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 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 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 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 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 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. 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 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. 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 Reviewer pair (DOCTRINE 12.2.8). N Implementers are parallel angles inside one Worker-group; the Reviewer gates the group output.

Dispatch one Implementer per affected file simultaneously (or one Implementer total if single-file):

• Implementer — fixing root cause in <file-1>: <change-description>
• Implementer — fixing root cause in <file-2>: <change-description> (if applicable)

Each Implementer receives: the bug, the verified root cause from Step 4b, the minimal change. No extra refactoring, no opportunistic cleanup — root cause only.

Constraints (non-negotiable):

• No error swallowing
• No defensive try/catch around the symptom
• No flags or feature gates to hide the bug

Then dispatch **Reviewer** — checking fix is at root over all Implementer outputs.

Reviewer verifies:

• The fix addresses the confirmed root cause from Step 4b, not the symptom.
• No constraint violations (error-swallow, try/catch workaround, feature gate).
• Files changed are internally consistent (no partial fix across N files).

On rejection — loop Step 5 with the Reviewer's specific objection attached. Do NOT commit until Step 5 passes.

Step 6 — Regression Test

Atomic — single Writer → single Reviewer pair (DOCTRINE 12.2.8). Test authorship has no parallel angle: two Writers would produce duplicate or conflicting tests.

Dispatch Writer — adding regression test for <bug>.

The test must:

• Exercise the exact code path that was broken.
• Assert the behavior that was missing (not just assert the fix is present).
• Be named to describe the bug scenario, not the implementation.

Then dispatch **Reviewer** — confirming regression test fails-without and passes-with the fix.

Reviewer process:

1. Mentally (or via Bash) revert the Step 5 fix.
2. Confirm the new test fails in the broken state.
3. Re-apply the fix.
4. Confirm the test passes in the fixed state.

If the test passes both with and without the fix — reject; Writer rewrites. The test must demonstrably distinguish the buggy and fixed states.

If existing suite had coverage gaps that allowed this bug → note for Step 7.