diagnose-loop ยท diff
git:20260518.0d37b7d to git:20260910.1199fd5
11 added, 3 removed. Audit A to A.
---
name: diagnose-loop
- description: Debug failures systematically.
+ description: Diagnose reproducible failures with hypothesis-driven fixes and bounded retries.
---
# Diagnose Loop
## Purpose
Debug failures systematically.
## When to use
Use when a command fails, behavior is wrong, a test regresses, or output does not match the spec.
## Inputs
- Failure report
- Exact command or reproduction case
- Recent changes
- Logs, traces, or output
## Workflow
1. Freeze feature work.
2. Reproduce the failure.
3. Identify the exact failing command or case.
4. List hypotheses.
5. Instrument minimally.
- 6. Apply the smallest fix.
+ 6. Name one active hypothesis and the observation that would falsify it; apply the smallest fix that tests it.
7. Add a regression check if possible.
8. Rerun the original failing command.
- 9. Rerun relevant verification.
+ 9. Rerun relevant verification. An improved signal is not completion; the original failure and compatibility checks must pass.
+ 10. Before a second repair attempt, count the initial attempt and define the retry contract: fixed input/evaluator identities, acceptance threshold, total attempt limit, consecutive no-progress limit, revert rule, ledger location, and review trigger. If incomplete, stop with `REVIEW_REQUIRED`; the initial bounded diagnosis does not require a separate loop artifact.
+ 11. Record each started attempt, including failed commands and interrupted attempts: hypothesis, artifact state, evidence, outcome, and consumed budget. Change the next hypothesis only when the evidence supports it. Unchanged or worse results and tool errors consume the no-progress budget; improvement does not reset the total budget.
+ 12. Stop at acceptance, either budget limit, an unresolved interruption, or a scope/permission/evaluator change. Preserve the best known state and the failed attempt's evidence; revert only edits owned by this attempt, never unrelated user work. Reconcile uncertain external effects before retrying.
+ 13. On resume, carry forward the same loop identity, ledger, input/evaluator identities, consumed budget, and stop reason. A fresh session or subtask does not grant new attempts. Renew a spent budget or change the evaluator only through an explicit contract revision; preserve the prior ledger.
## Outputs
- Root-cause note
- Smallest fix
- Regression check when possible
- Rerun results
+ - For repeated repairs: compact attempt ledger, remaining budget, and stop reason
## Stop conditions
- The original failure is fixed and verified.
- The failure cannot be reproduced.
- The next step requires a product or data decision.
+ - Retry limits are reached, evidence is stale, or an interrupted attempt has unresolved effects.
## Anti-patterns
+ - Repeating the same failed fix without a new falsifiable hypothesis.
+ - Weakening tests, changing the evaluator, or resetting counters to make progress appear green.
- Randomly editing files before reproducing the bug.
- Fixing symptoms without naming the failing case.
- Adding noisy instrumentation and leaving it behind.