debugging

---
name: debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---

# Systematic Debugging

## Overview

<!-- CANONICAL: shared/dispatch-convention.md -->
All subagent dispatches use disk-mediated dispatch. See `shared/dispatch-convention.md` for the full protocol.

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

**Models:** Quick structural mapping requests `fast`; investigation, synthesis, and implementation request `high`. The Claude Code examples use current reference aliases such as `model: haiku` and `model: opus`; other harnesses map supported profiles or omit unsupported model fields per `shared/model-tier-policy.md`.

## Communication Requirement (Non-Negotiable)

**Between every agent dispatch and every agent completion, output a status update to the user.** This is NOT optional — the user cannot see agent activity without your narration.

Every status update must include:
1. **Current phase** — Which debugging phase you're in
2. **Hypothesis status** — Current hypothesis being tested (or "forming hypothesis")
3. **What just completed** — What the last agent reported (investigation findings, fix results)
4. **What's being dispatched next** — What you're about to do and why
5. **Cycle count** — Which hypothesis cycle you're on (cycle 1, cycle 2, etc.)

**After compaction:** Re-read the session state from the scratch directory (see Session State below) and output current status before continuing.

**This requirement exists because:** Debugging sessions can involve multiple investigation rounds and fix attempts. Without narration, the user has no visibility into which hypotheses have been tried, what evidence was found, or why the orchestrator is pursuing a particular path.

**Execution model:** The orchestrator dispatches all investigation and implementation to subagents. The orchestrator NEVER reads code, edits files, or runs tests directly. It forms hypotheses, dispatches work, and makes decisions based on subagent reports.

**Depth principle:** When in doubt, dispatch MORE investigation agents, not fewer. A bug that looks simple from the surface often has a complex root cause. Spinning up 4-6 focused investigators in parallel costs minutes; missing the root cause costs hours.

## Pipeline Status

Write a status file to `~/.claude/projects/<hash>/memory/pipeline-status.md` at every narration point. This file is overwritten (not appended) and provides ambient awareness for the user in a second terminal.

### Write Triggers

Write the status file at every point where the Communication Requirement mandates narration: before dispatch, after completion, phase transitions, health changes, escalations, and after compaction recovery.

### Status File Format

The status file uses this structure (overwritten in full each time):

```
# Pipeline Status
**Updated:** <current timestamp>
**Started:** <timestamp from first write — persisted across compaction>
**Skill:** debugging
**Phase:** <current phase, e.g. "Synthesis", "4 — Implementation">
**Health:** <GREEN|YELLOW|RED>
**Suggested Action:** <omit when GREEN; concrete one-sentence action when YELLOW/RED>
**Elapsed:** <computed from Started>

## Recent Events
- [HH:MM] <most recent event>
- [HH:MM] <previous event>
(last 5 events, newest first)
```

### Skill-Specific Body

Append after the shared header:

```
## Investigation
- Hypothesis: "Missing null check in event handler dispatch chain"
- Cycle: 2 of 4 max
- Phase 4 fix attempts: 1 (WIP commit pending verification)

## Compression State
Goal: [original user request / bug report]
Key Decisions:
- [accumulated decisions, max 10]
Active Constraints:
- [constraints affecting remaining investigation]
Next Steps:
1. [immediate next action]
2. [subsequent actions]
```

### Health State Machine

Health transitions are one-directional within a phase: GREEN -> YELLOW -> RED. Phase boundaries reset to GREEN.

- **Phase boundaries** (reset to GREEN): Phase 0->1, 1->Synthesis, Synthesis->2, 2->3, 3->4, 4->4.5, 4.5->5. Sub-phases (3.5, within Phase 3; 4.4, within 4->4.5) do NOT reset.
- **YELLOW:** hypothesis cycle 3+, quality gate round 5+, fix retry in progress
- **RED:** escalation pending, stagnation detected, 3 fix failures reached

When health is YELLOW or RED, include `**Suggested Action:**` with a concrete, context-specific sentence (e.g., "Third hypothesis attempted. Consider narrowing the search space or providing additional context.").

### Inline CLI Format

Output concise inline status alongside the status file write:
- **Minor transitions** (dispatch, completion): one-liner, e.g. `Phase 1 [cycle 2] Investigating: null check hypothesis | GREEN | 34m`
- **Phase changes and escalations**: expanded block with `---` separators
- **Health transitions**: always expanded with old -> new health

### Compaction Recovery

After compaction, before re-writing the status file:
0. Read the `## Compression State` section from `pipeline-status.md` — recover Goal, Key Decisions, Active Constraints, and Next Steps. If absent, skip to step 1.
1. Read the rest of `pipeline-status.md` to recover `Started` timestamp and `Recent Events` buffer
2. Reconstruct phase, health, and skill-specific body from internal state files (see Session State below)
3. Emit a Compression State Block into the conversation to seed the new context window
3.5. **Read session index summary (supplementary):** If the CSB Scratch State contains a `Session Index:` path, or if globbing `~/.claude/projects/<hash>/memory/session-index/*/summary.md` finds a recent file, read `summary.md`. Include the Activity Timeline, Files Modified, and Key Decisions sections in the post-compaction narration. If no session index exists, skip silently — this step is purely additive. If `summary.md` lacks detail for a specific event type (e.g., errors, hypothesis changes, file modifications), use `/recall` to query `events.jsonl` with filters for targeted recovery.
4. Write the updated status file
5. Output inline status to CLI

## Session State and Compaction Recovery

The debugging skill writes session state to disk at **every phase transition**, not just on failure. This ensures compaction recovery works regardless of when it occurs.

**Scratch directory:** `/tmp/crucible-debug-<session-id>/` where `<session-id>` is a timestamp generated at the start of the debugging session.

