PR Fix

Overview

Streamline the workflow for addressing PR review comments. This skill:

• Auto-detects the PR from the current branch (or accepts PR number/URL as argument)
• Fetches all unresolved review threads (review comment threads)
• Guides through fixing each issue
• Posts reply comments properly threaded to the original review comment
• Resolves threads after replies are posted

Non-interactive Defaults (Important)

• Run end-to-end without confirmation prompts. Treat invoking /pr-fix as permission to:
  • Apply fixes
  • Run required self-checks from AGENTS.md before irreversible actions when code changes exist
  • Create local commits as needed while processing threads
  • Perform exactly one final push after all fixes (and PR body update when required) are complete
  • Reply to review comments and resolve threads after the final push succeeds (or immediately when no push is required)
• Only ask the user when blocked (e.g., PR cannot be identified, auth/tools missing, or stash restore conflicts).

Workflow

1. Identify the PR

   • Determine owner and repo for all subsequent API calls:
     • If the user provides a PR URL, parse owner and repo from it (e.g. https://github.com/<owner>/<repo>/pull/<number>).
     • Otherwise, determine owner and repo from git remote get-url origin (or another selected remote if origin is missing).
     • Fork workflow note: if an upstream remote exists and points to a different GitHub repo than origin, also capture upstream_owner/upstream_repo from git remote get-url upstream (PRs are often opened in the upstream repo).
   • If the user provides a PR URL, parse pull_number from it and use the parsed owner/repo.
   • If the user provides a PR number (without a URL), set pull_number and resolve which repo it belongs to:
     • If upstream_owner/upstream_repo are available, try resolving the PR number against the upstream repo first (preferred):
       • Prefer a lightweight PR metadata fetch (via GitHub MCP if available, otherwise gh pr view <pull_number> --repo <upstream_owner>/<upstream_repo>).
       • If it exists, use <upstream_owner>/<upstream_repo> for all subsequent API calls (fetch/reply/resolve).
       • Otherwise, fall back to <owner>/<repo> (derived from the selected remote).
     • If no upstream remote is available, use <owner>/<repo>.
   • Otherwise, detect from the current branch:
     • Get the current branch: git rev-parse --abbrev-ref HEAD
     • Use GitHub MCP list_pull_requests with:
       • owner: <owner>
       • repo: <repo>
       • state: open
       • head: <owner>:<branch> (if the branch lives on a fork, use <fork_owner>:<branch>)
     • If multiple PRs match, choose the one whose head ref matches exactly; otherwise ask the user.
     • Fork workflow note: if upstream_owner/upstream_repo are available, query list_pull_requests against the upstream repo first with head: <fork_owner>:<branch>, then fall back to querying the origin repo.
   • If no PR is found, ask the user to specify one.
   • Ensure you're on the PR head branch locally before editing:
     • Prefer: gh pr checkout <pull_number>
   • Keep commits clean without prompting:
     • If the working tree is dirty, auto-stash before making fixes:
       • git stash push -u -m "pr-fix: auto-stash before applying review fixes"
     • After all fixes/replies/resolutions are complete (and final push when required), restore it:
       • git stash pop
       • If restore conflicts, report and stop (do not force-resolve silently).

2. Fetch unresolved review threads

   • Use GitHub MCP pull_request_read with method: "get_review_comments".
   • Paginate with after and perPage until pageInfo.hasNextPage is false:
     • Use the response pageInfo.endCursor as the next request's after.
   • This method returns review threads (not a flat list of comments) with metadata like ID and IsResolved.
   • Filter to only unresolved threads (IsResolved: false).
   • Extract priority badges (P1/P2/P3) from the top-level comment body if present.
   • For each thread, record:
     • threadId: thread ID
     • commentId: extract from the top-level comment URL (parse digits from discussion_r<id>)
     • path and line: from the top-level comment Path / Line (or thread-level Path / Line if that's what the API returns)
   • Never rely on path+line for identity; line numbers drift after edits. Prefer commentId.

3. Display unresolved threads

   • Show a numbered list with:
     • File path and line number
     • Priority badge (if any)
     • commentId (reply target)
     • First 2-3 lines of the comment body
     • Author
   • If no unresolved threads, report success and exit.

4. Proceed with all threads by default

   • Do not ask which threads to handle.
   • Do not ask for confirmation to commit/push/reply/resolve.
   • Address all unresolved threads sequentially.
   • Only if the user explicitly requests it, switch to:
     • Select specific threads by number
     • Dry run (show what would be done without executing)

5. Apply root-cause-first triage before editing

   • Follow Cause over Symptom: do not default to symptom-only patching.
   • For each thread, explicitly evaluate:
     • comment -> observed behavior -> root-cause hypothesis -> verification signals -> fix strategy -> recurrence prevention
   • If the issue requires broad structural changes, identify it as a large-scope change when any of the following is true:
     • Changes span multiple modules/directories
     • Public interfaces or external contracts/compatibility are affected
     • Test strategy requires substantial redesign
   • When a large-scope change is identified:
     • Do not start implementation/commit/reply/resolve/push for that item yet
     • Present a concrete plan and wait for explicit user approval before proceeding

6. For each thread: a. Show full context

   • Display the complete comment
   • Read the relevant file and show surrounding code

   b. Implement the fix

   • Apply code changes as needed
   • If no code change is needed (acknowledgment only), note this
   • If code changes were made, run self-checks according to AGENTS.md before committing:
     • Follow Self Check & Fix Flow and related build/test command guidance for the project type
     • Repeat until checks are clean
     • Run the $codex-review skill for every code-changing thread (follow the $codex-review skill loop until clean, up to its max retry count)
   • After self-check passes, commit locally as needed (do not push yet):
     • Stage the intended changes (after auto-stash, git add -A is typically fine)
     • Commit with a concise, diff-based message

   c. Prepare the reply payload

   • Draft the reply text for this thread and keep it pending until after final push.
   • Do not post reply comments before push when fixes must be published.
   • Store commentId + reply body for the post-push phase.
   • Reply templates:
     • Code fix: "Fixed: "
     • Acknowledgment: "Acknowledged. "
     • Won't fix: "Won't fix: "
   • Keep wording factual and concise; avoid asserting actions that were not performed.

   d. Queue thread resolution

   • Queue threadId for resolution after the reply is posted in the post-push phase.
   • Do not resolve threads before the final push when fixes must be published.

   e. Move to next thread

7. Finalize PR metadata when needed (before final push)

   • If changes affect behavior/spec/test expectations, update PR body once at the end (not per thread).
   • If no such impact exists, keep PR body unchanged.

8. Perform one final push when required

   • If local commits exist that are not yet on the PR branch, push once before any reply/resolve actions:
     • git push (or git push -u origin HEAD if needed)
   • If no new local commits were created (e.g., acknowledgment-only handling), skip push and continue.
   • If this final push is required and fails, stop immediately and report the error (do not post reply comments or resolve threads).

9. Post replies and resolve threads

   • After successful final push (or skipped push when no code publication is needed), process each pending thread:
     • Post the queued reply to the top-level review comment (commentId)
     • Resolve the corresponding thread (threadId) after reply succeeds
   • Prefer GitHub MCP tools when available; otherwise use gh:
     • Prefer GitHub MCP if your toolset exposes a tool to reply to a pull request review comment.
     • Otherwise, use gh to reply to the top-level review comment (commentId):

       gh api repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies \
         -f body="<reply message>"
       

     • Prefer GitHub MCP if your toolset exposes a tool to resolve review threads.
     • Otherwise, use gh and the thread threadId:

       gh api graphql -f query='
         mutation($threadId: ID!) {
           resolveReviewThread(input: {threadId: $threadId}) {
             thread { isResolved }
           }
         }
       ' -f threadId="$THREAD_ID"
       

     • If resolve fails (permissions, thread already resolved/outdated), report it and continue.

10. Report completion

• Number of threads addressed
• Number of threads remaining (if any)
• Number of local commits created
• Mention whether final push was required and whether it completed
• Mention whether PR body was updated
• Mention reply/resolve status for processed threads
• Mention self-check status for code-changing threads
• Mention whether an auto-stash was restored (or why it was not)

Dry Run Mode

When dry run is explicitly requested:

• List all unresolved threads with full details
• For each thread, describe what action would be taken
• Do NOT make any API calls to post replies or resolve threads
• Do NOT modify any files

Reply Comment Guidelines

• Keep replies concise (1-2 sentences)
• Focus on what was done, not why the reviewer was right
• For code changes: reference the specific fix (e.g., "Added null check before accessing property")
• For acknowledgments: be brief (e.g., "Good catch, updated.")
• For won't fix: explain the reasoning clearly
• Do not include pipeline/trigger rationale in replies unless explicitly asked
• Post replies only after the relevant code is already published (or when no publication is needed)

Edge Cases

• Comment requires no code change: Queue acknowledgment, skip push if no new commits exist, then post reply and resolve
• New reviews added during session: Re-fetch threads before processing next item
• API rate limiting: Pause and retry with backoff
• Thread already resolved: Skip and move to next (only if IsResolved is available)
• Multiple comments in thread: Reply to the first (top-level) comment only
• Line numbers drifted: Match by commentId (derived from the comment URL) or comment URL, not by path+line.
• PR body update needed: Apply one consolidated update at the end before the final push

Error Handling

• If GitHub MCP tools are unavailable, ask the user to enable the GitHub MCP server and retry
• If PR detection is ambiguous, ask the user for the PR URL/number
• If fetching review threads fails, show the error and suggest using the PR URL as fallback context
• If final push fails, stop and report the push error without posting replies/resolutions
• If reply fails, show the error and continue with the next queued thread (do not resolve threads you did not successfully reply to)
• If gh is required but unavailable or unauthenticated, ask the user to install/login (or fall back to replying/resolving in the GitHub web UI)

Examples

Basic usage (auto-detect PR)

/pr-fix

Specify PR by number

/pr-fix 38

Specify PR by URL

/pr-fix https://github.com/owner/repo/pull/38

Dry run

/pr-fix --dry-run