Fix Bug

Fix Bug — Autonomous Bug-Fix Workflow

Loop-engineered workflow for GitHub bugs. A fixer agent implements and pushes; a separate reviewer subagent reads the diff and posts PR comments. The fixer never self-reviews.

Read Repo conventions below (and AGENTS.md / CONTRIBUTING.md at the repo root) before changing code.

Entry points

Invoke with either a bug issue or an existing PR. The agent detects where work left off and continues from there.

Fresh issue (no PR yet): read the bug report, reproduce or trace root cause, implement on a fix branch, open a PR, then enter the review loop.

Existing PR (work already started): check out the PR branch, read issue + PR context, then pick up at the right phase — fix failing CI, address an unaddressed reviewer round, or spawn the next review pass if CI is green.

Both paths converge on the same PR-centric review loop (Phase 3).

Repo conventions

Customize this section when copying the skill into a new repository. The orchestration phases below assume these conventions exist somewhere (here or in AGENTS.md).

• Agent guide: AGENTS.md or CONTRIBUTING.md at repo root — architecture, style, and workflow rules.
• Environment: how to run commands (e.g. uv run, npm run, poetry run). Never use system Python/Node unless the repo does.
• Tests: targeted test command for the touched area; full or fast suite command before PR is ready.
• Lint: formatter/linter/typecheck command(s) required before push.
• Branch naming: e.g. fix/<issue-number>-<short-slug>.
• Commit messages: imperative mood; Fixes #N in body when closing a bug issue.
• PR body: ## Issue links with accurate closing semantics (Fixes / Part of / Related to), summary, test plan.
• Fixer PR comments: brief comments explaining what changed and why (see Phase 2).
• Test policy: whether existing test assertions may be changed (many repos: add tests, don't change expected behavior without human review).
• Escalation label: label applied when the loop exhausts (e.g. needs developer attention).

pathmc (this repo)

• Environment: uv run for all commands. Never system Python.
• Tests: uv run pytest tests/test_<module>.py -x -v for targeted; make test-fast for full suite (skips MCMC).
• Lint: make lint (ruff, ruff-format, mypy, license checks via prek).
• Branch naming: fix/<issue-number>-<short-slug> (e.g. fix/149-non-gaussian-guards).
• Do not modify existing test assertions unless adding new tests or removing obsolete ones.

Phase 1: State detection

Resolve the work item, then determine current state.

Resolve issue and PR

# --- Entry: issue number ---
gh issue view $ISSUE_NUMBER --json title,body,state,labels,comments

# Find an existing PR for this issue (search title/body, not only "Fixes #")
gh pr list --search "#$ISSUE_NUMBER" --state all --json number,headRefName,state,title

# --- Entry: PR number (skip if you already have ISSUE_NUMBER) ---
gh pr view $PR_NUMBER --json number,title,body,state,headRefName,comments,statusCheckRollup,labels

# Linked issue: parse "Fixes #N" / "Closes #N" from PR body, or ask the user if absent

If started from a PR, check out its head branch before changing code:

gh pr checkout $PR_NUMBER

Inspect PR state

Round markers use the prefix fix-bug-round (HTML comments). Fixer summaries use fix-bug-fix-summary. Approval uses fix-bug-approved. Use the same prefixes in every repo copy of this skill so resume logic stays portable.

# Count review-round markers from automated reviewer:
gh pr view $PR_NUMBER --json comments -q \
  '[.comments[].body | select(test("fix-bug-round"))] | length'

# Approval marker (distinct from reviewer crash — no comment at all):
gh pr view $PR_NUMBER --json comments -q \
  '[.comments[].body | select(test("fix-bug-approved"))] | length'

# CI status:
gh pr checks $PR_NUMBER

# On resume: recover chosen scope from the latest fixer summary
gh pr view $PR_NUMBER --json comments -q \
  '[.comments[].body | select(test("fix-bug-fix-summary"))] | last'

Match rows top-to-bottom. Human intervention must win over fix-bug-approved — e.g. a human commenting after approval should escalate, not exit silently.

Fallback when round markers are missing: estimate rounds from PR comments that are not orchestration markers (fix-bug-fix-summary, fix-bug-escalation, fix-bug-approved). Do not count fixer summaries — they are posted every push and would trigger premature escalation.

marker_count=$(gh pr view $PR_NUMBER --json comments -q \
  '[.comments[].body | select(test("fix-bug-round"))] | length')
fallback_count=$(gh pr view $PR_NUMBER --json comments -q \
  '[.comments[].body | select(test("fix-bug-fix-summary|fix-bug-escalation|fix-bug-approved") | not)] | length')
# round_estimate = max(marker_count, fallback_count); if ambiguous, treat as round 0

Scope selection (umbrella / meta issues)

Some issues track many bugs (sub-issues, checklists, or long itemised lists). Fix one thing per PR — never attempt the whole umbrella in a single pass.

Detect umbrella issues before implementing:

REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)

