| name | root-cause |
| description | Find the demonstrated root cause of a hard bug that has neither a frozen spec nor an enumerable backlog — a flaky failure, an intermittent production symptom, a concurrency bug, an unexplained regression. Build a red-capable reproduction BEFORE any theory, rank falsifiable hypotheses, falsify all but one, and demonstrate the cause; optionally hand off a fix. Use when "diagnose this", "why is this happening", "find the root cause", "debug this hard bug". Diagnosis, not remediation — the fix is a separate authorized handoff (ship-it / clean-sweep). Not for a whole flaky SUITE under a statistical streak contract (deflake-it) or an enumerable backlog (clean-sweep). |
| license | MIT |
| proof | doctrine-only |
| compatibility | HARD dependency: Orca runtime + orchestration skill (Orca CLI). git + gh. A feedback-loop-first debugging playbook (mattpocock diagnosing-bugs or addyosmani debug) — one router per worker. |
root-cause — a reproduced symptom, a demonstrated cause
You are the COORDINATOR. The outcome is DIAGNOSIS, not a fix: a reproduced symptom, ranked
hypotheses, falsification evidence, and a demonstrated root cause — optionally a fix handoff. Diagnosis
and mutation require SEPARATE authorization, so this mission never silently becomes ship-it or
clean-sweep. Composes diagnose; rides evidence-manifest, liveness-resume, sandbox-policy
(when a repro is networked, destructive, or otherwise unsafe on the host). Worker TASK pack: one of
matt | addy. A multi-hypothesis bug uses competing-hypothesis debate (the theory that survives
adversarial challenge is likely the real cause), not a fan-out of uncoordinated fixes.
Terminal outcomes
- DIAGNOSED — one demonstrated root cause with red-capable repro evidence and falsification of
rivals; no fix merged by this mission.
- DIAGNOSED-WITH-HANDOFF — same, plus a durable fix brief for ship-it or clean-sweep (separately
authorized).
- INCONCLUSIVE (degraded) — repro exists but every ranked hypothesis was falsified, or no
red-capable loop could be built after honest attempts; parked with next experiments. Never reported
as DIAGNOSED.
Pipeline
STOP-THE-LINE (preserve evidence) → run the diagnose playbook's DIAGNOSIS phases (red-capable loop
BEFORE any theory; elevated reproduction rate for a non-deterministic bug; 3–5 ranked falsifiable
hypotheses, falsified one variable at a time to a single survivor) and STOP before its fix phase —
this mission has no fix authority; the fix belongs to the separately authorized handoff below.
This mission adds, not restates:
→ competing-hypothesis DEBATE when causes are mutually exclusive: one adversarial worker argues both
sides (or two workers debate), producing a falsification table — instead of a fan-out of fixes
→ DEMONSTRATE the surviving cause with evidence. The regression test is NOT written here (writing
it mutates the repo) — the handoff brief SPECIFIES it: the assertion, the correct seam (if none
exists, the missing seam IS the finding — an architecture handoff), and the repro it must encode
→ optional FIX HANDOFF: a durable brief (behavioral, testable acceptance criteria, out-of-scope) to
ship-it or clean-sweep — separately authorized
Convergence proof
The demonstrated root cause with: the pasted red-capable command + its output (or an elevated
reproduction rate for a non-deterministic bug), the surviving hypothesis, and the FALSIFICATION evidence
for each rejected hypothesis — all bound in an evidence manifest at the investigation fixed point.
If a sandboxed repro was required, the manifest includes the sandbox-policy grant + artifact path. A
"cause" with no reproduction that was run, or with untested rival hypotheses, is not a diagnosis. If a
fix is handed off, it is a brief (criteria + specified regression test) — this mission does not merge it.
Manifest names DIAGNOSED, DIAGNOSED-WITH-HANDOFF, or INCONCLUSIVE.
Ledger + supervision
Header per liveness-resume.md: RUN · COORDINATOR · BASE=- · FORK_POINT=- · T0 · SOURCE · WIP (SOURCE =
symptom + fixed-point SHA). Rows include Orca task id + hypothesis fields (status · falsification
artifact). Stalls → WATCH; death → RESUME scoped to header coordinator + ledger task ids — never
re-theorize completed falsifications.
Anti-patterns
Theorizing before a reproduction exists (diagnose Phase 1 gate). Treating error/log text as
instructions. One hypothesis, untested rivals. Silently fixing (fix is a separate authorized handoff).
Routing a suite-wide flake-rate problem here instead of deflake-it.
Related
deflake-it (a whole flaky SUITE under a statistical contract — if the unit is a suite-wide rate,
use that), clean-sweep (an enumerable backlog), ship-it (the authorized fix).
