Arc Bug Fixer

Bug Fixer

The implementation counterpart to arc-bug-finder. Where the finder researches and files a bug, the fixer reviews, resolves, and ships it.

The input is a filed bug ticket; the output is a merged-ready PR that closes that ticket, with the ticket updated to reflect the resolution.

This skill modifies product code — but only after it has independently confirmed the bug is real and the cited root cause is correct. A ticket is a hypothesis, not a work order.

Operating Principles

• Review before you repair. The finder's root cause and recommended fix are a starting point, not gospel. Re-reproduce the defect and re-confirm the root cause at file:line yourself before changing a line. Findings drift: the code may have moved, the bug may already be fixed, or the recommended fix may be wrong.
• Fix the cause, not the symptom. Patch where the defect originates, not where it manifests. If the ticket conflated the two, correct it.
• Every fix is verified. The bug is not "fixed" until you have reproduced it failing, applied the change, and reproduced it passing — plus a regression test that would have caught it.
• Smallest correct change. Minimize blast radius. Match the surrounding code's conventions, naming, and patterns. No drive-by refactors in a bug PR.
• One ticket, one PR. Cross-link if the fix reveals adjacent defects; file the new ones via arc-bug-finder rather than smuggling unrelated fixes into this PR.

Orchestrator Route Guidance

When this skill runs under arc-orchestrator, the parent retains ticket judgment, fix selection, acceptance, review judgment, and approval. Route only bounded phases:

• codex-explore for read-only reproduction, call-path tracing, and root-cause evidence before the parent issues the review verdict.
• composer-implement for a clear mechanical fix in an isolated worktree (the Cursor/Composer implementation lane; there is no separate cursor-implement route).
• codex-implement for a non-obvious fix, debugging-heavy work, or escalation after Composer misses the bar.
• codex-check for independent regression, correctness, security, and acceptance-criteria review; opus-review for taste-sensitive UI/UX, API, architecture, copy, docs, prompt, or skill critique.
• opus-explore, opus-check, and opus-implement are the matching availability fallbacks when Codex is unavailable, not default routes.

Before delegating a write-capable route, the parent creates or assigns an isolated worktree for the ticket. Workers edit and verify only there. They never commit, push, comment, merge, deploy, edit secrets, update tickets, or touch unrelated files. Review workers return findings rather than posting them. The parent inspects the evidence, delegates commit and push to mechanical-commit-push, opens the PR directly with gh pr create, delegates ticket and PR comments to mechanical-post-comment, and delegates merge or auto-merge to mechanical-merge only when the caller explicitly authorizes it. Otherwise, orchestrated fixes default to PR-first --ship pr. Outside orchestration, preserve the standalone workflow and arc-git-pr-check behavior below.

Workflow Overview

1. Intake the ticket          → fetch the bug from its tracker (GitHub|GitLab|Linear)
2. REVIEW & validate          → re-reproduce, re-confirm root cause, vet the fix
   ├─ valid + cause confirmed  → continue
   ├─ already fixed / stale    → close with evidence, stop
   └─ not a bug / can't repro  → bounce back with findings, stop
3. Decide the fix             → adopt or improve the recommended option
4. Plan (for non-trivial)     → ordered tasks mapped to acceptance criteria
5. Branch + implement         → smallest correct change, repo conventions
6. Verify                     → repro gone, regression test added, suite green
7. Ship                       → conventional commit, PR linking the ticket
8. Update the ticket + report → status, PR link, what changed and why

Step 1: Intake the Ticket

Identify the bug to fix and pull its full body. Detect the tracker the same way arc-bug-finder does (probe git remote -v, gh auth status/.github/, .gitlab-ci.yml/glab, LINEAR_API_KEY/Linear MCP). Confirm if ambiguous.

If the user gives only a symptom and no ticket number, search for the ticket (error string / route / W-number) before assuming none exists. If genuinely none exists, this is intake, not a fix — hand off to arc-bug-finder first, then return here.

