| name | diagnosing-bugs |
| description | Diagnose and fix bugs, manual test failures, CI failures, and regressions through a disciplined feedback loop. Use when Codex needs to reproduce, minimize, hypothesize, instrument, fix, regression-test, and prepare acceptance evidence. |
Diagnosing Bugs
Build a feedback loop before changing production code. A bug is not ready to fix until there is a signal that can prove the symptom is gone.
Read docs/agents/issue-tracker.md, docs/agents/domain.md, and docs/agents/verification.md if they exist.
Phase 1: Build A Feedback Loop
Create the tightest red-capable signal available:
- Failing automated test.
- CLI command with fixture input.
- HTTP/curl script.
- Browser automation.
- Replay of logs, traces, HAR files, or payloads.
- Small harness around the public path.
- Structured human-in-the-loop script if manual action is unavoidable.
The loop should be:
- Red-capable for the user's exact symptom.
- Deterministic, or high-reproduction for flaky bugs.
- Fast enough to run repeatedly.
- Agent-runnable, unless explicitly recorded as manual.
If no loop can be built, stop and ask for the missing artifact or environment. Do not guess a fix.
Phase 2: Reproduce And Minimize
Run the loop and confirm it shows the reported symptom. Minimize the repro by removing inputs, steps, config, or data until only load-bearing elements remain.
Capture the exact symptom and the command or steps that produce it.
Phase 3: Hypothesize
Generate 3-5 ranked hypotheses. Each must make a falsifiable prediction.
Format:
If <cause>, then <probe or change> should <observable result>.
Use project domain terms and relevant ADR constraints.
Phase 4: Instrument
Probe one hypothesis at a time. Prefer debuggers or focused inspection. If adding temporary logs, tag them with a unique prefix and remove them before handoff.
For performance regressions, measure first, then change one variable at a time.
Phase 5: Fix And Regression-Test
Turn the minimized repro into a regression test when there is a correct seam. If there is no correct seam, document that architecture risk and use the best available verification.
Then:
- Watch the regression signal fail.
- Apply the smallest fix.
- Watch the signal pass.
- Re-run the original repro.
- Run relevant broader regression checks.
Phase 6: Clean Up And Hand Off
Before declaring done:
- Original repro no longer reproduces.
- Regression evidence exists or the missing seam is recorded as a risk.
- Temporary instrumentation is removed.
- Throwaway harnesses are removed or clearly marked.
- The cause is summarized for the issue, PR, or handoff.
- Acceptance evidence is ready.
If the bug reveals poor seams, hidden coupling, or code that cannot be safely tested, recommend a follow-up architecture issue after the fix is complete.
