Practical decision guide
5 min read
Updated
Debug with an agent by testing one cause at a time
Move from a reproducible symptom to a bounded fix without random changes or leaked logs.
Direct answer
Start from a reproducible symptom and separate observation from explanation. Ask for competing causes, then run the smallest check that distinguishes them before editing. Verify the original failure after the fix and retain unresolved uncertainty instead of treating a plausible story or a passing unrelated test as proof.
01
Freeze the reproduction
For a save that sometimes duplicates a record, capture steps, expected count, observed count and environment. Use fictional records in an authorized test system. Note whether the failure occurs before or after the response.
Sanitize logs before sharing: remove tokens, personal data and full request bodies unless necessary and authorized. Keep useful timestamps or request references without pretending redaction preserves every diagnostic clue.
- debug with an agent without random fixes
- find the cause before changing code
For a save that sometimes duplicates a record, capture steps, expected count, observed count and environment. Use fictional records in an authorized test system. Note whether the failure occurs before or after the response. Sanitize logs before sharing: remove tokens, personal data and full request bodies unless necessary and authorized. Keep useful timestamps or request references without pretending redaction preserves every diagnostic clue.
02
Choose a discriminating check
Two hypotheses may be a double client event or a server retry. Count outbound requests and resulting operations for one controlled action. A disabled button screenshot does not distinguish those causes.
Write the expected observation for each hypothesis before the check. If the result fits neither, revise the explanation rather than expanding the patch until the symptom disappears.
Two hypotheses may be a double client event or a server retry. Count outbound requests and resulting operations for one controlled action. A disabled button screenshot does not distinguish those causes. Write the expected observation for each hypothesis before the check. If the result fits neither, revise the explanation rather than expanding the patch until the symptom disappears.
03
Example: out-of-order results
Search A starts, then B starts. Delay A so it completes last. If the UI displays A under B’s query, the observed defect is stale rendering; changing the search vocabulary will not address it.
A focused fix can guard the request identity or cancel obsolete work, according to the existing design. Verify B remains visible when A resolves late and that a genuine B failure remains recoverable.
Search A starts, then B starts. Delay A so it completes last. If the UI displays A under B’s query, the observed defect is stale rendering; changing the search vocabulary will not address it. A focused fix can guard the request identity or cancel obsolete work, according to the existing design. Verify B remains visible when A resolves late and that a genuine B failure remains recoverable.
04
Use history when it narrows the cause
When a reliable good and bad revision exist, comparison or bisect can narrow a regression. Use an isolated checkout and a repeatable outcome. An intermittent test needs stabilization before it can reliably label revisions.
Do not reset or overwrite the user’s working tree to reproduce an old build. If the previous environment cannot be recovered, report that limitation and use current evidence rather than inventing a baseline.
When a reliable good and bad revision exist, comparison or bisect can narrow a regression. Use an isolated checkout and a repeatable outcome. An intermittent test needs stabilization before it can reliably label revisions. Do not reset or overwrite the user’s working tree to reproduce an old build. If the previous environment cannot be recovered, report that limitation and use current evidence rather than inventing a baseline.
05
Verify the causal fix
Repeat the original reproduction and the neighboring success path. Add a regression test when it captures the failure meaningfully. Record what changed, which hypothesis was supported and what is still unverified.
This method does not guarantee a root cause for every intermittent incident. A temporary mitigation, a confirmed fix and an unexplained non-reproduction are different conclusions.
Repeat the original reproduction and the neighboring success path. Add a regression test when it captures the failure meaningfully. Record what changed, which hypothesis was supported and what is still unverified. This method does not guarantee a root cause for every intermittent incident. A temporary mitigation, a confirmed fix and an unexplained non-reproduction are different conclusions.
Keep this
Verify in your product
- 01The symptom can be repeated or bounded.
- 02Logs are scoped and sanitized.
- 03Hypotheses have distinct predictions.
- 04The check precedes the fix.
- 05The original path is replayed.
- 06Uncertainty remains explicit.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- git bisect (opens in a new tab)Git · Primary reference for the documented mechanism. The worked scenario and decision checklist are original SkillCodex editorial guidance, not a certified implementation.
- AbortController (opens in a new tab)MDN · Primary reference for the documented mechanism. The worked scenario and decision checklist are original SkillCodex editorial guidance, not a certified implementation.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “Debug with an agent by testing one cause at a time” step by step
# Apply the “Debug with an agent by testing one cause at a time” guide in your agent ## Objective Start from a reproducible symptom and separate observation from explanation. Ask for competing causes, then run the smallest check that distinguishes them before editing. Verify the original failure after the fix and retain unresolved uncertainty instead of treating a plausible story or a passing unrelated test as proof. ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: Move from a reproducible symptom to a bounded fix without random changes or leaked logs. - Preserve the correct decisions already in place. ## Guide steps - 1. Freeze the reproduction — For a save that sometimes duplicates a record, capture steps, expected count, observed count and environment. Use fictional records in an authorized test system. Note whether the failure occurs before or after the response. Sanitize logs before sharing: remove tokens, personal data and full request bodies unless necessary and authorized. Keep useful timestamps or request references without pretending redaction preserves every diagnostic clue. - 2. Choose a discriminating check — Two hypotheses may be a double client event or a server retry. Count outbound requests and resulting operations for one controlled action. A disabled button screenshot does not distinguish those causes. Write the expected observation for each hypothesis before the check. If the result fits neither, revise the explanation rather than expanding the patch until the symptom disappears. - 3. Example: out-of-order results — Search A starts, then B starts. Delay A so it completes last. If the UI displays A under B’s query, the observed defect is stale rendering; changing the search vocabulary will not address it. A focused fix can guard the request identity or cancel obsolete work, according to the existing design. Verify B remains visible when A resolves late and that a genuine B failure remains recoverable. - 4. Use history when it narrows the cause — When a reliable good and bad revision exist, comparison or bisect can narrow a regression. Use an isolated checkout and a repeatable outcome. An intermittent test needs stabilization before it can reliably label revisions. Do not reset or overwrite the user’s working tree to reproduce an old build. If the previous environment cannot be recovered, report that limitation and use current evidence rather than inventing a baseline. - 5. Verify the causal fix — Repeat the original reproduction and the neighboring success path. Add a regression test when it captures the failure meaningfully. Record what changed, which hypothesis was supported and what is still unverified. This method does not guarantee a root cause for every intermittent incident. A temporary mitigation, a confirmed fix and an unexplained non-reproduction are different conclusions. ## Acceptance criteria — Verify in your product - The symptom can be repeated or bounded. - Logs are scoped and sanitized. - Hypotheses have distinct predictions. - The check precedes the fix. - The original path is replayed. - Uncertainty remains explicit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:d3945541c49a55863153f33ef6580225227b8752e754601b7f68fd6014e8a00d
Diagnose a problem
Diagnose a “Debug with an agent by testing one cause at a time” guide gap
# Diagnose a failed application of the “Debug with an agent by testing one cause at a time” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. Freeze the reproduction — For a save that sometimes duplicates a record, capture steps, expected count, observed count and environment. Use fictional records in an authorized test system. Note whether the failure occurs before or after the response. Sanitize logs before sharing: remove tokens, personal data and full request bodies unless necessary and authorized. Keep useful timestamps or request references without pretending redaction preserves every diagnostic clue. - 2. Choose a discriminating check — Two hypotheses may be a double client event or a server retry. Count outbound requests and resulting operations for one controlled action. A disabled button screenshot does not distinguish those causes. Write the expected observation for each hypothesis before the check. If the result fits neither, revise the explanation rather than expanding the patch until the symptom disappears. - 3. Example: out-of-order results — Search A starts, then B starts. Delay A so it completes last. If the UI displays A under B’s query, the observed defect is stale rendering; changing the search vocabulary will not address it. A focused fix can guard the request identity or cancel obsolete work, according to the existing design. Verify B remains visible when A resolves late and that a genuine B failure remains recoverable. - 4. Use history when it narrows the cause — When a reliable good and bad revision exist, comparison or bisect can narrow a regression. Use an isolated checkout and a repeatable outcome. An intermittent test needs stabilization before it can reliably label revisions. Do not reset or overwrite the user’s working tree to reproduce an old build. If the previous environment cannot be recovered, report that limitation and use current evidence rather than inventing a baseline. - 5. Verify the causal fix — Repeat the original reproduction and the neighboring success path. Add a regression test when it captures the failure meaningfully. Record what changed, which hypothesis was supported and what is still unverified. This method does not guarantee a root cause for every intermittent incident. A temporary mitigation, a confirmed fix and an unexplained non-reproduction are different conclusions. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Verify in your product - The symptom can be repeated or bounded. - Logs are scoped and sanitized. - Hypotheses have distinct predictions. - The check precedes the fix. - The original path is replayed. - Uncertainty remains explicit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:c2d529ffea3aaaa16d062a00d99dc64d5b988ccb78fb3a464216ab0628da29ea
Pack digest: sha256:54f02b7995dd8acce39afc613b0cdd885fa2b9311fe5515d382b9748ca542f06