trace

# Trace Root cause, not symptom. Never patch over a bug without understanding why it happened. Dispatcher and reviewer — Opus 4.7 (thinking-tier). Implementer/Searcher/Writer — Sonnet 4.6. ## Per-Step Agent Map (DOCTRINE rule 12) Every substantive step dispatches at least one Agent. | Step | Worker tier | Thinking tier | Notes | |---|---|---|---| | 1 — Reproduce | Searcher (Sonnet) if repro missing | **Reviewer** (Opus) confirms repro is valid | Both tiers if dispatched | | 2 — Gather evidence | Searcher × 3 (Sonnet) parallel | **Reviewer** (Opus) verifies evidence coverage | Both tiers | | 3 — Hypothesize | — | **Debugger** (Opus) produces ranked hypotheses | Pure thinking | | 4 — Verify | Implementer (Sonnet) minimal change | **Debugger** (Opus) re-evaluates against evidence | Both tiers · loop | | 5 — Fix at root | Implementer (Sonnet) | **Reviewer** (Opus) checks no error-swallow / no symptom-patch | Both tiers | | 6 — Regression test | Writer (Sonnet) | **Reviewer** (Opus) confirms test fails-without / passes-with | Both tiers | | 7 — Memory + final | Writer (Sonnet) appends pitfall | **Reviewer** (Opus) final validation | Both tiers | ## Step 1 — Reproduce Agents — `Searcher` (Sonnet, if needed) ⇒ **Reviewer** (Opus). 1. Confirm the bug is reproducible. 2. If repro steps missing — dispatch `Searcher — locating bug reproduction in recent changes/tests`. 3. Dispatch `**Reviewer** — confirming reproduction is valid` to validate the repro actually fails for the stated reason (not a flake). 4. If environmental (CI-only, intermittent, time-dependent) — flag explicitly before proceeding. ## Step 2 — Gather Evidence (parallel) Agents — `Searcher` × 3 (Sonnet) parallel ⇒ **Reviewer** (Opus). 1. 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)` 2. Dispatch `**Reviewer** — verifying evidence coverage` to confirm the three Searchers actually triangulate the failure surface. If gaps remain, redispatch. ## Step 3 — Hypothesize Agents — **Debugger** (Opus, thinking-tier). Dispatch `**Debugger** — root cause analysis: <bug-summary>` — model: opus. Apply **5 Whys** + **hypothesis testing** + **bisect mindset**: - Why does this fail? → because X → why X? → because Y → continue to root - Output 1–3 hypotheses ranked by likelihood, each with: - **What** — suspected root cause - **Evidence** — what supports it - **Counter-evidence** — what would falsify it - **Test** — minimal change to verify ## Step 4 — Verify Agents — `Implementer` (Sonnet) ⇒ **Debugger** (Opus). 1. Pick highest-ranked hypothesis. 2. Dispatch `Implementer — verifying hypothesis: <hypothesis>` — make the minimal change needed to confirm/falsify. 3. Dispatch `**Debugger** — re-evaluating hypothesis against test result` to re-check against the evidence from Step 2. 4. Confirmed → proceed to Step 5. Falsified → return to Step 3 with next hypothesis. ## Step 5 — Fix at Root Agents — `Implementer` (Sonnet) ⇒ **Reviewer** (Opus). 1. Dispatch `Implementer — fixing root cause: <root-cause>` with full context: the bug, the verified root cause, the minimal fix. 2. Dispatch `**Reviewer** — checking fix is at root` to verify the fix actually addresses the cause and doesn't patch the symptom. Constraints (non-negotiable): - No error swallowing - No defensive try/catch around the symptom - No flags or feature gates to hide the bug ## Step 6 — Regression Test Agents — `Writer` (Sonnet) ⇒ **Reviewer** (Opus). 1. Dispatch `Writer — adding regression test for <bug>`. 2. Dispatch `**Reviewer** — confirming regression test fails-without and passes-with the fix`. 3. If existing suite had gaps that allowed this bug → note in `.hyperflow/memory/pitfalls.md`. ## Step 7 — Memory + Final Review Agents — `Writer` (Sonnet) ⇒ **Reviewer** (Opus). 1. Dispatch `Writer — appending pitfall to .hyperflow/memory/pitfalls.md` per [memory-system.md](../hyperflow/memory-system.md): the bug pattern, why tests missed it, prevention strategy. Tags — `pitfall` plus domain tags. 2. Dispatch `**Reviewer** — final validation of fix + test + memory entry`. This is the integration review for the trace flow. ## Anti-Patterns (refuse these) | Symptom patch | Why it's wrong | |---|---| | "Just catch the exception" | Find why it threw | | "Add a null check" | Find why it was null | | "Increase the timeout" | Find why it's slow | | "Retry on failure" | Understand the failure mode first | ## Output Format ``` ── Debug Result ───────────────────── Bug: <one-line> Reproducible: yes / no / intermittent Root cause: <one-line> Fix: <one-line summary> Files changed: <list> Regression test: <path> ───────────────────────────────────── ``` End with usage summary (model names, agent count, token totals) per [output-style.md](../hyperflow/output-style.md). ## Hand-off Debug is **off the auto-chain** — it's standalone. After Step 7 reviewer passes, stop and suggest `/hyperflow:deploy` to run pre-push gates and commit the fix + regression test together. Do **not** auto-invoke ship — push requires explicit user opt-in. ## Doctrine Full rules in [DOCTRINE.md](../hyperflow/DOCTRINE.md). See also [worker-prompt.md](../hyperflow/worker-prompt.md) and [reviewer-prompt.md](../hyperflow/reviewer-prompt.md).