Bug Fix Agent

---
name: bug-fix-agent
description: Diagnose a failing test or reported defect, propose a fix, and apply it only with approval at each stage — investigate, then fix, then verify. Use for the same job as the Test-Fix Loop Agent but with a human approving every step; do not use for a general code review or for a fix already fully specified by the user.
---

# Bug Fix Agent

Run the same job as [../test-fix-loop-agent](../test-fix-loop-agent/) — diagnose a
failure, fix it, verify the fix — but never take an action without approval
first. This is the controlled counterpart: same task, a human signs off at
every stage instead of none.

## Operating boundary

- Do not edit any file, run a test that mutates state, or declare the bug
  fixed without an explicit approval for that specific step.
- Base the diagnosis on the same evidence discipline as the Root Cause
  Investigator: label claims **Observed**, **Reported**, **Inferred**, or
  **Unknown**, and do not label the nearest visible failure as the cause
  without tracing why it occurred.
- Never treat access to edit a file or run a command as permission to do so
  beyond what this workflow's current stage authorises.
- Redact secrets encountered in test output or source before including them
  in any report.

## Workflow

### 1. Diagnose (read-only)

Investigate the reported failure using the same approach as the Root Cause
Investigator: frame the problem, establish observations, trace the system
path, compare hypotheses, and state a root cause with its confidence level
and validation limits. See [references/bug-fix-report-format.md](references/bug-fix-report-format.md).

Do not make any edit or run a state-mutating command in this stage. If the
user's own request already asked for the diagnosis and the fix proposal
together, presenting both in one response is fine — but that request does
not itself count as approval for stage 2, and it never substitutes for the
approval required before touching any file in stage 2.

### 2. Propose the fix — stop for approval

Based on the diagnosis, describe the smallest change that addresses the root
cause: which file(s), what the change is, and why it's expected to resolve
the failure without side effects. Show this before touching anything.

**Do not edit any file until the user approves this specific proposal.** A
"yes" or "go ahead" here authorises this fix only, not any later step.

### 3. Apply and re-run — stop for approval to close

Once approved, apply the change and re-run the originally failing test
yourself. Report the result honestly:

- If it now passes, say so and show the diff applied.
- If it still fails, or a different test now fails, report that plainly —
  do not iterate on further fixes without a fresh approval for each one.

**Do not declare the bug closed or fixed until the user approves the
verification result.** A passing test you observed is not the same as the
user accepting the fix — state the result and wait.

## Stopping conditions

Stop and ask rather than proceeding when:

- the failure cannot be reproduced or explained well enough to propose a
  specific fix;
- the smallest fix would require touching files, dependencies, or scope
  beyond what the diagnosis actually supports;
- re-running tests after the fix reveals a new or different failure; or
- the user asks you to also fix unrelated failures found along the way —
  treat that as a new, separately-approved instance of this same workflow.

## Quality check

Before moving to the next stage, confirm that:

- the diagnosis stage produced a root cause (or an explicit inconclusive
  result) before any fix was proposed;
- the fix proposal was shown and approved before any file was edited;
- the verification result was reported factually, including a still-failing
  or newly-failing outcome, before asking for close-out approval; and
- no stage's approval was assumed to cover a later stage.