trace

# Trace

Root cause, not symptom. Never patch over a bug without understanding why it happened.

All agents inherit the session model. Reviewers and Debuggers bold-labeled; Workers plain.

## Per-Step Agent Map (DOCTRINE rule 12)

Every substantive step dispatches at least one Agent. Atomic steps (per DOCTRINE 12.2.8) are a single Worker → Reviewer pair with no independent angles to fan out.

| Step | Status | Workers | Reviewers | Notes |
|---|---|---|---|---|
| 1 — Reproduce | Atomic (12.2.8) | Searcher | **Reviewer** | Runs if repro missing; single Worker→Reviewer pair |
| 2 — Gather evidence | Atomic (12.2.8) | `searcher` specialist × 3 | **Reviewer** | 3 parallel Searchers → single Reviewer; one Worker-group→Reviewer pair |
| 3 — Hypothesize | Atomic (12.2.8) | **`debugger` specialist** | **Reviewer** | Single Debugger (5 Whys + ranked hypotheses); may fan out Step 4 across hypotheses (rule 18) |
| 4 — Verify | 2 sub-phases | Implementer × N | **Debugger** · **Reviewer** | 4a: parallel Implementers → Reviewer; 4b: Debugger re-evaluation → Reviewer |
| 5 — Fix at root | Atomic (12.2.8) | Implementer × N | **Reviewer** | N Implementers (one per file) → Reviewer; single Worker-group→Reviewer pair |
| 6 — Regression test | Atomic (12.2.8) | Writer | **Reviewer** | Single Writer → single Reviewer; no parallel angle |
| 7 — Memory + final | Atomic (12.2.8) | Writer | **Reviewer** | Single Writer → integration Reviewer; no parallel angle |

## Step 1 — Reproduce

Atomic — single Searcher → Reviewer pair (DOCTRINE 12.2.8). No parallel angles: artifact retrieval is a single-scope search when the symptom is unknown.

If the user supplied a stack trace, test name, or log snippet — skip the Worker dispatch entirely (Step 1 is then trivially fulfilled by existing input; proceed to Step 2).

Otherwise dispatch `Searcher — locating bug reproduction in recent changes/tests`.

Collect: failing test name or command, error message, stack trace, log lines, recent commits touching the affected surface.

Then dispatch `**Reviewer** — confirming reproduction is valid` with the collected artifacts.

Reviewer confirms:
- The failure is consistent and deterministic (or flags intermittent).
- The error matches the stated symptom.
- The repro is not a test-environment artifact (missing seed data, wrong env vars, clock skew).

If environmental (CI-only, intermittent, time-dependent) — flag explicitly before proceeding to Step 2.

## Step 2 — Gather Evidence

Atomic — one Worker-group (3 parallel Searchers) → single Reviewer pair (DOCTRINE 12.2.8). The three Searchers are parallel angles inside one sub-phase, not independent sub-phases. They are dispatched as the [`searcher`](../../agents/searcher.md) specialist — path-anchored evidence, read-only, no fan-out.

Dispatch simultaneously in a single message:
- `Searcher — reading error stack traces and logs`
- `Searcher — mapping the code paths involved`
- `Searcher — finding related tests (passing and failing)`

Each Searcher writes its findings as a structured list: file paths, line numbers, key values, timestamps.

Then dispatch `**Reviewer** — verifying evidence coverage` over all three Searcher outputs.

Reviewer confirms the three Searchers actually triangulate the failure surface. If gaps remain (e.g., no log found, code path incomplete), the Reviewer names specific missing angles — re-run the Searcher(s) for those gaps only, then re-run the Reviewer. Repeat until coverage is confirmed.

**Failure recovery:** Searcher tool errors and NEEDS_REVISION verdicts follow DOCTRINE rule 14 (`skills/hyperflow/failure-recovery.md`). For trace specifically, a Searcher that aborts mid-evidence-gathering leaves the debugger with incomplete coverage — flag the gap explicitly in the Step 3 Reviewer output and carry it forward as a known uncertainty in the root-cause synthesis. Do not silently proceed as if evidence is complete.

## Step 3 — Hypothesize

Atomic — single Debugger → Reviewer pair (DOCTRINE 12.2.8). 5 Whys and hypothesis ranking are a single sequential reasoning task; one Debugger call produces both in one pass.

Dispatch `**Debugger** — 5 Whys + hypothesis ranking: <bug-summary>` — the [`debugger`](../../agents/debugger.md) specialist agent, carrying its charter (root-before-symptom, written 5-Whys chain, web-research-first on a gated flow for known-issue/changelog lookups). When ≥ 2 hypotheses are genuinely independent, the debugger may **fan out** Step 4 verification across them (depth 1, ≤ 3 sub-workers — DOCTRINE rule 18); a single-hypothesis bug never fans out.

Single call produces:

**Part A — 5 Whys causal chain** (depth-first):
- Why does this fail? → because X → why X? → because Y → continue to root.
- Goal: reach a structural cause (data contract violation, state mutation, missing guard, timing assumption), not a surface symptom.
- Output: one causal chain ending at the deepest reachable root.

**Part B — Hypothesis fan-out** (using Part A's causal chain):
- Emit 1–3 ranked hypotheses. Each must include:
  - **What** — suspected root cause
  - **Evidence** — what from Step 2 supports it
  - **Counter-evidence** — what would falsify it
  - **Test** — minimal change to verify (used by Step 4)

Then dispatch `**Reviewer** — validating causal chain and hypothesis set` over the Debugger's output.

Reviewer confirms the causal chain reaches a structural root (not a symptom) and that each hypothesis is independently testable.

## Step 4 — Verify

Two sub-phases (genuine sequential dependency: 4b depends on 4a results; 4b Debugger does substantive re-evaluation work, not a pure review pass).

### Step 4a — Minimal change verification

Workers: `Implementer` × N parallel, where N = number of hypotheses to test. One Implementer per hypothesis dispatched simultaneously.

- `Implementer — verifying hypothesis 1: <hypothesis-1-test>` — make the minimal change to confirm/falsify
- `Implementer — verifying hypothesis 2: <hypothesis-2-test>` (if applicable)

Each