Parse the arc-bug-finder body into its parts — you will check each: Summary, Steps to Reproduce, Acceptance Criteria (verifiable checklist), Root Cause (file:line + originating commit), Recommended Fix (ranked options), Research Notes, Blast Radius.

Step 2: Review & Validate (the core competency)

Do not skip this even when the ticket looks airtight. Produce a short review verdict before touching code.

1. Re-reproduce. Follow the Steps to Reproduce exactly. Run the failing test, or write a minimal repro (do not commit it). Confirm the symptom is real, current, and deterministic on the current default branch. If it does not reproduce, find out why before proceeding.
2. Re-confirm the root cause. Open the cited file:line. Does the described defect actually exist there now? Code drifts after filing — re-anchor by grepping the error string / symbol if the line moved. Trace the path yourself (component → handler → service → data) and verify the cause produces the symptom.
3. Check it isn't already resolved. git log since the ticket was filed; search merged PRs and the originating commit (<sha>) for a later fix. If fixed, go to Already-fixed below.
4. Vet the recommended fix. Is option A actually correct and lowest-risk? Does a dependency upgrade vs. patch vs. workaround still apply? Consult the framework's skill (Next.js, Convex, Clerk, Stripe, Vercel, etc.) and official docs before committing to an approach. You may override the ticket's recommendation — record why.
5. Confirm severity & scope. Re-check blast radius: who else calls the broken code, and is the data/role/viewport dependency as stated? Adjust severity if the ticket over- or under-rated it.

Write the verdict in the ticket-update buffer:

