fix-pr

/fix-pr restores a pull request's intended workflow outcome. It identifies the earliest causal failure, classifies its cause, applies the smallest durable repair, and verifies the repaired commit against every required check.

Local work and durable records

Use the filesystem protocol and python3 <skill-dir>/scripts/p2p_filesystem.py --repo <root> resolve .p2p/work/<slug>/contract.md to resolve paths. Save reports with save .p2p/work/<slug>/contract.md <report-name> --from <file> to retain history before replacement.

When a canonical .p2p/work/<slug>/contract.md applies, discover its saved candidate and reports in .p2p/work/<slug>/. Save diagnosis, repair outcome, retained safe evidence, and exact old/new candidate identities to .p2p/work/<slug>/ci-repair.md, preserving prior records under the protocol retention rule. Put disposable logs in .p2p/tmp/; retain needed evidence before claiming a handoff. Redact secrets, and use the protocol durable reference and checksum record for evidence unsuitable for Git. Local report saving alone does not grant Git authority; the explicit /fix-pr invocation authority below remains separate. Candidate changes require fresh review/proof; never rewrite old verdicts.

Invocation

Accept one repository target:

• /fix-pr #123
• /fix-pr https://github.com/acme/project/pull/123
• /fix-pr <workflow-run-url>

Infer the relevant workflow from a pull request or workflow run whenever the target makes that possible.

Guardrails

Before editing, inspect the branch and worktree. Continue only when the current branch and commit identify the target PR head or workflow commit, and the worktree has no unrelated changes. Stop with NOT FIXED when the target cannot be established, credentials or permissions are unavailable, or the branch state makes the repair ambiguous.

Commit only the scoped repair, push only the target PR head branch, and never force-push.

Bind diagnosis and verification to the exact target commit SHA. If the PR changes during the repair, stop and re-establish the target rather than silently chasing the newer commit.

For fork or otherwise untrusted PRs, do not expose secrets, approve privileged workflow execution, broaden permissions, or weaken isolation. Stop with NOT FIXED when the required verification depends on an unavailable safe execution path.

Preserve the verification boundary that exposed the failure:

• Keep every required job, test, assertion, lint/type check, coverage threshold, CI matrix entry, and failure condition. Replace an incorrect or obsolete check only under the evidence rule in Forbidden repairs.
• For a workflow-only repair, require the same quality checks to run with the same failure semantics.
• Add or strengthen a focused regression test for a product or test defect when the repository has a suitable seam. Use an independent behavioral assertion, not a copy of the implementation's calculation.
• Keep fixes scoped to the failure. A rerun is evidence, not a repair.

Workflow

1. Establish the intended operation

Determine what the failed workflow was meant to guarantee, such as validating the PR branch before merge or running required checks for a specific commit. Define success from that guarantee.

Read the acceptance contract protocol and the linked ticket and acceptance contract when they define the behavior under repair. Preserve the revision, requirement IDs, promised results, boundaries, agreed seams, and independent oracles. If that contract is unavailable or ambiguous, continue only with repairs whose correctness does not depend on guessing the missing requirement. Report the gap; a CI failure does not authorize changing the ticket's promises.

2. Diagnose before editing

Inspect the workflow run, failed jobs and steps, logs, workflow YAML, relevant changes, and the target PR's branch-protection or ruleset-required checks. Start at the earliest causal failure, then look for independent failures in parallel jobs. Record the workflow, job, step, command, and observed error.

Choose local reproduction, a pushed GitHub Actions run, or both by expected evidence per unit of clock time, context cost, and compute cost. Use local checks when they isolate the cause quickly; prefer the authoritative remote workflow when it is environment-specific or expensive to reproduce locally. Use existing artifacts and focused static inspection when they answer the question; avoid equivalent duplicate runs.

Classify the primary cause before changing anything:

• PRODUCT: branch code, test target, or generated output is wrong.
• WORKFLOW: GitHub Actions configuration, permissions, or job wiring is wrong.
• EXTERNAL: dependency, runner, credential, or service is unavailable.

