| name | diagnose |
| description | Diagnoses hard bugs and performance regressions with a controlled feedback loop, and implements the fix only when requested. Use when the failure is flaky, not yet reproducible, still lacks a root cause, or needs measurement.
|
Diagnose
A discipline for hard bugs. When the failure mode and repro are already
narrow, use the smallest feedback loop that can still falsify the suspected
cause.
Phases
Work through these in order:
- Build a feedback loop — the highest-leverage step; do not skip.
- Reproduce — confirm the loop matches the user's reported symptom.
- Hypothesise — 3–5 ranked, falsifiable hypotheses; show the user.
- Instrument — one variable at a time; tagged debug logs or perf baseline.
- Conclude or fix — report the proven cause; implement and regression-test
only when the request authorizes a fix.
- Cleanup + post-mortem — remove instrumentation; hand off architecture
findings to
improve-codebase-architecture when warranted.
Completion Criterion
The successful diagnosis branch is complete when:
- the bug or regression is reproduced with a feedback loop,
- the root cause is supported by evidence that distinguishes it from the other
ranked hypotheses,
- the requested output is delivered: either a diagnosis with a concrete fix
and regression-test plan, or an implemented fix with a passing regression
test,
- and the instrumentation is removed unless it remains necessary.
The blocked branch is complete when the feedback loop cannot be built after
the documented attempts, the missing artifact or access is named, and no root
cause or fix is claimed.
Deep Reference
Use REFERENCE.md for full phase instructions, loop construction
patterns, and the HITL script at
scripts/hitl-loop.template.ps1. Use
EXAMPLES.md for concrete diagnosis loops.
