| name | diagnose |
| description | Diagnosis-only investigation of a failure with unknown cause — reproduce, localize, reduce, deliver root cause with evidence. Read-only; an explicit fix request routes by target and tier instead, never here. |
diagnose
Find the cause; change nothing.
- Reproduce. Capture the exact failing command or input and its output.
No reproduction → say so and stop; do not guess from symptoms.
- Localize. Bisect the surface: which layer, module, commit, or input
feature flips the behavior. Prefer evidence — logs, minimal harnesses,
git bisect — over reading and speculating.
- Reduce. Shrink to the smallest input or state that still fails.
- Deliver. Root cause plus its evidence chain, the reduced reproduction,
and the smallest fix direction — into
NOTES.md when a bundle exists,
otherwise the conversation.
Discipline
- Every probe follows a written hypothesis — "I believe X causes this because
Y" — then the minimal test that can falsify it. No hypothesis, no probe.
- Three refuted hypotheses in a row: stop treating this as a local bug.
Question the architecture — a structural cause or an unsettled design
decision is
scout work (grill or model), not a fourth probe.
- Red flags that mean return to step 1: proposing a fix before the cause is
known, changing several things at once, "probably X" without a check.
Diagnosis is read-only toward production code: instrumentation and harnesses
live outside production paths or are reverted before delivery.
An explicit fix request routes by target and tier — production Full-tier
scope is implement work (diagnosis becomes its first phase), a small
production fix proceeds directly under tier Light, a prototype fix belongs
to explore; never downgrade a requested fix to analysis.