**Write at each phase transition:**
- `phase-state.md`: current phase, cycle count, current hypothesis (if formed), and
  `wip-sha-<cycle>:` (where `<cycle>` is the same N as `pre-debug-fix-cycle-N` — the
  current hypothesis cycle's Phase 4 WIP commit SHA, once recorded — see Commit Strategy;
  **never drop a given cycle's key on a subsequent phase-transition write**)
- `hypothesis-log.md`: running hypothesis log (updated at Phase 3, after Phase 4 results)
- `synthesis-report.md`: latest synthesis report (written after Synthesis completes)
- `implementation-details.md`: cumulative record of implementation attempts — what was tried, which files changed, regressions encountered, why it failed (appended after each Phase 4)
- `where-else-state.md`: Phase 4.5 state — pre-Phase-4.5 SHA, generalized pattern, siblings found/fixed/remaining (written during Phase 4.5, read during compaction recovery)
- `scope-check-<cycle>.md` (where `<cycle>` is the hypothesis cycle count, the same N as `pre-debug-fix-cycle-N`): Phase 4.4 state for the current hypothesis cycle — verdict (from the closed set in Phase 4.4, including the skip/unparseable outcomes), flagged paths, and confidence, or the reason no usable verdict exists (written after Phase 4.4 runs or is skipped, read during compaction recovery)

At each phase transition, in addition to writing session state files, emit a Compression State Block into the conversation. The block captures the reasoning layer (goal, decisions, constraints, next steps) that the session state files do not.

### Checkpoint Timing

Emit a Compression State Block at:
- **Phase transitions:** 0→1, Synthesis→3, 3.5→4, 4.5→5 — emit a **Phase Handoff Manifest** (see below) instead of a Compression State Block at these major boundaries. Other transitions (1→Synthesis, Synthesis→2, 2→3, 3→3.5, 4→4.5) continue to use CSBs. (Phase 4.4 is a sub-phase within 4→4.5 and does not emit its own CSB.)
- **Hypothesis cycles:** After each hypothesis is formed or invalidated
- **Fix attempts:** After each Phase 4 implementation attempt completes (success or failure)
- **Escalations:** Before any escalation to user
- **Health transitions:** On any GREEN->YELLOW or YELLOW->RED transition

**Context hygiene:** After synthesis completes, raw Phase 1 investigation reports are superseded by the synthesis report. The orchestrator should rely on the synthesis report going forward, not the raw reports. After Phase 4 completes (success or failure), the Phase 2 pattern analysis report is superseded by the implementation results. This keeps the orchestrator lean across long sessions.

**Compaction recovery:**
0. Check for handoff manifests (`handoff-*-to-*.md`) in the scratch directory. If the most recent manifest exists, use its Inputs, Decisions, and Constraints to reconstruct state for the current phase — this supersedes session state files for phase-boundary recovery. If no manifest exists, continue with standard recovery.
1. Read `phase-state.md` to determine current phase and cycle.
2. Read `hypothesis-log.md` for hypothesis history.
3. Read `synthesis-report.md` for latest investigation findings.
4. Read `implementation-details.md` for prior fix attempts.
   - Also read `scope-check-<cycle>.md` for the *current* hypothesis cycle (if it exists) — written for every Phase 4.4 outcome, including `SKIPPED-BELOW-THRESHOLD`, `SKIPPED-NO-WIP-COMMIT`, `SKIPPED-HEAD-MISMATCH`, and `UNPARSEABLE`, not only a usable judge verdict — so a resumed run knows Phase 4.4 already ran (or was correctly skipped) for this cycle and does not re-dispatch the scope judge blindly — **presence means Phase 4.4 is done for this cycle and Phase 4.5 may proceed, EXCEPT when the recorded outcome is `SKIPPED-NO-WIP-COMMIT` or `SKIPPED-HEAD-MISMATCH`, which are halts, not completions: do not proceed to Phase 4.5. For `SKIPPED-NO-WIP-COMMIT`, resolve the commit failure, then re-enter Phase 4.4 from the top for this cycle and overwrite the file. For `SKIPPED-HEAD-MISMATCH`, resolve per case (a) or (b) as applicable, overwrite `scope-check-<cycle>.md` with the resulting outcome, before proceeding.**
5. Read `where-else-state.md` (if exists) for Phase 4.5 progress — which siblings have been fixed, which remain.
6. Output status to user and continue from the current phase.

**Cleanup:** Delete scratch directory and `.pipeline-active` marker after debugging completes (Phase 5 passes clean or escalation to user).

### Phase Handoff Manifest

At major phase boundaries (0→1, Synthesis→3, 3.5→4, 4.5→5), write a **handoff manifest** to the scratch directory instead of emitting a Compression State Block. The manifest defines exactly what the next phase needs — an allowlist. Everything not on the manifest is shed.

**Format:**

```markdown
# Phase Handoff: N → M
**Timestamp:** ISO-8601
**Goal:** [original bug report, verbatim]

## Inputs for Phase M
- **[Input name]:** [disk path or inline value]

## Decisions Carried Forward
- [DEC-N] [decision]: [reasoning, one line]

## Active Constraints
- [constraint affecting remaining work]

## Shed Receipt
- [what was shed] → [where it lives on disk]
```

**Rules:**
- After writing the manifest, emit an explicit **shed statement**.
- After writing the manifest, update `## Compression State` in pipeline-status.md with manifest contents.
- CSBs continue at non-major-boundary checkpoint triggers (1→Synthesis, Synthesis→2, 2→3, 3→3.5, 4→4.5, hypothesis cycles, fix attempts, escalations, health transitions). Phase 4.4 is a sub-phase within 4→4.5 and emits no CSB for its own phase transition; the escalation and health-transition triggers above apply inside it normally (gate (1) case (b) escalates to the user).
- **Backward compatibility:** If no manifest exists at a recovery point, fall back to CSB-based recovery.

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

If you haven't dispatched Phase 1 investigation and received findings back, you cannot propose fixes. If you haven't received a synthesis report, you cannot form a hypothesis. If you haven't formed a hypothesis, you cannot dispatch implementation.

## When to Use

Use for ANY technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

**Use this ESPECIALLY when:**
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand the issue

**Don't skip when:**
- Issue seems simple (simple bugs have root causes too)
- You're in a hurry (rushing guarantees rework)
- Manager wants it fixed NOW (systematic is faster than thrashing)

---

## The Orchestrator-Subagent Debugging Workflow

All investigation and implementation is delegated to subagents via the Agent tool. The orchestrator handles hypothesis formation, dispatch decisions, and escalation -- nothing else.

### Subagent Model Selection

| Phase | Agent | Model | Rationale |
|-------|-------|-------|-----------|
| Phase 1 | Error Analysis | Opus | Deep code reading and call-chain tracing |
| Phase 1 | Change Analysis | Opus | Cross-file diff analysis |
| Phase 1 | Evidence Gathering | Opus | Multi-component data flow tracing |
| Phase 1 | Reproduction | Opus | Complex reproduction requires reasoning |
| Phase 1 | Deep Dive (any) | Opus | Specialized investigation |
| Synthesis | Consolidation | Opus | Cross-referencing, contradiction detection, and causal reasoning — not just summarization |
| Phase 2 | Pattern Analysis | Opus | Exhaustive comparison requires depth |
| Phase 4 | Implementation | Opus | TDD + root cause fix |
| Phase 4.4 | Scope judge | Sonnet | Semantic traceability check — hypothesis text vs. fix diff, no repo context |
| Phase 4.5 | "Where Else?" scan | Opus | Cross-codebase pattern matching and sibling fixing |
| Phase 5 | Red-team | Opus | Adversarial analysis |
| Phase 5 | Code review | Opus or Sonnet | Lead decides by fix complexity |
| Phase 5 | Test gap writer | Opus | Test authoring requires reasoning |

### Workflow Overview

```
Bug reported / test failure / unexpected behavior
    |
    v
Orchestrator: Parse initial context (error message, failing test, user description)
    |
    v
Phase 0: Repro & scope coherence gate (pass silently / ask one question / flag-and-proceed)
    |  then Load codebase context (crucible:cartographer-skill)
    |
    v
Phase 1: Dispatch 3-6 parallel investigation subagents
    |  +-- Error Analysis agent (always)
    |  +-- Change Analysis agent (always)
    |  +-- Evidence Gathering agent (conditional -- multi-component systems)
    |  +-- Reproduction agent (conditional -- intermittent/unclear bugs)
    |  +-- Deep Dive agents (conditional -- 1-2 focused on specific subsystems)
    |
    v
Synthesis agent: Consolidate all Phase 1 findings -> concise root-cause analysis
    |
    v
Phase 2: Pattern Analysis agent (skipped if synthesis identified obvious root cause)
    |
    v
Phase 3: Orchestrator forms hypothesis (no subagent -- lightweight decision-making)
    |
    v
Phase 3.5: Hypothesis Red-Team (crucible:quality-gate on hypothesis)
    |  -> Survives? Proceed to Phase 4.
    |  -> Torn apart? Reform hypothesis or loop back to Phase 1.
    |
    v
Phase 4: Implementation agent (TDD: failing test, fix, verify)
    |
    v
Orchestrator: Verify fix -> Success? Phase 4.4. Failed? Cleanup, log, loop back.
    -> 3 failures? Escalate to user. If checkpoints exist: "Checkpoints available from prior fix cycles. Restore to a known-good state before manual investigation?"
    |
    v
Phase 4.4: Scope judge — did the fix stay inside the hypothesis? (skipped on small fixes; halts if no WIP commit was created, or if HEAD cannot be confirmed to be this cycle's WIP commit)
    |
    v
Phase 4.5: "Where Else?" scan — find and fix sibling locations
    |
    v
Phase 5: Quality-gate the fix (crucible:quality-gate) + Code review (crucible:temper)
    |
    v
Test Gap Writer (if reviews flagged missing coverage)
    |
    v
Done.
```

---

### Phase -1: Pipeline-Active Marker Check

Before any dispatch work, check for a crashed prior debugging session:

1. **Check `<scratch>/.pipeline-active`** (where `<scratch>` is `~/.claude/projects/<hash>/memory/`)
2. **Not found:** Write the pipeline-active marker (JSON with `pipeline_id` set to current session ID, `skill` set to `"debugging"`, `phase` set to `"0"`, `start_time` set to current ISO-8601 timestamp, `scratch_dir` and `dispatch_dir` paths, `branch` from `git branch --show-current`, `baseline_sha` from `git rev-parse HEAD`). Proceed to Phase 0.
3. **Found, same `pipeline_id`:** Compaction recovery (existing behavior). Do not re-write the marker.
4. **Found, different `pipeline_id`:** Previous debugging session crashed. Check marker's `branch` against current branch — if mismatched, warn the user which branch the crashed session was on. Present to user:
   > "Previous debugging session on branch [marker.branch] crashed. Start fresh? [yes]"
   Delete the stale marker. Write a fresh marker. Proceed to Phase 0. (Full replay orchestration for debugging is deferred -- detection and cleanup only for now.)

**Marker cleanup:** Delete `.pipeline-active` after debugging completes (Phase 5 passes clean or escalation to user), alongside the existing scratch directory cleanup.

### Phase 0: Load Codebase Context

**Repro & scope coherence gate (runs first, before context load).** Before spending the cartographer load and a 3–6-way parallel Opus investigation, confirm the report carries the minimum signal to aim it. This is a cheap, orchestrator-local check — no subagent — against the bug report / user description for three coherence signals:

1. **Symptom** — a concrete, observable wrong behavior (a specific incorrect output, a crash, a failing assertion), not a bare "it's broken" / "doesn't work".
2. **Reproduction** — a failing test, an error message / stack trace, or repro steps — OR an explicit statement that the bug is intermittent / not-yet-reproduced.
3. **Scope** — an identifiable surface: a file, subsystem, feature, or the location named in an error / stack trace.

Decision (best-effort and fast — a well-formed report passes silently with zero added friction):

- **Symptom present AND (reproduction OR scope) present** → proceed to context load — **unless the ONLY reproduction signal is an explicit "intermittent / not-yet-reproduced" statement, in which case skip to the third bullet and apply the Reproduction-lead routing instead**. Otherwise do NOT ask anything; an error/stack trace or failing test already clears the gate with zero friction. Record this outcome as `pass`.
- **Only a vague symptom (no reproduction AND no scope)** → the report is too thin to aim parallel investigators. **When a human is in the loop, ask the user ONE targeted question before dispatch** — request the error text, repro steps, or the affected area — then re-check; if the answer is still below the bar, fall through to flag-and-proceed (do NOT ask a second question). Either way (cleared or still thin), record this outcome as `asked-then-proceeded`. **When running autonomously** — this debugging run was itself dispatched by a parent orchestrator via a dispatch file (no human typed the bug report), or you are otherwise unsure whether a human is in the loop — do NOT block: proceed and apply the Reproduction-lead routing in the next bullet (defaulting toward proceed here is what keeps an autonomous pipeline from hanging on an unanswered question).
- **Symptom is concrete but explicitly not-yet-reproduced (intermittent / "can't trigger it reliably"), or the thin-input autonomous case above** → proceed, and ensure the **Reproduction** investigator is among the dispatched Phase 1 agents, naming *establish a reliable repro* as its lead goal in the Phase 0→1 handoff — **without reducing the agent count the Phase 1 dispatch heuristics call for** (a vague multi-system report still gets the full fan-out those heuristics specify). Record this outcome as `repro-lead-proceeded`.

The gate routes toward debugging's own Phase 1 Reproduction investigator from the front door; it never silently blocks — it either passes, asks exactly one clarifying question, or flags-and-proceeds (the recorded `[DEC-N]` outcome line below IS the flag — there is no separate surfaced warning), mirroring the best-effort discipline of the grudge pre-flight below. Record the gate outcome (`pass | asked-then-proceeded | repro-lead-proceeded`) as a `[DEC-N]` line under `## Decisions Carried Forward` in the Phase 0→1 handoff, so Synthesis and later phases see why Reproduction was prioritized.

**Before any investigation dispatch,** use `crucible:cartographer-skill` (load mode) to pull module context for the area being investigated. If module files exist, include them in every investigator's dispatch file so agents start with structural knowledge instead of wasting turns rediscovering the codebase.

**Defect signature loading (for investigators):**
1. Glob `defect-signatures/*.md` (excluding `*.non-matches.md`) from the cartographer storage directory
2. For each signature, read its `Modules` field and match against the investigation area's modules:
   - Read each cartographer module file's `Path:` field
   - A file is in a module if the file path starts with the module's `Path:` value
   - When the investigation spans multiple modules, load signatures for all matched modules
   - **Directory prefix fallback:** When no cartographer modules exist, match if any target file path starts with any of the signature's `Modules` directory prefixes
3. For matching signatures, validate all file paths still exist on disk — drop stale entries silently
4. Inject into the `[DEFECT_SIGNATURES]` section of `investigator-prompt.md`:
   - Generalized pattern (always)
   - Confirmed siblings list (always)
   - Unresolved siblings list (always)
   - Non-match companion file IS loaded for investigators, truncated to 50 entries at load time with note "(list truncated to 50 most recent entries)"
5. **`Last loaded` update:** Loading is pure-read. After all investigator dispatches complete, batch-update the `Last loaded` field to today on all signatures that were loaded.

**Grudge pre-flight (regression-oracle, #271):** Also query the **Book of Grudges** for the files under investigation and include any matches in the investigators' dispatch files — a past regression on these files is a prime hypothesis. Resolve the helper by absolute path from the plugin root — `plugin_root="$(realpath "<this-skill-base-dir>/../..")"` — and run `python3 "$plugin_root/scripts/grudge_query.py" <files under investigation…>`. Best-effort: if unresolved, emit a one-line stderr warning and continue — never block the investigation. See `skills/grudge/SKILL.md`.

If cartographer data doesn't exist for the relevant area, dispatch a quick Explore agent (`subagent_type="Explore"`, requested profile `fast`; Claude Code maps it to `model: haiku`) to map the relevant directories and note key files. Include its findings in investigator prompts.

### Domain Detection

Check the project's CLAUDE.md for a `## Debugging Domains` table:

```markdown
| Signal | Domain | Skills | Context |
|--------|--------|--------|---------|
| file paths contain `/UI/`, `USS`, `VisualElement` | ui | mockup-builder, mock-to-unity, ui-verify | docs/mockups/ |
| error mentions `GridWorld`, `Tile`, `hex` | grid | - | grid system architecture |
```

**Signal types:** File path patterns (regex against paths in error/stack trace), error message patterns (regex against error text), user description keywords. Evaluate signals in order; load context for all matching domains.

**When domain is detected:**
- Auto-load referenced skills' SKILL.md into investigator prompts (see Domain Context section in investigator-prompt.md)
- Add a domain-specific investigator to Phase 1
- Give Phase 4 implementer domain skill context
- Load files from the Context column

**When no domain table exists:** Proceed normally. Domain detection is opt-in.

**When a referenced skill doesn't exist:** Log a warning and proceed without domain enrichment. Never fail on missing config.

#### Phase Handoff: 0 → 1

Before dispatching investigation agents:

1. Write `handoff-0-to-1.md` with:
   - **Goal:** bug report / user description, verbatim
   - **Inputs for Phase 1:** cartographer module paths, defect signature paths (with match notes), domain context (if any), error messages / stack traces (verbatim), reproduction steps (if any)
   - **Decisions Carried Forward:** (holds the repro-gate outcome line; otherwise typically empty)
   - **Active Constraints:** user-stated constraints
   - **Shed Receipt:** raw cartographer exploration output → module files on disk
2. Emit shed statement: "Phase 0 context shed. Module files, defect signatures, and error context captured in manifest. Raw exploration output is not carried forward."
3. Update `## Compression State` in pipeline-status.md.
4. Do NOT emit a Compression State Block.

---

### Phase 1: Investigation (Parallel Subagent Dispatch)

**Prompt template:** `./investigator-prompt.md`

Dispatch 3-6 investigation subagents in parallel using the Agent tool in a single message. All subagents use `subagent_type="general-purpose"` and request the `high` profile; Claude Code maps that to `model: opus`. Pass all known context (error messages, stack traces, file paths, user description, and cartographer module context from Phase 0) verbatim to each agent -- do not make them search for context you already have.

**Bias toward MORE agents, not fewer.** Each investigator is cheap. Missing a root cause is expensive. When in doubt about whether to dispatch an additional agent, dispatch it.

**Always dispatch:**

1. **Error Analysis Agent** -- Read error messages, stack traces, and logs. Identify the exact failure point, error codes, and what the error is telling us. Trace the call chain backward to the originating bad value.

2. **Change Analysis Agent** -- Check recent changes via git diff, recent commits, new dependencies, config changes, and environmental differences. Identify what changed that could cause this.

**Conditionally dispatch (lean toward dispatching):**

3. **Evidence Gathering Agent** -- For multi-component systems (CI pipelines, API chains, layered architectures). Add diagnostic instrumentation at component boundaries. Log what enters and exits each component. Run once, report where the data flow breaks.

4. **Reproduction Agent** -- For intermittent, timing-dependent, or unclear bugs. Attempt to reproduce consistently. Document exact steps, frequency, and conditions. If not reproducible, gather more data rather than guessing.

5. **Deep Dive Agent(s)** -- For bugs touching multiple subsystems, dispatch 1-2 additional agents each focused on a specific subsystem or code path. Give each a narrow scope: "Investigate how [specific subsystem] handles [specific scenario]." These agents read deeply into a single area rather than scanning broadly.

6. **Dependency/Environment Agent** -- For bugs that might be caused by version mismatches, missing registrations, configuration drift, or framework behavior changes. Check DI registrations, package versions, framework release notes, and environment state.

#### Phase 1 Dispatch Heuristics

| Bug Characteristics | Agents to Dispatch |
|--------------------|--------------------|
| Test failure with clear stack trace | Error + Change + Deep Dive (on the failing subsystem) |
| Vague "something broke" across multiple systems | All six agent types |
| Intermittent / timing-dependent issue | Error + Change + Reproduction + Deep Dive |
| Multi-layer system failure (CI, API chain) | Error + Change + Evidence Gathering + Deep Dive per layer |
| Performance regression | Error + Change + Evidence Gathering + Deep Dive (hot path) |
| "It worked yesterday" | Error + Change + Dependency/Environment |
| Framework/library update broke things | Error + Change + Dependency/Environment + Deep Dive |

#### Context Self-Monitoring (All Phase 1 Agents)

Every investigation subagent prompt MUST include the context self-monitoring block from `./investigator-prompt.md`. Investigators reading large codebases are prime candidates for context exhaustion. If an agent hits 50%+ utilization with significant investigation remaining, it must report partial findings immediately rather than silently degrading.

---

### Synthesis: Consolidate Findings

**Prompt template:** `./synthesis-prompt.md`

After all Phase 1 agents report back, dispatch a single Synthesis agent (requested profile `high`; Claude Code maps it to `model: opus`) that receives all Phase 1 reports verbatim.

**Trust-but-verify:** The synthesis agent does NOT take investigator claims at face value. It cross-references findings between agents, flags contradictions, and identifies claims that lack concrete evidence (file paths, line numbers, stack traces). Speculative findings are downgraded. Concrete artifacts outrank plausible theories.

**The Synthesis agent produces:**
- A 200-400 word root-cause analysis
- Ranked list of likely causes (most to least probable), each with evidence strength rating
- Cross-references between agent findings (where they agree, where they contradict)
- Identified unknowns or gaps in evidence
- Recommendation: is the root cause obvious, or is pattern analysis needed?

**Skip-ahead rule:** If all Phase 1 agents converge on the same root cause with concrete evidence (not just speculation) and the Synthesis agent confirms it as obvious, the orchestrator may skip Phase 2 and proceed directly to Phase 3 (hypothesis formation).

---

### Phase 2: Pattern Analysis (Skippable)

**Prompt template:** `./pattern-analyst-prompt.md`

Dispatch a single Pattern Analysis agent that receives the synthesis report.

**The Pattern Analysis agent:**
1. Finds working examples of similar code/patterns in the same codebase
2. Compares working examples against the broken code exhaustively
3. Lists every difference, however small -- does not assume "that can't matter"
4. Identifies dependencies, config, environment, and assumptions
5. Reports back with specific differences and their likely relevance

**When to skip:** The orchestrator skips Phase 2 when the synthesis report identifies an obvious root cause with high confidence (all investigation agents agree, clear evidence chain).

#### Phase Handoff: Synthesis → 3

Before the orchestrator forms a hypothesis (whether Phase 2 ran or was skipped):

1. Write `handoff-synthesis-to-3.md` with:
   - **Goal:** original bug report, verbatim
   - **Inputs for Phase 3:** synthesis report path, pattern analysis report path (or "skipped" with reason), hypothesis log path (empty if cycle 1), key file paths surfaced during investigation
   - **Decisions Carried Forward:** skip-phase-2 decision (if applicable), investigator-count decision
   - **Active Constraints:** constraints from investigation findings
   - **Shed Receipt:** raw Phase 1 investigation reports (3-6 agent reports) → synthesis report captures consolidated findings
2. Emit shed statement: "Investigation context shed. Synthesis report captures consolidated findings. Raw investigator reports are not carried forward."
3. Update `## Compression State` in pipeline-status.md.
4. Do NOT emit a Compression State Block.

---

### Phase 3: Hypothesis Formation (Orchestrator Only -- No Subagent)

This phase stays local to the orchestrator. No subagent dispatch.

The orchestrator:
1. Reads the synthesis report (and Phase 2 report if it was dispatched)
2. Forms a single, specific, testable hypothesis: "I think X is the root cause because Y"
3. Checks the hypothesis log -- do not repeat a hypothesis that already failed
4. Logs the hypothesis before dispatching Phase 4

**Hypothesis discipline:**
- Be specific, not vague. "The null reference is caused by X not being initialized before Y calls it" -- not "something with initialization."
- One hypothesis at a time. Do not bundle multiple theories.
- If you cannot form a hypothesis from the reports, dispatch more investigation -- do not guess.

#### Hypothesis Log Format

Maintain a running log across cycles:

```
## Cycle 1
- Hypothesis: "[specific hypothesis]"
- Based on: [which reports informed this]
- Result: [filled in after Phase 4 completes]

## Cycle 2
- Hypothesis: "[specific hypothesis]"
- Based on: [which reports informed this]
- Result: [filled in after Phase 4 completes]
```

---

### Phase 3.5: Hypothesis Red-Team

Before dispatching the Phase 4 implementer, invoke `crucible:quality-gate` on the hypothesis with artifact type "hypothesis".

The quality gate challenges:
- Does the hypothesis explain ALL symptoms, or just some?
- Could the root cause be upstream of what the hypothesis targets?
- If this hypothesis is correct, what other symptoms should we expect? Do we see them?
- Has this pattern been tried and failed before? (check hypothesis log and cartographer landmines for `dead_ends`)

**If hypothesis survives:** Proceed to Phase 4.
**If hypothesis is torn apart:** Reform the hypothesis or dispatch additional investigation (back to Phase 1) without wasting a full TDD cycle.

#### Phase Handoff: 3.5 → 4

Before dispatching the implementation agent:

1. Write `handoff-3.5-to-4.md` with:
   - **Goal:** original bug report, verbatim
   - **Inputs for Phase 4:** validated hypothesis (verbatim), target file paths, conventions path, hypothesis log path, implementation details log path (if prior cycles exist)
   - **Decisions Carried Forward:** hypothesis rationale, red-team survival notes
   - **Active Constraints:** constraints on the fix approach
   - **Shed Receipt:** red-team round details, hypothesis formation reasoning → hypothesis log captures outcomes; gate round details are shed
2. Emit shed statement: "Hypothesis formation context shed. Validated hypothesis, target files, and hypothesis log on disk. Red-team round details are not carried forward."
3. Update `## Compression State` in pipeline-status.md.
4. Do NOT emit a Compression State Block.

---

### Phase 4: Implementation (Single Subagent -- TDD)

**RECOMMENDED SUB-SKILL:** Use crucible:checkpoint — create checkpoint with reason "pre-debug-fix-cycle-N" (where N is the hypothesis cycle count) before dispatching the implementation agent. If the fix attempt fails or introduces regressions, this checkpoint allows clean rollback without relying on WIP commit revert mechanics.

**Prompt template:** `./implementer-prompt.md`

Dispatch a single Implementation agent that receives:
- The hypothesis (verbatim)
- Relevant file paths identified during investigation
- Project conventions and test standards
- The hypothesis log (so it knows what hypotheses were already tried)
- The implementation details log from prior cycles (so it knows what code-level approaches were tried, which files were changed, and why they failed — see `implementation-details.md` in the scratch directory)

**The Implementation agent follows strict TDD:**
1. Write a failing test that reproduces the bug per the hypothesis
2. Run the test -- verify it fails for the expected reason
3. Implement the minimal fix addressing the root cause
4. Run the test -- verify it passes
5. Run the broader test suite -- verify no regressions
6. Report back with a structured Implementation Report

**Implementation discipline:**
- ONE change at a time. No "while I'm here" improvements.
- No bundled refactoring.
- Fix the root cause, not the symptom.
- Uses `crucible:test-driven-development` for proper TDD workflow.

---

### Commit Strategy

**After Phase 4 completes**, if the implementer modified any files, create a WIP commit regardless of outcome:

```
git commit -m "fix(wip): [hypothesis summary]"        # on success
git commit -m "fix(wip-failed): [hypothesis summary]"  # on failure or regressions
```

**Immediately after the commit succeeds, record its SHA** (`git rev-parse HEAD`) to
`phase-state.md` as `wip-sha-<cycle>:` (this cycle's key) — this is the durable record
Phase 4.4's gate (1) cites as its comparison operand, so it survives a compaction between
this commit and Phase 4.4.

This gives every outcome path a clean revert target (`git revert <sha>`), gives Phase 5 code review a real diff, and isolates Phase 5 test modifications from the core fix. If the full pipeline succeeds, the final commit message is amended to drop the `(wip)` prefix. If Phase 5 requires changes (test audit updates, gap test additions), those are committed as separate follow-up commits.

On loop-back (failed fix or user-requested revert), `git revert <wip-sha-cycle>` (this cycle's recorded SHA) cleanly undoes all Phase 4 changes including new files.

If Phase 4.5 ran (sibling commits exist): use `git revert <pre-4.5-sha>..HEAD` instead of `git revert <wip-sha-cycle>`. This reverts all sibling commits plus the original WIP commit in one operation. See Phase 4.5 below.

**Phase 4.5 sibling commits:** Each sibling fix uses the prefix `fix(sibling):` with a descriptive message. Example: `fix(sibling): add icon initialization to StashScreen.OnEnable`

---

### Phase 4.4: Scope Check (Tier-2 Scope Judge, Advisory)

**Prototype of `shared/dispatch-convention.md` → Scope Anchoring, tier 2 (#562).**

**EXPERIMENTAL.** This phase is a #562 spike prototype, not a hardened pattern, and is
**advisory-only**: it runs the judge, records the verdict to disk, and surfaces it — it
never reverts, resets, or re-dispatches anything, so there is no destructive step for a
crash to interrupt. Its accuracy numbers come from a different input shape than the one
it actually feeds the judge (see "Unmeasured input shape" below), and its output format
has a known, declared conflict with `shared/return-convention.md` (see
`shared/dispatch-convention.md`'s Scope Anchoring section). Do not copy this phase into
another skill until those gaps are closed.

Phase 4's implementation discipline ("ONE change at a time. No 'while I'm here'
improvements. No bundled refactoring.") is prose the implementer is asked to honor with
nothing checking it. Tier 1 (a pre-declared file allow-list) does not apply here — the
hypothesis names a root cause, not the file set the fix will need. This phase adds a
read-only check: it flags likely scope expansion for a human, or a later review phase,
to weigh — it does not act on what it finds.

**Unmeasured input shape:** the #562 spike's six cases all used issue/finding text
(request-shaped, with an enumerable ask list); none used a Phase 3 hypothesis (a causal
assertion with no enumerable ask list). This adoption feeds the judge a hypothesis, the
one input shape the spike never measured — so the spike's accuracy numbers do not
transfer to it unexamined. Treat the first several runs as calibration: compare the
verdict against what Phase 5's red-team flags. **This is a primed cross-check, not an
independent one** — the Phase 4.5→5 handoff already carries the Phase 4.4 `[DEC-N]`
(flagged paths and confidence) into Phase 5's context (see Phase Handoff: 4.5 → 5 below),
so a systematic bias toward `unrequested-expansion` on a single-item ask list can be
masked if the red-teamer's own read is anchored on having seen the judge's flags first.
Weigh agreement accordingly.

**One rule governs when this phase runs: Phase 4.4 runs immediately before Phase 4.5,
whenever the pipeline is about to reach Phase 4.5.** (The `SKIPPED-NO-WIP-COMMIT` branch
of gate (1) below is a defensive fallback for the case where Commit Strategy's own
guarantee — a WIP commit always gets created — somehow did not hold; it does not describe
a normal path into this phase.)
In practice that is the "Fix works, no regressions" outcome in Loop-back, Cleanup, and
Escalation below — the only outcome that proceeds to Phase 4.5. It does **not** run on
either loop-back path: not on the regression path ("Fix works but introduces regressions"
— the original fix stays, but the pipeline starts a new investigation cycle instead of
proceeding to Phase 4.5; that retained fix is never scope-judged by Phase 4.4 — the judge
only ever sees the current cycle's HEAD commit against the current cycle's hypothesis, so
a later cycle's own success reaches Phase 4.4 judging only that later cycle's own WIP
commit, and the retained fix is reviewed by Phase 5 only), and not on the fix-failed path
(the WIP commit is reverted, so there is nothing left to scope). It runs again on the
Phase 4 of whichever cycle next reaches the success outcome, judging that cycle's own WIP
commit against its own hypothesis.

**Evaluate the two gates below in this order — (1) then (2) — never (2) first:**

**(1) Requires a Phase 4 WIP commit, and it must be `HEAD`.** Phase 4.4 only runs on the
"Fix works, no regressions" outcome, which is exactly the outcome where the Commit
Strategy above always creates a WIP commit (the implementer modified files to fix the
bug). The "test passes immediately, bug already resolved" outcome is a different
Loop-back outcome — it bypasses Phase 4.4 (and Phase 4.5) entirely on its own terms, not
because no WIP commit exists for the case this phase actually handles. Confirm identity,
not just existence: `git rev-parse HEAD` must equal `phase-state.md`'s `wip-sha-<cycle>:`
**for the current cycle only** (see Commit Strategy above, which records it immediately
after the WIP commit succeeds) — `HEAD` alone is not proof, since it silently resolves to
whatever commit came before if the WIP commit was never created, or to a later commit if
one landed on top (e.g. a pre-commit hook's auto-fix commit, or the "preserve reproduction
test" commit pattern used elsewhere in this skill). A `wip-sha-<cycle>:` belonging to any
other cycle is never a valid comparison operand or case-(a) operand for this cycle's gate
(1) — treat it as absent. This gate has two distinct failure modes, and each gets its own
outcome token and remedy — do not conflate them:

- **`SKIPPED-NO-WIP-COMMIT`** — the Commit Strategy step itself observably failed for this
  cycle (e.g. `git commit` exited non-zero, a pre-commit hook blocked it), and no WIP
  commit was created at all. If this happens, write `SKIPPED-NO-WIP-COMMIT` to
  `scope-check-<cycle>.md` (see "Record the outcome" below) and **STOP: the commit failure
  must be resolved** (retry after fixing the hook failure, or escalate) **before Phase
  4.5**, which requires the WIP commit's SHA. Phase 4.4 does not itself resolve it. If the
  commit failure is resolved and the WIP commit is created, re-enter Phase 4.4 from the
  top for this cycle and overwrite `scope-check-<cycle>.md` with the resulting outcome.
- **`SKIPPED-HEAD-MISMATCH`** — the identity check cannot confirm `HEAD` is this cycle's
  WIP commit, for either of two reasons: (a) `phase-state.md` has a `wip-sha-<cycle>:` for
  this cycle but it is not `HEAD` — e.g. a pre-commit hook appended a follow-up commit, or
  the implementer made a second commit on top; or (b) `phase-state.md` has no
  `wip-sha-<cycle>:` for this cycle at all (including when only a prior cycle's key is
  present — that is never a valid operand for this cycle, per gate (1) above) **and the
  Commit Strategy step was not observed to fail** — the identity operand is missing, and
  `HEAD` cannot supply it, since a value read from `HEAD` is not evidence about `HEAD`. Do
  not attempt to recover `wip-sha-<cycle>:` mechanically from `git log -1` or any other
  inspection of `HEAD` in case (b). Neither case is a commit failure (in (a) a commit
  exists; in (b) no commit failure was observed; if one *was* observed, this is
  SKIPPED-NO-WIP-COMMIT, above) — do **not** apply the `SKIPPED-NO-WIP-COMMIT` remedy
  (telling the user to fix a hook failure that did not occur is itself the defect this
  token exists to avoid). If this happens, write `SKIPPED-HEAD-MISMATCH` to
  `scope-check-<cycle>.md`. For (a): either evaluate gate (2) against the recorded
  `wip-sha-<cycle>:` (`git show --numstat --format='' <wip-sha-cycle>` in place of `HEAD`)
  and, if it passes, judge that commit directly (`git show --format='' <wip-sha-cycle>` in
  place of `HEAD`), or escalate. For (b): there is no recorded commit to judge directly —
  escalate, naming the missing `wip-sha-<cycle>:` as the cause, and ask the user to
  confirm which commit is this cycle's WIP commit before Phase 4.4 proceeds. **Record the
  confirmed SHA to phase-state.md as wip-sha-<cycle>: before proceeding** — it is the
  operand Phase 4.5 and the Loop-back revert paths read. Once the remedy resolves — gate
  (2) resolves to a judged verdict or a below-threshold skip, or the escalation settles on
  one — **overwrite `scope-check-<cycle>.md` with the resulting outcome** (`IN-SCOPE`,
  `SCOPE-EXPANSION`, `UNPARSEABLE`, or `SKIPPED-BELOW-THRESHOLD`) so the recovery key
  records the completed check, not the resolved mismatch.

Both are outcomes that do not terminate the phase for the cycle in the ordinary
done-for-this-cycle sense — see the exception in "Record the outcome" and Compaction
Recovery below. Do not evaluate gate (2) against `HEAD` until this gate passes; case (a)'s
remedy above is the only route by which gate (2) may be evaluated against a different
operand, and it is permitted.

**(2) Runs when** the Phase 4 WIP commit (confirmed by gate (1) to be `HEAD`) is
non-trivial: **>1 non-test file changed OR >40 changed lines (insertions + deletions,
from `git show --numstat --format='' HEAD`) in non-test files**. (`--numstat` gives full,
unabbreviated paths and insertions/deletions
as two summable integers, unlike `--stat`, which truncates long paths; count a binary
file as one changed non-test file with 0 lines, and use the post-rename path for
classification when `--numstat` reports a rename.) A test file is a file whose
**basename** matches `test_*`, `*_test.*`, `*.test.*`, `*.spec.*`, `*_spec.*`, `*Test.*`,
`*Tests.*`, or (in this repo) `check_*` (Crucible's structural checkers), or whose path
contains a `tests/`, `test/`, `spec/`, `__tests__/` or `evals/` segment — a purpose-based
rule, not an invocation-based one: `scripts/run_tests.sh` invokes plenty of production
scripts (e.g. `scripts/rcpt_verify.py --selftest`) that are not themselves test files, and
classifying everything it invokes as a test file would make the below-threshold branch
swallow diffs that should be judged. A path following a test convention this list does not
name still counts as a test file; when genuinely ambiguous, count it as a **non-test**
file — the cost of running the judge unnecessarily is bounded; the cost of skipping it is
losing the check entirely. Phase 4's TDD cycle guarantees at least one
test file plus one source file on every fix, so counting test files toward the threshold
would make the "below this, skip" branch unreachable. Below the threshold the judge's
fixed cost outweighs what it can find — skip it, writing `SKIPPED-BELOW-THRESHOLD` to
`scope-check-<cycle>.md` rather than skipping silently, so a resumed run knows why no
judge ran this cycle. This threshold assumes a Sonnet judge; no agent def binds that tier
today (`harness-adapter.md` Mapping 1b — prose model words are descriptive, not binding),
so an orchestrator on a larger model pays proportionally more and the threshold is
correspondingly miscalibrated (see `shared/dispatch-convention.md`'s Cost paragraph).

**Ordering is load-bearing: Phase 4.4 runs AFTER the Phase 4 WIP commit and BEFORE Phase
4.5.** Phase 4.5 fixes analogous siblings *by design*; a judge shown only the original
hypothesis would flag every sibling commit as unrequested expansion. Judge the Phase 4
fix alone.

Dispatch one judge (model tier **sonnet**) using `shared/scope-judge-prompt.md`, disk-
mediated per `shared/dispatch-convention.md`. It receives exactly two substitutions and
nothing else:

- `{{TASK}}` — the hypothesis text as it stood when Phase 4 was dispatched for this cycle
  (i.e. the post-Phase-3.5 reform if the hypothesis was reformed, and this cycle's entry
  if the pipeline has looped back), **verbatim** (not the investigation
  synthesis, not the implementation report, not the implementation-details log)
- `{{DIFF}}` — `git show --format='' HEAD`, the Phase 4 WIP commit's own diff (Phase 4.4
  runs immediately after that commit, so `HEAD` names it directly — no dependence on the
  undefined `<pre-fix-sha>` placeholder used elsewhere in this skill). `--format=''`
  suppresses the commit message, which matters for the same reason the judge gets no
  other repo context: a commit message states the author's own rationalization of the
  change, which is exactly what the judge must not see.

**The verdict is advisory only.** The judge returns `VERDICT: IN-SCOPE | SCOPE-EXPANSION`,
a flagged path list, per-hunk classifications, and a confidence (see
`shared/scope-judge-prompt.md`'s `## Confidence` section — Phase 4.4 gates no
*tree-modifying* action on confidence, at any level. The one place confidence is
consulted is routing: `CONFIDENCE: low` is an unusable return per the canonical trigger
list below, and is recorded as `UNPARSEABLE`). **If the
return is unusable** (unparseable per the canonical trigger list in
`shared/dispatch-convention.md`'s Scope Anchoring tier
2, "Reading the verdict" — do not re-specify that list here): record a
`[DEC-N]` line noting the scope check did not produce a usable verdict, write
`UNPARSEABLE` to `scope-check-<cycle>.md` (see "Record the outcome" below), and proceed to
Phase 4.5. Do not re-dispatch the judge; do not block on it.

**Record the outcome to disk before proceeding, for every branch above** (judge ran,
skipped below threshold, skipped for no WIP commit, skipped for a HEAD mismatch, or
unparseable) — `<scratch-dir>/scope-check-<cycle>.md` (the session scratch directory
`/tmp/crucible-debug-<session-id>/`, same as the other Session State files — do not use
the `<scratch>` token, which names the persistent memory directory instead), holding one
verdict from the closed set `{IN-SCOPE,
SCOPE-EXPANSION, UNPARSEABLE, SKIPPED-BELOW-THRESHOLD, SKIPPED-NO-WIP-COMMIT,
SKIPPED-HEAD-MISMATCH}` plus a
one-line reason, and — when the judge actually ran — the flagged path list and
confidence. Writing the file on every branch, not only when the judge produced a usable
verdict, is what makes it a reliable recovery marker: compaction recovery keys on this
file's presence **for the current cycle** (see Compaction Recovery below) to know Phase
4.4 already ran (or was correctly skipped) for this cycle and must not be re-dispatched —
a file written only on some branches would let a resumed run silently re-run Phase 4.4 on
the branches that didn't write one, defeating "one-shot check by design." There is
nothing destructive to resume into either way, since Phase 4.4 never modifies the tree.
**Presence means done and Phase 4.5 may proceed, except when the recorded outcome is
`SKIPPED-NO-WIP-COMMIT` or `SKIPPED-HEAD-MISMATCH`** — both are transient/blocking by
design (see gate (1) above) and must be resolved (and, for either halt token, overwritten
once it is resolved — see gate (1) above for what each token's remedy overwrites the file
with) rather than treated as a terminal record that clears the cycle to proceed.

- `IN-SCOPE` → record a `[DEC-N]` line and proceed to Phase 4.5.
- `SCOPE-EXPANSION` → record a `[DEC-N]` line naming the flagged paths and the verdict's
  confidence, surface the verdict to the user, and proceed to Phase 4.5. **Phase 4.4
  never reverts, resets, re-dispatches the implementer, or otherwise modifies the tree —
  at any confidence level.** The flagged paths are information for the orchestrator and
  for Phase 5's red-teamer to weigh, not a trigger for action, and Phase 4.4 has no
  interaction with the 3-failure escalation counter: it never counts as, and never
  causes, a Phase 4 fix attempt.

Either way, record the `[DEC-N]` line under Decisions Carried Forward in the Phase
4.5→5 handoff. **Known gap:** the 4.5→5 Phase Handoff Manifest's `Inputs for Phase 5`
allowlist does not yet name the scope-check file itself, so the red-teamer sees the
decision but not the judge's full classification output — do not assume it is visible
unless the orchestrator surfaces it directly. This is a known gap in the #562 prototype,
not yet filed as a follow-up issue.

The judge **never edits anything** and never re-runs. One dispatch, one verdict.

---

### Phase 4.5: "Where Else?" Blast Radius Scan

**RECOMMENDED SUB-SKILL:** Use crucible:checkpoint — create checkpoint with reason "pre-where-else" before dispatching the scan agent. This replaces the need to manually track the pre-Phase-4.5 SHA for revert mechanics — the checkpoint captures the full working directory state.

After Phase 4 succeeds, the WIP commit is created, and Phase 4.4 has recorded an outcome other than `SKIPPED-NO-WIP-COMMIT` or `SKIPPED-HEAD-MISMATCH` (see Phase 4.4's gate (1) above — either of those two outcomes is a halt, not a completion, and must be resolved before Phase 4.5 can run), dispatch the "Where Else?" scan agent to find and fix analogous locations in the codebase that have the same bug pattern. Phase 4.5 does NOT run on loop-back paths (fix failed, regressions found).

**Prompt template:** `./where-else-prompt.md`

**Pre-Phase-4.5 SHA:** Immediately after the Phase 4 WIP commit succeeds, record its SHA. This is the last commit before any sibling work begins. Store it in `where-else-state.md` in the scratch directory.

#### Three Input Signals

The scan agent receives three sources of information:

1. **The fix diff** — `git diff <pre-fix-sha>..HEAD`. The structural pattern of what changed: what was missing, what was added, and what makes a location "analogous."
2. **Cartographer module context** — If cartographer data is available from Phase 0, structurally similar modules (other screens, panels, managers, handlers that follow the same architectural pattern as the fixed code).
3. **Implementer's "Analogous Locations" report** — The Phase 4 implementer's observations about locations they noticed during the fix that may have the same pattern. This is the highest-quality signal — the implementer was already reading the code.

#### Existing Defect Signatures (Fourth Input Signal)

When dispatching the Phase 4.5 scan agent, load matching defect signatures from cartographer as additional context:
- **Selection:** Load at most 3 matching signatures. Treat `Last loaded: never` as oldest. Sort by `Last loaded` descending. Tiebreak by `Date` descending.
- **Module matching:** Same as build/debug load — read each cartographer module file's `Path:` field; match if any target file path starts with the module's `Path:` value. Fall back to directory prefix matching if no cartographer modules exist.
- **What to load:** Signature file (generalized pattern, confirmed siblings, unresolved siblings) plus non-match companion file paths only (without full reason text). The scan agent can read individual companion files on demand if it needs the reasoning.
- **Guidance to scan agent:** Prioritize evaluating candidates NOT listed as confirmed non-matches in existing signatures, but may still evaluate non-match locations if context budget allows. If the new scan confirms the same pattern still exists in a previously-cleared location, note this as a "stale non-match" in the report.

#### Scan Agent Behavior

1. **Analyze the fix pattern.** Read the diff. Extract the structural pattern. Produce a 2-3 sentence generalized pattern description.
2. **Build candidate list.** Combine all three input signals, deduplicate candidates.
3. **Evaluate each candidate.** Read the code at that location. Determine if the same pattern/omission exists. If yes: write a justification explaining WHY this location matches semantically (not just structurally). If no: record as skipped with reason.
4. **Fix confirmed siblings.** For each confirmed sibling:
   - Apply the same fix pattern
   - Run tests
   - If tests pass: commit with `fix(sibling): <description>`
   - If tests fail: revert that single commit, record as "reverted — test failure", continue with remaining candidates
   - After each fix (or revert), update `where-else-state.md` in the scratch directory
5. **Report back.** Structured report:

```
## Where Else? Scan Report

### Generalized Pattern
[2-3 sentence pattern description]

### Candidates Evaluated: N

### Siblings Fixed: N
- [file:path] — [commit SHA] — Justification: [why this matches]
- ...

### Siblings Skipped: N
- [file:path] — Reason: [why this doesn't match]
- ...

### Siblings Reverted: N
- [file:path] — Test failure: [summary of what failed]
- ...
```

#### Compaction Recovery

Phase 4.5 maintains state in `<scratch-dir>/where-else-state.md` to survive session compaction. The file is updated after each sibling fix. On compaction recovery, the agent reads this file to:
- Skip siblings already fixed
- Resume from where it left off with remaining siblings
- Recover the pre-Phase-4.5 SHA (needed for revert mechanics)
- Recover the generalized pattern (avoids re-deriving from the diff)

#### Rules

- Apply the SAME fix pattern — do not invent new approaches for siblings
- One commit per sibling — clean revert granularity
- If tests fail for a sibling, revert and continue — do not debug the sibling
- Do not modify the original fix
- If no candidates are found, report "No analogous locations found" and proceed to Phase 5
- No cap on sibling count — fix all confirmed siblings

#### Defect Signature Persistence

After the Phase 4.5 scan agent reports back, persist the scan results as a cartographer defect signature. This is orchestrator-managed — the recorder only writes files.

**Skip condition:** Do not write a signature when Phase 4.5 reports "No analogous locations found" (0 candidates evaluated). A pattern with no siblings and no non-matches has no evaluation ledger worth persisting.

**Step 1: Dedup check (orchestrator)**
1. Glob `~/.claude/projects/<hash>/memory/cartographer/defect-signatures/*.md` (excluding `*.non-matches.md`)
2. Read each file's `## Generalized Pattern` section only (each is 2-3 sentences; 20 patterns is ~1000-1500 tokens)
3. Compare semantically with the new scan report's generalized pattern
4. **Dedup rubric:** Two patterns are duplicates if they describe the same root cause in the same codebase area. Different areas or different root causes = distinct signatures. When in doubt, treat as distinct — a near-duplicate is recoverable via pruning, a false merge is not.
5. If a match is found, set `update_path` to the existing file path (the recorder will merge into it rather than creating new)
6. If no match, the recorder creates a new file using the content hash slug

**Step 2: Pre-write pruning (orchestrator)**
When count of existing signatures would exceed 20 after writing:
1. Build the pruning-eligible set: exclude signatures where `Last loaded: never` AND `Date` is less than 30 days old
2. Sort by `Last loaded` date ascending; `Last loaded: never` sorts oldest
3. Among ties, prune the oldest by `Date` field
4. Write-before-delete ordering: dispatch the recorder first, then delete pruned files after the recorder succeeds

**Step 3: Dispatch recorder (orchestrator)**
Dispatch a Sonnet cartographer recorder agent

[…] pełny plik w paczce .zip

• SKILL.md 89 KB
• condition-based-waiting.md 3 KB
• defense-in-depth.md 4 KB
• implementer-prompt.md 10 KB
• investigator-prompt.md 15 KB
• pattern-analyst-prompt.md 8 KB
• root-cause-tracing.md 5 KB
• synthesis-prompt.md 5 KB
• test-gap-writer-prompt.md 4 KB
• where-else-prompt.md 12 KB
• evals/evals.json 27 KB