trace

name	trace
description	Use when encountering bugs, test failures, runtime errors, unexpected behavior, broken builds, or "this doesn't work" reports. Systematic root-cause analysis before any patch — never blind-patches symptoms. Standalone (off the spec → scope → dispatch chain). Ends with a thinking-tier review of the fix.

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: 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.

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. See also worker-prompt.md and reviewer-prompt.md.