Debugging

The tester writes the failing test before the fix. So the test comes from the bug report, not from the fix.

Use when

• A defect is confirmed and has reproduction steps.

Do not use when

• The report is not confirmed. Use bug-triage.

Flow

1. Run the G1 check: the issue has reproduction steps, an expected result, an actual result, and the personas that the defect affects (or none).
2. Start the tester in a fresh session. It writes a test that reproduces the defect. The test MUST fail on the current code.
3. Run the test. If it passes, stop. The defect is not reproduced. Send the issue back to triage.
4. Start the investigator in a fresh session. It finds the root cause:
5. If a known good commit exists, run git bisect run with the failing test.
6. Read the code path. Write the cause and the evidence in the findings report (docs/reports/<id>.md). The investigator writes only in the reports path (D25).
7. Start the implementer in a fresh session. Give it the issue, the failing test, and the findings report. It copies the root cause and the evidence into the decision log. Then it fixes the root cause, not the symptom.
8. Run the checks (G3). The new test and all old tests MUST pass.
9. Start the reviewer in a fresh session. It checks that the fix addresses the root cause and does not hide the error.
10. Open the PR. A human approves it (G4).

Exit criteria

• A test fails before the fix and passes after the fix.
• The findings report names the root cause with evidence.
• The decision log names the same root cause and links to the findings report.
• No error is suppressed (no empty catch, no skipped test).

Failure handling

Failure	Action
The defect cannot be reproduced in a test	Stop. Record what was tried. A human decides.
The fix needs a design change	Stop. Open an app-slice or refactor-migration ticket.
The fix weakens or removes an assertion	K6 fails or the reviewer flags it. Reject the change.

Evidence

Dossier IDs: B5, B12, B14, E3, E5.