Create PR

Overview

Create a pull request on GitHub from a feature branch, automatically populating PR title and description with work item metadata. Links PR to the associated work item and facilitates smooth transition to review phase.

When to Use

Create a PR when:

• Implementation is complete and tested locally

• Feature branch is synced with main and ready for review

• Work item status is testing (or ready for code review)

• PR does not already exist for the branch

• Ready to solicit code review and feedback

When NOT to Use

Skip creating PR for:

• Work still in progress (use [[update-work-item/SKILL]] to track, submit PR later)

• Exploring experiment branches (keep as WIP, don't create PR)

• Pushing emergency hotfixes (create PR directly via GitHub UI or gh pr create manually)

Frontmatter Fields in Work Item

When work item status transitions to testing , [[create-pr/SKILL]] is invoked automatically. It reads:

title: "Implement FilterAdapter" id: 60 status: testing feature_branch: feature/60-filter-adapter # Set by feature-branch-management related_commit:

• 6d8c044 # feat(sdk): initial FilterAdapter interface
• f00459b # feat(filters): implement selectattr and map notes:
• timestamp: 2024-06-01T12:00:00Z user: @john note: | Implementation complete. All filters implemented with type signatures. Awaiting code review and merge.

Uses these fields to construct PR title and description.

Workflow: Creating a Pull Request

1. Verify Preconditions

Before creating PR, verify:

• Feature branch exists and is pushed to remote

• Branch is synced with main (no conflicts)

• Work item status is testing (or equivalent ready state)

• No PR already exists for this branch (check GitHub)

2. Generate PR Title

PR title is auto-generated from work item:

Format: <work-item-id>: <work-item-title>

Examples:

60: Implement FilterAdapter #59: Fix elif parsing edge case #61: Evaluate expression engines

Customization: User can override title if provided.

3. Generate PR Description

PR description is auto-generated from work item and commit history.

Template:

Work Item

Closes #<id> - <title> See: backlog/<id>_<slug>.md

Summary

<work_item_notes excerpt (first 200 chars)>

Implementation Details

<commit messages from related_commit in chronological order>

Commits

• <commit hash>: <message>
• <commit hash>: <message> ...

Testing

<test_results if recorded>

Acceptance Criteria

<acceptance criteria from work item body>

Related Work

<dependencies if any>

Example:

Work Item

Closes #60 - Implement FilterAdapter See: backlog/60_implement_filter_adapter.md

Summary

Implements core filtering operations for FilterAdapter. Supports filtering sequences by attribute value and projection.

Initial focus: selectattr and map filters.

Commits

• 6d8c044: feat(sdk): initial FilterAdapter interface
• f00459b: feat(filters): implement selectattr and map
• a1b2c3d: docs: add filter usage examples

Testing

Local: All 47 tests pass, coverage 89% CI: Pending review

Acceptance Criteria

• FilterAdapter interface designed and documented
• selectattr and map filters implemented
• Integration tests pass (pending CI)
• Code review approved

Related Work

• Dependency: 54 (complete temple_native)

Customization Options

1. Title Override

Allow user to provide custom title:

Input option:

custom_title: "feat: add FilterAdapter with selectattr and map support"

Result: Uses custom title instead of auto-generated

2. Template Selection

Support different PR templates for different work item types:

Work item field:

pr_template: feature # or "bugfix", "spike", "refactor"

Result: Uses matching template from .github/PULL_REQUEST_TEMPLATE/

3. Draft PR

Create PR in draft mode for early feedback:

Input option:

draft: true

Result: PR created as Draft, marking work-in-progress

Can be marked ready-for-review later

Integration with PR Management

Linking to Work Item

PR description includes work item link:

Closes #60 See: backlog/60_implement_filter_adapter.md

Enables:

• GitHub auto-linking (PR references issue #60)

• Bidirectional traceability (work item ↔ PR)

• Auto-close on merge (if "Closes" used)

PR Fields

Created PR populates:

repository: squirrel289/pax base_branch: main head_branch: feature/60-filter-adapter title: "60: Implement FilterAdapter" description: <auto-generated from template> draft: false # or true if requested labels: [feature, testing] # Optional: auto-applied based on work item assignee: <creator> # Optional: auto-assign to work item creator reviewers: [] # Optional: can be specified in work item or PR template

PR URL

After creation, record in work item:

pr_url: "https://github.com/squirrel289/pax/pull/247" pr_number: 247

Related skill [[update-work-item/SKILL]] can be invoked to record these.

Workflow: From Work Item to PR

1. update-work-item ├─ Status: in_progress → testing └─ Invokes: create-pr skill

2. create-pr (automatic execution) ├─ Read work item metadata ├─ Verify branch exists and is synced ├─ Generate PR title and description ├─ Call pull-request-tool (via PR_MANAGEMENT_INTERFACE) └─ Create PR on GitHub

3. PR Created ├─ Title: "60: Implement FilterAdapter" ├─ Description: Auto-generated from work item + commits ├─ Base: main ├─ Head: feature/60-filter-adapter └─ Status: Open, ready for review

4. Record PR details (optional) ├─ update-work-item again to record pr_number and pr_url └─ Or: Work item maintains reference bidirectionally

Interaction Modes (Aspect)

This skill uses the interaction-modes aspect for consistent prompting and decision handling.

• Aspect: interaction-modes

• Decision point: confirm_pr_details

• Parameter: interaction-mode = yolo | collaborative

Error Handling

PR Already Exists

error: "PR already exists for branch feature/60-filter-adapter" existing_pr: "https://github.com/squirrel289/pax/pull/247" action: "Use existing PR or delete branch and create new PR"

Branch Not Found or Not Pushed

error: "Branch feature/60-filter-adapter not found on remote origin" action: "Push branch first: git push origin feature/60-filter-adapter" hint: "ensure feature-branch-management sync completed successfully"

Work Item Not in Testing Status

warning: "Work item #60 status is 'in_progress', not 'testing'" action: "Run update-work-item to transition to testing first" hint: "create-pr triggered automatically on status transition"

Branch Behind Main

error: "Branch feature/60-filter-adapter is behind main" action: "Sync branch first: feature-branch-management sync" hint: "ensure rebasing completed before PR submission"

Related Skills

See the dependency matrix in docs/SKILL_COMPOSITION.md for the canonical calling relationships.

• [[update-work-item/SKILL]]: Triggers PR creation when status → testing ; records pr_number and pr_url

• [[feature-branch-management/SKILL]]: Creates and syncs feature branch before PR creation

• [[pull-request-tool/SKILL]]: Backend for PR operations (via [[PR_MANAGEMENT_INTERFACE]])

• [[handle-pr-feedback/SKILL]]: Monitors PR for feedback and triggers rework if needed

• [[process-pr/SKILL]]: Full PR workflow (includes PR review, feedback, merge)

Tips & Best Practices

1. Commit History Quality

PR description includes commit history. Ensure commits are well-written:

Good commit messages

git log --oneline feature/60-filter-adapter ^main

Output:

a1b2c3d docs: add filter usage examples

f00459b feat(filters): implement selectattr and map

6d8c044 feat(sdk): initial FilterAdapter interface

[[create-pr/SKILL]] will extract these into PR description.

2. Work Item Notes

Keep work item notes concise and review-ready:

notes:

• timestamp: 2024-06-01T12:00:00Z user: @john note: | Implement FilterAdapter SDK with core filters (selectattr, map, join, default).

  Changes

  • temple/sdk/adapter.py: New FilterAdapter class
  • temple/sdk/filters.py: Core filter implementations
  • tests/test_filters.py: Comprehensive test coverage (95%)

  Testing

  • All 47 tests pass locally
  • Coverage 89% (target: 85%)

This becomes PR description. Keep it clear for reviewers.

3. Link Work Items

Ensure PR title includes work item ID:

Good: "60: Implement FilterAdapter" Good: "#60 - Implement FilterAdapter" Avoid: "Implement FilterAdapter" # No ID, harder to trace

Auto-generation handles this, but verify if customizing.

4. Draft PRs for Early Feedback

Use draft mode for work-in-progress or experimental PRs:

Input:

draft: true

Result: PR marked as Draft

Reviewers see it's not ready; no review requests sent

Mark ready-for-review when implementation completes

Debugging

PR Not Created Despite Invocation

Check:

• Work item status is testing (or ready state)

• Feature branch exists locally and on remote

• Branch is synced with main (no conflicts)

• GitHub authentication works (gh auth status )

• Repository has PR creation permissions

PR Description Looks Wrong

Check:

• Work item notes field is populated

• related_commit field lists implementation commits

• Commit messages are clear and follow convention

Customization Not Applied

Check:

• Custom options passed correctly (e.g., custom_title=... )

• Interaction mode is set (yolo vs collaborative)

• Template selection matches available templates in .github/PULL_REQUEST_TEMPLATE/

References

• GitHub PR API: https://docs.github.com/en/rest/ref/pulls

• Conventional Commits: https://www.conventionalcommits.org/

• PR_MANAGEMENT_INTERFACE: See tools/PR_MANAGEMENT_INTERFACE.md