# Sub-issues (primary — GitHub sub-issues API)
gh api "repos/$REPO/issues/$ISSUE_NUMBER/sub_issues" \
  --jq '.[] | {number, title, state}'

# Issue body and metadata (checklists, cross-references)
gh issue view $ISSUE_NUMBER --json title,body,state,labels,comments
# Secondary: scan body for unchecked `- [ ]` items, numbered bug lists, or `#NNN` cross-refs

Placeholders in templates below use angle brackets (#<scope-issue>, #<parent-issue>) — substitute the actual issue numbers. Heredocs use <<'EOF' (no shell expansion).

Tie-breaking: When several candidates look equally valid, pick one and proceed — do not ask the user. The user delegated this work; a coin-flip question blocks progress. Use the first open sub-issue by number, or the first unchecked checklist item top-to-bottom, and record the choice in the fixer summary.

Record scope explicitly before coding:

• Note the scope issue number (#<scope-issue>) — the child issue when fixing a sub-issue, otherwise the issue you were pointed at.
• Note which checklist item or sub-issue you chose and why (one sentence).

Closing semantics (must match what the PR actually does):

When in doubt, under-close (Part of) rather than over-close (Fixes on a parent meta issue).

Phase 2: Fix implementation

Skip steps already done when resuming an existing PR (e.g. branch exists, partial fix landed).

1. Read the bug report thoroughly — issue body, all comments (especially triage bot comments), linked PR discussion, any linked docs. If the issue is an umbrella, complete Scope selection above and fix only the chosen item.

2. Identify root cause — trace the actual code path; reproduce with a failing test when possible. Don't guess from the description alone.

3. Consider 2–3 approaches — pick the smallest correct diff. Prefer fixing the shared function once over patching each caller.

4. Implement — follow the repo's agent guide and style conventions.

5. Validate — run targeted tests and lint per Repo conventions.

6. Commit and push:

   git add -A
   git commit -m "$(cat <<'EOF'
   Short imperative summary
   
   Fixes #<scope-issue>. Part of #<parent-issue> if umbrella. Why this approach.
   EOF
   )"
   git push -u origin HEAD

7. Create PR (only if none exists yet):

   gh pr create --title "Fix: <short description>" --body "$(cat <<'EOF'
   ## Summary
   <1-2 sentences on the approach.>
   
   ## Issue links
   - Fixes #<scope-issue> (or Part of #<parent-issue> — match actual scope)
   - <If umbrella: which sub-issue or checklist item this addresses>
   
   ## Test plan
   - [ ] Targeted tests pass
   - [ ] Full/fast test suite passes
   - [ ] Lint passes
   EOF
   )"

8. Post a fixer summary comment on the PR (required after initial push and after each round of review fixes):

   gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
   <!-- fix-bug-fix-summary -->
   ## Fix summary
   
   **Scope**: Fixes #<scope-issue> / Part of #<parent-issue> — <which sub-issue or checklist item, if umbrella>
   **Root cause**: <one sentence>
   **Approach**: <why this fix, not an alternative>
   **Not in scope**: <what was deliberately left for a follow-up PR>
   EOF
   )"

   Keep it brief (4–6 sentences). The reviewer reads the diff; this comment explains intent for humans and the next automation pass.

9. Update PR body when scope drifts — if implementation narrows or shifts scope, edit only the ## Issue links section. Read the current body first; never replace the whole description (that would destroy human edits to Summary, Test plan, or checkboxes):

   gh pr view $PR_NUMBER --json body -q .body   # read current body
   # Merge: keep all existing sections; update only ## Issue links
   gh pr edit $PR_NUMBER --body "$(cat <<'EOF'
   <paste merged body — preserve everything outside Issue links>
   EOF
   )"