Engineering
Trace-First Debugging
Make the agent earn the fix before touching code.
Use when
A failure has logs, screenshots, stack traces, recent commits, or user reports, but the cause is not obvious yet.
Cadence
When an agent is tempted to patch a bug from a hunch
Verification
The bug is reproduced, the root cause is evidenced by traces or tests, and the fix includes a regression check.
Structured loop spec
| Field | Value |
|---|---|
| Name | Trace-First Debugging |
| Category | Engineering |
| Trigger | When an agent is tempted to patch a bug from a hunch |
| Objective | Make the agent earn the fix before touching code. |
| Allowed inputs | Relevant files, source notes, logs, tests, screenshots, metrics, or task state for this loop |
| Allowed actions | Collect the symptom, expected behavior, recent changes, logs, stack traces, screenshots, and environment details.; List plausible causes and the smallest diagnostic for each before modifying files.; Reproduce the bug or create a failing regression test/check that captures it.; Patch the smallest proven cause and remove temporary debug noise unless it should become structured logging.; Verify the original reproduction fails before and passes after, then run nearby tests. |
| Verification | The bug is reproduced, the root cause is evidenced by traces or tests, and the fix includes a regression check. |
| Stop condition | Stop when the verifier passes, the budget is exhausted, no progress is made, a blocker appears, or approval is required. |
| Budget | Set a time, turn, token, retry, file, or dollar cap before running the loop. |
| Approval boundary | Human approval required before public, destructive, financial, legal, account, or production-impacting actions. |
| Safe output | Pull request, patch, report, or evidence log |
| Works with | Claude Code, OpenAI Codex, Cursor, Gemini CLI, any tool-using coding agent |
Steps
- Collect the symptom, expected behavior, recent changes, logs, stack traces, screenshots, and environment details.
- List plausible causes and the smallest diagnostic for each before modifying files.
- Reproduce the bug or create a failing regression test/check that captures it.
- Patch the smallest proven cause and remove temporary debug noise unless it should become structured logging.
- Verify the original reproduction fails before and passes after, then run nearby tests.
Prompt
Run the Trace-First Debugging loop. Do not patch from vibes. Gather symptom, expected behavior, recent changes, logs, traces, screenshots, and environment. List likely causes with diagnostics before editing. Reproduce the bug or create a failing regression check, patch the smallest proven cause, remove temporary debug noise, and verify the original reproduction plus nearby tests.Run in Claude Code
Paste this into Claude Code (or any tool-using agent) to run the loop bounded: one change per round, the same verification every round, durable state files, and explicit stop conditions.
Run the "Trace-First Debugging" loop from AI Loop Library (https://ailooplibrary.com/loops/trace-first-debugging/) as a bounded loop.
Goal: Make the agent earn the fix before touching code.
Rules: one change per round; run the same verification every round (The bug is reproduced, the root cause is evidenced by traces or tests, and the fix includes a regression check.); append each round to docs/loops/trace-first-debugging/progress.md and update docs/loops/trace-first-debugging/state.json; stop on verifier pass, 8 rounds, 3 consecutive failed verifications, no progress, a blocker, or anything needing human approval (money, production, outbound, deletion). Finish with a proof report: rounds used, changes made, verification output, remaining risk, and the next human decision.