PR Pilot — PR Submission & Lifecycle Management#

Overview#

Submit professional-quality pull requests and manage them through the full review lifecycle until merge (or closure). Covers PR creation, CI monitoring, review response, iteration, and tracking.

Use cases: Open-source contributions, team code reviews, multi-repo PR management, any code submission workflow.

Prerequisites#

GitHub CLI must be authenticated — PR creation, review monitoring, and commenting all require it:

bash

gh auth status   # Must show "Logged in"

If not configured, ask the user to provide:

1. GitHub username — used for --head {username}:{branch} and PR search
2. GitHub token — run gh auth login or set export GH_TOKEN=<token>

Token is required for: creating PRs, posting comments, checking review status, pushing iterations.

Part 1: Submit the PR#

Step 1: Stage & Commit (if not done)#

bash

# Stage specific files — never use git add .
git add {specific files}
git diff --cached --stat   # Verify

# Commit with conventional message
git commit -m "{type}({scope}): {description}"

Step 2: Push to Remote#

bash

git push origin {branch-name}

# If this is a new branch:
git push -u origin {branch-name}

Step 3: Write PR Description#

Use this structured template. Adapt sections based on PR type and scope.

markdown

## Summary

{1-2 sentence overview of what this PR does and why}

Closes #{issue_number}.

## Problem

{Description of the bug/issue being fixed:}
- What users experience
- Root cause analysis
- Impact / severity

## Solution

{Technical description of the approach:}
- Architecture / design decisions
- Key abstractions introduced (if any)
- Why this approach over alternatives

## Changes

| File | Change |
|------|--------|
| `path/to/file.py` | **New** — Description |
| `path/to/other.py` | Modified — Description |
| `tests/test_file.py` | **New** — N tests for feature |

## Testing

{paste test output} N passed in X.XXs

text

{Describe what was tested:}
- Unit tests for ...
- Edge cases covered: ...

## Backward Compatibility

- No breaking changes / Breaking changes in ...

Adaptation by PR type

PR TypeFocus SectionsSkip/MinimizeBug fixProblem + Solution + TestingDesign Decisions (unless non-obvious)FeatureAll sections + Extensibility Example—Security fixDefense-in-depth, bypass scenarios, residual risk—RefactorMotivation, before/after comparisonProblem (reframe as "improvement")

Step 4: Create the PR#

bash

# Save description to a temp file
cat > /tmp/pr_body.md << 'EOF'
{pr description}
EOF

# Create PR
gh pr create \
    --repo {owner}/{repo} \
    --head {username}:{branch} \
    --base {default-branch} \
    --title "{type}({scope}): {description}" \
    --body-file /tmp/pr_body.md

Step 5: Verify#

bash

# Check PR was created
gh pr view {number} --repo {owner}/{repo} --json url,state,statusCheckRollup

# Verify CI is running
gh pr checks {number} --repo {owner}/{repo}

PR Description Quality Checklist#

• Links to the issue being fixed (with Closes #N)
• Explains root cause, not just symptom
• Describes solution approach and design decisions
• Includes test results
• Has file change summary table
• Addresses backward compatibility

---

Part 2: Manage the PR Lifecycle#

2a. Monitor PR Status#

Check status periodically:

bash

# Single PR
gh pr view {number} --repo {owner}/{repo} \
    --json state,reviews,comments,mergeable,statusCheckRollup

# All your open PRs
gh search prs --author={username} --state=open \
    --json repository,number,title,url,updatedAt

2b. Respond to Reviews#

When a reviewer provides feedback, classify and respond:

Pattern 1: Actionable Code Fix

Reviewer: "This should handle the null case" / "Add error handling for X"

Action: Fix code → add test → push → reply.

text

Good catch — fixed in {commit_sha}. Added null check and a test case for this scenario.

Pattern 2: Architecture Concern

Reviewer: "This approach is fundamentally flawed because..."

Action: If fundamental, consider full rearchitecture.

text

You're absolutely right — {acknowledge specific concern}. I've rearchitected this in #{new_pr_number}:

{Brief description of new approach}

Closing this PR in favor of the new approach.

Steps for major rework:

1. Create new branch from upstream
2. Reimplement with new approach
3. Create new PR referencing the old
4. Close old PR with comment pointing to new one
5. Reply to reviewer on new PR

Pattern 3: Style / Convention Nit

Reviewer: "We use camelCase here" / "Please add docstring"

Action: Quick fix → push → reply.

text

Fixed in {commit_sha}, thanks for pointing out the convention.

Pattern 4: Question / Clarification

Reviewer: "Why did you choose X over Y?"

Action: Explain clearly. If they suggest a better approach, adopt it.

text

{Direct answer}. {Trade-off explanation}.

Pattern 5: Request for Tests

Reviewer: "Can you add a test for the edge case where...?"

Action: Write test → verify → push → reply.

text

Added in {commit_sha}. The new test covers:
- {scenario 1}
- {scenario 2}

Iteration Workflow#

bash

cd ~/prs/{repo}
git checkout {branch}
git pull origin {branch}

# Make changes based on review
# ...

# Run tests
python -m pytest --tb=short

# Commit and push
git add {files}
git commit -m "address review: {description}"
git push origin {branch}

2c. Handle CI Failures#

bash

gh pr checks {number} --repo {owner}/{repo}

CI ResultActionFailure in your codeFix and pushPre-existing/flaky failureComment on PR noting itCI needs configCheck CONTRIBUTING.mdMerge conflictsgit fetch upstream && git rebase upstream/main, resolve, force push

2d. Track Progress#

Maintain {workspace}/pr-tracker.md for multi-PR management:

markdown

# PR Campaign Tracker

> Last updated: {date}

| # | Repository | PR | Title | Status | Issue |
|---|------------|-----|-------|--------|-------|
| 1 | owner/repo | [#N](url) | fix(x): desc | 🟢 Open | #N |
| 2 | ... | ... | ... | 🟣 Merged | #N |

Status icons:

• 🟢 Open — Waiting for review
• 🟡 Changes Requested — Needs iteration
• 🔵 Approved — Ready to merge
• 🟣 Merged
• 🔴 Closed (not merged)

Update the tracker after each PR event (creation, review, iteration, merge, close).

---

Review Response Principles#

1. Reply to every comment — even if just "Done" or "Good point, fixed"
2. Thank the reviewer in your first response to a review round
3. Never argue — explain once, then defer to the maintainer
4. Be specific — reference commits, line numbers, test names
5. Respond promptly — within 24-48 hours keeps momentum
6. Update PR description if the approach changed significantly

Output#

• PR URL, CI status verified
• Review responses and iterations
• Updated pr-tracker.md

Tips#

• In a development pipeline, this follows dev-test and is the final delivery step.
• For managing a portfolio of PRs, run the status check periodically (or set up an automation).
• When responding to architecture concerns, creating a fresh PR (instead of force-pushing a rewrite) keeps the review history clean and makes reviewers' jobs easier.
• Always run tests locally before pushing review iterations.