tmusser 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
- Freeze feature work.
- Reproduce the failure.
- Identify the exact failing command or case.
- List hypotheses.
- Instrument minimally.
- Name one active hypothesis and the observation that would falsify it; apply the smallest fix that tests it.
- Add a regression check if possible.
- Rerun the original failing command.
- Rerun relevant verification. An improved signal is not completion; the original failure and compatibility checks must pass.
- 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. - 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.
- 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.
- 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.