analyze

name	analyze
description	Structured root-cause analysis (5-whys / fishbone / fault-tree) for a confirmed problem. Use when a failure's cause is unknown, or /analyze. Not for the executor's in-wave REVISE debug or unconfirmed bugs.

Analyze

You find the root cause of a confirmed problem with a named method, not a guess. You select the method by the problem's shape, rank competing hypotheses by evidence (not intuition), and report a confidence-scored cause with a fix direction. You surface; you do not fix (the executor does). Complements the in-wave debug-protocol (that is the REVISE-loop discipline executor applies per wave); analyze is the standalone, deeper RCA you reach for when a cause spans waves or the obvious fix failed.

What this does / does not do

Does: confirm + reproduce the problem, select an RCA method by shape, apply it, rank hypotheses on the evidence hierarchy, and write a receipt naming the root cause, its confidence, and a fix direction. Does not: implement the fix (executor), challenge a solution's design (adversary), or analyze an unconfirmed/intermittent symptom (reproduce it first, or this is speculation).

When NOT to use

• The cause is already known — go straight to the fix (executor); analyze adds nothing.
• The failure is inside a single executor wave's REVISE loop — that is debug-protocol, applied inline, not a standalone analyze.

Reference Routing

Situation	Reference
The in-wave RCA discipline (feedback-loop-first, 3-strike)	engine/shared/references/debug-protocol.md
The "bug" may be the agent's own context, not the code	engine/shared/references/context-degradation.md
Receipt write delegation	engine/shared/references/script-delegation-contract.md

Inputs

Field	Required	Description
problem	yes	the confirmed problem statement (what is wrong, observably)
evidence	yes	reproduction, logs, artifacts — the grounding for any hypothesis
scope	no	where to look (a module, a flow); bounds the search

How to do it

Step 1 — Confirm + reproduce

A root-cause analysis of an unreproduced symptom is speculation. Confirm the problem deterministically first (or narrow conditions until you can). If it cannot be reproduced, say so and stop.

Step 2 — Select the method by shape

Problem shape	Method	Why
a linear causal chain (one thing led to another)	5-whys	drills the chain to the first controllable cause
multiple contributing factors / a recurring anomaly	fishbone	enumerates factor categories so none is missed
an integrity / safety / "how could this fail" question	fault-tree	decomposes a top failure into its sufficient conditions

Step 3 — Apply the method

Work the chosen method against the evidence. Generate the candidate causes it surfaces; do not stop at the first plausible one.

Step 4 — Rank by evidence, not intuition

Use the evidence hierarchy (controlled reproduction > primary artifact > multi-source > single inference

circumstantial). The top-ranked cause is the one with the strongest evidence, not the most familiar.

Step 5 — Report cause + fix direction + receipt

Name the root cause, its confidence (drop it when the evidence is thin or contradictory — context-degradation.md), and a fix direction (not the implementation). Write the receipt.

Output Contract

analyze receipt (<workspace>/receipts/analyze-receipt-<timestamp>.json): base + method (5-whys/fishbone/fault-tree), root_cause, hypotheses (array, each with evidence + rank), evidence_strength (controlled/primary/multi-source/inference/circumstantial), fix_direction, reproduced (bool), confidence. persistence: Spec-Anchored.

Proactive Triggers

• The symptom can't be reproduced: stop — RCA on an unreproduced symptom is a guess; narrow first.
• The first plausible cause is accepted without ranking: apply the evidence hierarchy; the familiar cause is not always the evidenced one.
• Three fixes have failed: the debug-protocol 3-strike rule applies — question the architecture, do not generate a fourth symptom-level hypothesis.
• A hypothesis rests on a long, unverified context: it may be context-degradation, not a code defect — rule that out before asserting a cause.

Completion Criteria

Done when: a receipt names the root cause with its method, the ranked hypotheses + evidence strength, a fix direction, and a confidence that reflects the evidence; the problem was reproduced (or its non-reproducibility is recorded).

Not done if: a cause was asserted without reproduction; the first plausible cause was taken without ranking; analyze implemented a fix; confidence stayed high on thin/contradictory evidence.

Next step: the executor applies the fix in the indicated direction (and writes the regression test first, per debug-protocol); shift handles it if the cause is a spec-implementation drift.

Related Skills

• executor / debug-protocol: The in-wave REVISE discipline + who fixes. analyze surfaces the cause; executor fixes it.
• hunt: Tests whether a hypothesis is real (TP/FP/GAP); analyze finds why once it is confirmed real.
• shift: Owns the case where the root cause is the spec drifting from the implementation.