---
name: fix-bug-pr
description:
  Find bug-type PRs with unresolved bug items (Issues Found table), fix and push updates, comment with what changed, and keep PR body status
  synced (set to fixed when complete).
---

# 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.

## Test-First Evidence Gate

- Before editing production behavior, capture failing-test evidence or an explicit waiver.
- This gate applies before editing production behavior.
- For bug items, prefer a focused failing regression, unit, integration, or acceptance test that demonstrates the unresolved issue.
- Record the command, exit code, failing test file/name, and concise failure summary before production edits.
- If no failing test is practical, record why, what substitute validation will run, and the residual risk.
- PR comments/body updates must include `Change classification`, `Failing test before fix`, `Final validation`, and `Waiver reason` when
  applicable.

## Workflow

1. Resolve the target PR:
   - Auto-pick an open PR with unresolved bug items:
     - `$AGENT_HOME/skills/automation/bug/fix-bug-pr/scripts/bug-pr-resolve.sh`
   - Or target a specific PR:
     - `$AGENT_HOME/skills/automation/bug/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:
   - Capture the Test-First Evidence Gate before production edits.
   - 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:
     - `$AGENT_HOME/skills/automation/bug/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/bug/fix-bug-pr/references/COMMENT_TEMPLATE.md` as the structure.
