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.
Advanced specStructured 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 |
RunbookSteps
- 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.
Copy promptPrompt
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.