fix-bug-pr

Fix Bug PR

Contract

Prereqs:

• Run inside the target git repo.
• git and gh available on PATH, and gh auth status succeeds.
• python3 available on PATH (helper scripts parse/patch PR Markdown deterministically).
• Start from a clean working tree (avoid staging unrelated local changes).

Inputs:

• Optional PR number to operate on; otherwise resolve an open bug-type PR automatically.
• Optional label filters to narrow candidate PRs (defaults: bug, type: bug).

Outputs:

• If a matching PR exists:
  • Code fix committed and pushed to the PR head branch.
  • PR comment describing what changed, tests run, and which bug IDs were updated.
  • PR body updated so the Issues Found table reflects latest bug Status; if all bugs are fixed, set overall Status: fixed.
• If no bug-type PR exists (or none with unresolved bugs): no repo changes; report “no related issues”.

Exit codes:

• N/A (workflow skill). Helper scripts define their own exit codes.

Failure modes:

• No matching bug-type PR found, or PR body does not include a parseable ## Issues Found table.
• Missing tooling (gh/git/python3) or gh not authenticated.
• Dirty working tree, merge conflicts, or failing tests prevent a safe commit/push.
• High-risk areas (auth/billing/migrations/deploy) should stop or be skipped.

Workflow

1. Resolve the target PR:

   • Auto-pick an open PR with unresolved bug items:
     • $CODEX_HOME/skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh
   • Or target a specific PR:
     • $CODEX_HOME/skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh --pr <number>
   • If it exits 2: stop and report “No relevant issues found (no bug-type PR found).”

2. Checkout the PR branch:

   • gh pr checkout <number>

3. Identify the next unresolved bug item:

   • Use next_bug_id from bug-pr-resolve.sh output.
   • Fix one bug item per run unless multiple items share the same root cause.

4. Implement the minimal fix + validation:

   • Prefer small, targeted diffs; avoid refactors.
   • Follow the target repo’s testing/build docs and CI workflow: install required tooling/deps, then run the most relevant lint/test/build commands.
   • If docs are missing/unclear, infer likely commands from common entrypoints (package.json scripts, Makefile/Justfile/Taskfile, language defaults).
   • Treat validation as a gate: if checks fail, do not commit/push; fix and re-run (or stop and report). If checks cannot be run, document why in the PR comment.

5. Commit + push:

   • Use semantic-commit-autostage (end-to-end automation) unless the user explicitly wants manual staging.
   • Push to the PR head branch.

6. Update PR body progress (status sync):

   • Mark the fixed bug ID(s) as fixed and recompute overall status:
     • $CODEX_HOME/skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh --pr <number> --mark-fixed <bug_id>
   • If all bug items are fixed, the PR body will be updated to Status: fixed.

7. Comment on the PR with what changed:

   • Include: fixed bug IDs, summary, tests run, and any remaining open items.
   • Use skills/automation/fix-bug-pr/references/COMMENT_TEMPLATE.md as the structure.