Fix a failing pull request

Take a red pull request and make the checks pass. This skill ends after you commit a fix to the branch and push it. Confirming the result belongs to watch-pr, and merging belongs to merge-pr.

A guard hook runs alongside. It refuses a log sweep that goes around the diagnosis below, while leaving one job's full log open to read, because that's the real next step once the printed tail runs short.

Which pull request

$ARGUMENTS names the pull request number when the caller knows it. An empty value means whatever is open for the current branch.

Step 0: the checklist

Track these steps with the session's task-list tools where it carries them. Newer harnesses leave those tools out by default, and a session without them works the list in order as written.

1. Diagnose the failures
2. Reproduce each one locally
3. Fix the cause
4. Commit through the commit skill
5. Bring the description forward
6. Push and hand back

Step 1: diagnose

bash .claude/skills/fix-pr/scripts/diagnose.sh <number>

One call gets the failing jobs, the tail of each failing step's log, and the local task the script maps each job to. Read that output before running anything else. Going straight to gh run view repeats work the script already did.

The script also compares the local checkout against the commit CI tested. Stop when it reports a mismatch. The logs then describe code this worktree no longer carries, so a fix aimed at them reaches the wrong revision. Check out the branch the pull request names, or pull it forward, and diagnose again.

Step 2: reproduce

Run the task the script named for each failure. Reproducing first is what separates a fix from a guess.

The mapping from job name to task is a guess, so treat a task that passes locally as a signal rather than a contradiction. Look for the explanation among these:

• The job runs something the task doesn't. Read the workflow.
• The failure depends on the environment, such as a pinned tool version or a container image the worktree isn't running.
• The failure is a flake, which makes the run worth repeating before anything changes.
• A stale branch. CI tested it merged with a base this worktree doesn't have, and the gate that fails arrived on that base. Nothing here reproduces it until the branch moves, so run the rebase skill and diagnose again.

Say which one applies rather than editing until the symptom moves.

Recognizing that last shape matters, because it produces a failure no commit on the branch caused. The base added a gate and the branch added something that gate rejects, so neither side was red alone. Running the gates against the combined tree is what the rebase skill's verification step is for.

Step 3: fix the cause

Change what made the check fail, and nothing else. A red pull request is a poor moment for adjacent cleanup: it widens the diff a reviewer already has questions about, and it hides the fix inside unrelated edits.

Where a lint gate failed, the finding names the file and the line, and often the replacement too. Apply it exactly. Where a test failed, read the assertion before changing either side, because a test that caught a real defect deserves the fix on the other side.

Never silence a gate to make it pass. Excluding a path changes the project's standards, and so does a new rule exception or a lowered threshold. Any of those goes to the operator as a proposal rather than into the commit.

Re-run the reproducer until it passes.

Step 4: commit

The caller decides how the fix reaches the branch. $ARGUMENTS holds that answer when pr routed here, and where it doesn't, ask before committing with AskUserQuestion: question set to How should this fix land?, header set to Fixes, multiSelect set to false, and these options:

Label	Description
Separate commit	The fix lands as its own commit. History keeps the record of what broke.
Amend and force-push	The fix folds into the commit that caused it, pushed with --force-with-lease.

Either way, the commit skill takes it from there, and it writes the message and runs the review and the gates exactly as it always does. One thing changes for an amend: pass --amend after the repository root when invoking review-commit-message, so it reads git diff --cached HEAD~1 rather than the staged delta. Skip that and the reviewer judges a whole message against a partial diff, returning findings that look certain and are wrong. Where the fix splits into unrelated groups the commit skill says so and takes them one at a time, which suits a separate commit better than an amend.

Step 5: bring the description forward

The description is on GitHub at this point, and often nothing sits on disk. Fetch it back before revising it:

bash .claude/skills/fix-pr/scripts/populate-description.sh <number>

That rebuilds PR_AGENTDESC.md from what the pull request currently says, reassembling the frontmatter from the properties set on the pull request. It refuses to overwrite an existing draft without --force, because a pr workflow further up the stack may have one in flight.

A fix changes what the branch does, so the published description now describes a branch that has moved. Where the change is worth a reader's attention, invoke write-pr-description with the repository root and a note saying which commits arrived since the last publish.

Then invoke review-pr-description and loop on its verdict the same way the pr skill does, bounded at three rounds. Publish the result with bash .claude/skills/pr/scripts/create-pr.sh, which updates the open pull request rather than opening another.

Skip this where the fix left the description accurate. A typo in a lint rule rarely changes what the branch is for. Say which way you judged it.

Don't edit PR_AGENTDESC.md here. A guard hook refuses it, and the writer owes the validator a clean run that hand-editing skips.

Step 6: push and hand back

A separate commit pushes normally:

git push origin HEAD

An amend rewrote the branch, so it needs the lease:

git push --force-with-lease origin HEAD

Never a bare --force. A guard hook refuses it, because the lease is the difference between replacing your own commit and discarding whatever arrived while you worked.

Report what failed, what caused it, and what the fix changed. Then say the checks are running again.

Where the caller asked for a fix and nothing more, stop here. Where the caller asked to see it through, invoke watch-pr with the same number and repeat from step 1 on a fresh failure.

Bound the loop. After three rounds on the same check, stop, then report what each attempt changed and why the check still fails. A fourth attempt at the same shape of fix is rarely the one that works.

Preconditions

• gh installed and authenticated
• the pull request's branch checked out, so a fix reaches the code CI tested
• the commit skill deployed alongside this one