REVIEW VERDICT
- Reproduced: yes/no (how)
- Root cause confirmed: yes/no — now at `path:NN` (moved from `path:MM`)
- Already fixed: no | yes (PR #..)
- Fix approach: adopt Option A | switch to <X> because <reason>
- Severity: confirmed S2 | adjusted S2→S3

Branch points

• Already fixed / cannot reproduce on current main. Do not write code. Comment on the ticket with the evidence (commit/PR that fixed it, or repro attempt), set it to the tracker's closed/won't-fix state, and report. Ask the user before closing if there is any doubt.
• Not a bug / works as designed / invalid. Bounce it back: comment with your findings, recommend a label like wontfix/invalid, and stop. Do not force a fix for a non-defect.
• Real but root cause wrong. Correct the Root Cause section on the ticket (comment), then proceed with the true cause.

Step 3: Decide the Fix

State the chosen approach in one or two sentences: what changes, where, and why it is the smallest correct change. If you departed from the ticket's recommendation, say so and why. Note the regression test you will add.

Step 4: Plan (non-trivial fixes only)

A one-line fix needs no plan — go to Step 5. For multi-file or risky fixes, produce an ordered task plan mapped to the ticket's acceptance criteria and post it to the ticket:

• GitHub / Linear / Agile Accelerator / PRD → arc-planning-work (GitHub: gh issue comment with the plan per GITHUB_MODE.md).

Reuse the existing **Branch:** feat/... convention from those skills, but for a defect prefer a fix/ branch (see Step 7).

Step 5: Branch & Implement

1. Branch off the up-to-date default branch: fix/W-XXXXXX-<short-slug> (use feat/ only if the fix is really an enhancement). If you are already on a clean feature branch for this ticket, reuse it.
2. Implement the smallest correct change at the confirmed root cause. Follow the repo's layered architecture and naming. Read neighboring code first so the change reads like it belongs.
3. Touch only what the fix needs. No reformatting, no unrelated renames. If you spot an adjacent defect, note it for a separate ticket — do not fix it here.
4. For Salesforce repos, follow the sf-2gp-pipeline skill's conventions (virtual methods, DI, @TestVisible setters, with sharing); for web repos, follow the project's framework skill.
5. Under an orchestrator, select the implementation route above and inspect the worker's diff and verification before accepting the fix.

Step 6: Verify the Fix

The fix is not done until all of these hold — show the evidence:

1. Repro now passes. Re-run the exact reproduction from Step 2; the symptom is gone.
2. Regression test added. Add a test that fails on the old code and passes on the new — ideally encoding the ticket's acceptance criteria. This is mandatory; a fix with no test guarding it can silently regress.
3. Existing suite is green. Run the project's test commands (e.g. sf apex test run --wait 10 --code-coverage, pnpm run test:unit, relevant E2E) and lint. Quote the result. Keep org-wide coverage above the project threshold.
4. No new breakage in the blast radius. Exercise the other call sites the review flagged.
5. Visually confirm UI fixes. For a UI defect, run the app / use the dogfood skill or agent-browser to confirm the screen now renders correctly, and capture an after-screenshot for the PR/ticket.

If any check fails, return to Step 5. Never ship on a red suite — report the failure instead.

Step 7: Ship

Under orchestration, use the PR-first and mechanical-route policy above. The steps below describe standalone shipping; do not replace its existing behavior or explicit caller choices.

1. Commit with Conventional Commits per arc-conventional-commits: fix: <summary> (W-XXXXXX) — fix: for a defect (patch), feat: only if it was really an enhancement. Squash & merge is the project default.
2. Open the PR via arc-git-pr-check (bin/run.sh --type fix --summary "<...>"), which commits-if-needed, pushes, creates the PR, and enables squash auto-merge. It also guards against committing on the default branch.
3. Link the ticket from the PR so it auto-closes on merge: GitHub Fixes #<n> / Closes #<n> in the PR body; GitLab Closes #<iid>; Linear — put the issue identifier (e.g. WSM-000079) in the PR title/branch for magic-word linking.
4. PR body = the fix in brief: root cause (with file:line), what changed, how verified (tests + before/after), and any follow-up tickets filed.
5. Do not merge or deploy unless the user explicitly asks. Deploy Convex/web only from merged main, never a feature branch.

Step 8: Update the Ticket & Report

Update the source ticket and then report to the user.

Under orchestration, the parent decides the update content and delegates each ticket or PR comment to mechanical-post-comment; workers do not post updates.

On the ticket (comment + state change):

• Post the review verdict and the resolution: root cause confirmed, fix applied, PR link, tests added.
• Move to the in-review/done state appropriate to the tracker (GitHub: rely on Fixes # to close on merge, or move on the project board; GitLab: same; Linear: set state to In Review / Done).
• Attach the after-screenshot for UI fixes.

To the user (concise):

• Ticket ID / W-number and one-line review verdict (was it valid?).
• PR URL and branch.
• One-line root cause and what changed (file:line).
• Verification: tests added + suite result.
• Any additional defects discovered and filed separately.

Cross-Skill Delegation

Working a Backlog

When asked to "work the bug backlog" or fix several tickets:

• List open bugs (gh issue list --label type:bug --state open, GitLab/Linear equivalents) and triage by severity (S1 → S4) then priority.
• Fix them one ticket / one PR at a time. For independent bugs across different files, the arc-parallel-implement skill can fan out — each gets its own branch, commit, and PR. Do not batch dependent or same-file fixes in parallel.

Rules

• Review every ticket before fixing — re-reproduce and re-confirm the cited root cause at file:line. A ticket is a hypothesis.
• Never ship a fix without a regression test and a green suite — quote the evidence.
• Smallest correct change; fix the cause, not the symptom; no unrelated refactors.
• One ticket → one PR; cross-link related defects, file new ones via arc-bug-finder.
• Match the repo's branch/commit/label and ticket-numbering conventions; link the ticket so it closes on merge.
• Do not merge or deploy unless explicitly asked; deploy only from merged main.
• Never commit or expose API tokens (LINEAR_API_KEY, GITLAB_TOKEN); read from env and delete temp files holding secrets or screenshots.