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.

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
• If it exits 2: stop and report “No relevant issues found (no bug-type PR found).”

1. Checkout the PR branch:

• gh pr checkout

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

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

1. Commit + push:

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

1. 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 --mark-fixed
• If all bug items are fixed, the PR body will be updated to Status: fixed.

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: graysurf
• Source: graysurf/agent-kit
• License: MIT

Install and usage instructions live in the source repository linked above.