trace

What this skill does

# Trace

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

Dispatcher and reviewer — Opus 4.8 (thinking-tier). Implementer/Searcher/Writer — Sonnet 4.6.

## 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 | Worker tier | Thinking tier | Notes |
|---|---|---|---|---|
| 1 — Reproduce | Atomic (12.2.8) | Searcher (Sonnet) | **Reviewer** (Opus) | Runs if repro missing; single Worker→Reviewer pair |
| 2 — Gather evidence | Atomic (12.2.8) | Searcher × 3 (Sonnet) | **Reviewer** (Opus) | 3 parallel Searchers → single Reviewer; one Worker-group→Reviewer pair |
| 3 — Hypothesize | Atomic (12.2.8) | **Debugger** (Opus) | **Reviewer** (Opus) | Single Debugger (5 Whys + ranked hypotheses in one pass) → Reviewer |
| 4 — Verify | 2 sub-phases | Implementer × N (Sonnet) | **Debugger** (Opus) · **Reviewer** (Sonnet) | 4a: parallel Implementers → Sonnet Reviewer; 4b: Debugger re-evaluation → Reviewer |
| 5 — Fix at root | Atomic (12.2.8) | Implementer × N (Sonnet) | **Reviewer** (Opus) | N Implementers (one per file) → Opus Reviewer; single Worker-group→Reviewer pair |
| 6 — Regression test | Atomic (12.2.8) | Writer (Sonnet) | **Reviewer** (Opus) | Single Writer → single Reviewer; no parallel angle |
| 7 — Memory + final | Atomic (12.2.8) | Writer (Sonnet) | **Reviewer** (Opus) | 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` (Sonnet).

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` (Opus) 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.

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

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

Then dispatch `**Reviewer** — verifying evidence coverage` (Opus) 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>` (Opus).

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` (Sonnet) 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 (Sonnet) 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 Implementer makes only the change described in the hypothesis's **Test** field from Step 3. No additional cleanup, no reformatting. Run the failing test/command after each change and capture the result.

If only one hypothesis exists — single Implementer is justified (no parallel angle; single-Worker sub-phase per DOCTRINE 12.2.3 single-Worker exception).

Reviewer: `Reviewer — checking verification results are deterministic` (Sonnet) over the Implementer outputs. Confirms each test run is deterministic and the result cleanly maps to a confirm/falsify verdict.

**Failure recovery (4a):** Implementer tool errors and NEEDS_REVISION verdicts follow DOCTRINE rule 14 (`skills/hyperflow/failure-recovery.md`). An Implementer that aborts or cannot confirm/falsify its hypothesis marks that hypothesis `INCONCLUSIVE` — the chain does not abort. Other hypotheses proceed normally; the 4b Debugger receives the full set including any INCONCLUSIVE entries.

### Step 4b — Re-evaluation + loop gate

Worker: `**Debugger** — re-evaluating hypotheses against verification results` (Opus). Substantive reasoning — the Debugger compares hypothesis predictions against actual test outcomes and decides the next branch. Not a pass/fail check: the Debugger may emit `CONFIRMED`, `FALSIFIED ALL`, or `PARTIALLY CONFIRMED` with new directions.

Reviewer: `Reviewer — confirming re-evaluation verdict is sound` (Sonnet) over the Debugger's verdict.

**Failure recovery (4b):** Debugger tool errors and NEEDS_REVISION verdicts follow DOCTRINE rule 14 (`skills/hyperflow/failure-recovery.md`). A failed 4b Debugger dispatch does not abort the chain; retry once, then escalate to thinking-tier. If all attempts fail, mark the entire verify step as `INCONCLUSIVE` and surface to the user — do not advance to Step 5 without a root-cause verdict.

Debugger verdicts:
- `CONFIRMED <hypothesis-N>` → proceed to Step 5 with that hypothesis as the confirmed root cause.
- `FALSIFIED ALL` → loop back to Step 2 with a broader evidence scope.
- `PARTIALLY CONFIRMED` → redispatch Step 4a for the leading candidate with a tighter test.

Revert all minimal changes from 4a before entering Step 5 (the real fix goes in Step 5, not here).

## Step 5 — Fix at Root

Atomic — one Worker-group (N parallel Implementers) → single Opus Reviewer pair (DOCTRINE 12.2.8). N Implementers are