For EXTERNAL, do not change product or workflow code to compensate for the unavailable capability. Resolve the external condition only when it is authorized and independently verifiable; otherwise return NOT FIXED.

Treat flakiness as a confidence modifier. A rerun without a relevant change ends as NOT FIXED — WORKFLOW GREEN — FLAKE NOT RESOLVED until nondeterminism is understood.

3. Repair and verify

Apply the smallest complete repair at the layer that owns the failure. Keep required checks and their failure semantics, subject to the evidence rule in Forbidden repairs. For product and test defects, add or strengthen the focused regression evidence before declaring success.

Map product or test repairs to the affected requirements and their observable results. Record replacement evidence and why it still checks the same promise. Keep unrelated acceptance gaps visible without expanding this CI repair into a full implementation or proof run.

Run the cheapest high-signal verification first, whether local or remote. Use the authoritative GitHub workflow as the primary verification when it is the more efficient evidence source; run broader local checks only when their additional evidence justifies the cost. Verify every required check reported by the target PR's branch protection or ruleset, not only the original failed job. For a workflow-run target, use its associated PR when available; otherwise verify every check represented by the run and state that branch-protection requirements could not be established. Count a required check only when it succeeds for the exact repaired SHA. Pending, queued, cancelled, timed-out, skipped, missing, or stale results are not successful verification. Use the environment's waiting mechanism when one is available; do not invent polling intervals, wait budgets, or repair-attempt caps. Without a waiting mechanism, return NOT FIXED — VERIFICATION PENDING with the run URLs. Stop when the cause is uncertain, a required capability is unavailable, the repair would weaken quality, or the repair introduces an unexplained quality regression. Confirm that the repaired commit is pushed and all required signals remain measurable.

Forbidden repairs

Keep the required quality signal measurable. Do not delete or skip tests, disable lint rules, lower coverage, make checks optional, swallow failures, add unconditional continue-on-error, add arbitrary retries, or comment out workflow steps. A check may change only when the source contract and evidence prove it incorrect or obsolete. The replacement must provide stronger valid evidence for the same promised behavior. Record the reason and affected requirement IDs; changing a check does not authorize changing the promise.

Do not redesign workflows, clean up unrelated code, or use a green rerun to mask an unresolved failure.

Completion

Return one of these outcomes:

• FIXED: the cause is understood, a durable repair and focused verification pass, required quality signals are preserved or strengthened, the repaired commit is pushed, and all required checks for the target are green.
• NOT FIXED: the failure remains unresolved, required capability is unavailable, the worktree is unsafe, the repair would weaken quality, or only an unexplained rerun passed.

FIXED means the workflow is repaired. It does not mean every ticket requirement is proven.

For either outcome, report the intended operation, failure classification, earliest causal error, files changed, verification performed, required-check status, and the remaining reason when NOT FIXED. Include the repaired SHA, affected requirement IDs, replaced evidence, and any acceptance gaps. Record the preserved contract revision when one exists. Any changed candidate leaves prior proof tied to the old candidate. Changes to product behavior, acceptance evidence, or relevant tests require fresh /prove against every requirement before acceptance. Green CI cannot refresh proof. Identify stale proof and review results, and hand off to /prove and the repository's review process when those steps are requested or required.

Invoking /fix-pr authorizes scoped inspection, edits, commit, push, and workflow reruns for the target PR or workflow run. It does not authorize force-pushes, changes outside the target branch, or workarounds that weaken verification.

End with Next steps: and a numbered list (1., 2., ...) of applicable actions in order, so each can be referenced by number. For FIXED, refresh stale reports with the applicable invocation below; when both match, give /merge-readiness <PR URL> with the saved report references.

/prove <saved contract>; candidate <repaired SHA>
/review-implementation <repaired candidate> against <comparison base>

For NOT FIXED, give the exact failed check command from the workflow and its observed failure, or name the specific missing input or human decision. Do not claim acceptance or merge authority.