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

- [x] FilterAdapter interface designed and documented
- [x] 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