Prospector

All subagent dispatches use disk-mediated dispatch. See

shared/dispatch-convention.md

Explores a codebase organically, surfaces architectural friction, and proposes competing redesigns for the user to choose from.

Announce at start: "Running prospector on [codebase/directory name]."

Skill type: Rigid -- follow exactly, no shortcuts.

Purpose: Discover structural improvement opportunities in a codebase. Distinct from audit (which finds bugs in a specific subsystem) -- prospector finds what could be better across the entire codebase. Audit finds what's broken. Prospector finds what could be better.

Model: Opus (orchestrator, organic explorer, competing design agents). Sonnet (genealogists, structured analysis). If the orchestrator session is not running Opus, warn: "Prospector requires Opus-level reasoning for exploration and design phases. Results may be degraded."

Invocation

crucible:prospector                        # default — explore for all friction types
crucible:prospector --focus testability     # narrow: where is testing painful?
crucible:prospector --focus coupling        # narrow: where does change ripple?
crucible:prospector --focus complexity      # narrow: where are things over-engineered?
crucible:prospector --focus depth           # narrow: Ousterhout deep modules lens

Default mode uses the full friction example set. A

--focus

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 phase you're in
2. What just completed -- What the last agent reported
3. What's being dispatched next -- What you're about to do and why
4. Agent status -- During parallel phases (1.5+2, 3, 6): which agents have reported vs. still in flight, finding counts so far

After compaction: Re-read the scratch directory and current state before continuing. See Compaction Recovery below.

Examples of GOOD narration:

"Phase 1 complete. Explorer found 6 friction points (3 High, 2 Medium, 1 Low). Presenting for your review before committing genealogy + root cause dispatches."

"Phase 1.5+2: Genealogy 4/6 complete, Root cause 2/3 complete. 3 Incomplete Migrations, 1 Accretion so far. 4 agents still running."

"Phase 2.5: Convergence found 2 clusters (friction points #2+#5, #3+#7). Presenting draft for confirmation."

"Phase 6: All 3 competing designs complete. Presenting sequentially with comparison including 'Do Nothing' option."

Agent Budget

Total budget: ~24 agents. Worst case with 8 friction points (typically 3-4 High-severity):

• 1 explorer (Opus)
• 8 genealogists (Sonnet) — enhanced with change metrics
• 3-4 root cause agents (Sonnet) — parallel with genealogists, High-severity findings only
• 8 analysis agents (Sonnet) — enhanced, 2000-line hard cap
• 3 design agents (Opus) — enhanced with root cause integration
• 0-1 just-in-time root cause agent (Sonnet) — dispatched only if user selects a Limited candidate

Concurrency: Maximum 5 concurrent agents. Genealogy and root cause agents share this budget during their parallel execution window. The orchestrator dispatches them in round-robin fashion (e.g., 3 genealogy + 2 root cause, then backfill as each completes). Once both tracks complete, analysis agents use the full concurrency budget.

The explorer's output cap of 8 friction points enforces the overall budget. If the user requests exploration of a second candidate after completing the first, the budget resets for the new design cycle (Phases 5-7 only), reusing existing exploration and analysis results.

Scratch Directory

Canonical path:

~/.claude/projects/<project-hash>/memory/prospector/scratch/<run-id>/

The

<run-id>

2026-03-18T14-30-00

Files:

• invocation.md

  — Written at run start. Contains focus mode ("default", "testability", "coupling", "complexity", "depth") and any user-specified directory scope. Compaction recovery reads this first.

• explorer-findings.md

  — Phase 1 organic explorer output

• exploration-approved.md

  — Phase 1 user gate confirmation

• genealogy-<n>.md

  — Phase 1.5 genealogy per friction point

• root-cause-<n>.md

  — Phase 2 root cause output per High-severity friction point

• convergence-draft.md

  — Phase 2.5 proposed groupings with confidence ratings (checkpoint before user confirmation)

• convergence.md

  — Phase 2.5 root cause convergence output after user confirmation (clusters + standalones)

• analysis-<n>.md

  — Phase 3 structured analysis per friction point

• candidates.md

  — Synthesized candidate list (after analysis)

• problem-frame.md

  — Phase 5 problem space framing

• design-<n>.md

  — Phase 6 competing design outputs

• decision.md

  — Phase 7 user's design choice

Stale cleanup: Delete scratch directories older than 24 hours at run start. Prospector runs include unbounded user interaction gaps, so do not delete directories that lack a

decision.md

Session Tracking

• Metrics:

  /tmp/crucible-prospector-metrics-<run-id>.log

  — agent dispatches, completion times
• Decision journal:

  /tmp/crucible-prospector-decisions-<run-id>.log

  — constraint selection rationale, candidate ranking decisions

Preferences Storage

Stored in

~/.claude/projects/<project-hash>/memory/prospector/preferences.md

## Issue Tracker
- Tracker: [github|jira|linear|...]
- Project: [identifier]

First run: ask if user wants to file issues and which tracker. Persist for future runs.

Phase 0.5: Framework Detection

Framework detection is a deterministic orchestrator step that runs BEFORE explorer dispatch. The orchestrator reads dependency manifests directly — this is orchestrator-local work requiring 1-3 file reads, not an agent dispatch.

Phase 0.5 identifies which frameworks are declared (name + version). It does NOT determine which framework patterns are used, unused, or available — that requires code-level investigation and is handled by root cause agents in Phase 2 and analysis agents in Phase 3.

Dependency Manifests Checked

The orchestrator reads whichever of the following exist in the repository root (or known locations):

• package.json

  (Node.js / JavaScript / TypeScript)

• *.csproj

  (C# / .NET)

• Cargo.toml

  (Rust)

• go.mod

  (Go)

• requirements.txt

  ,

  pyproject.toml

  ,

  setup.cfg

  (Python)

• build.gradle

  ,

  pom.xml

  (Java / Kotlin)

• Gemfile

  (Ruby)

• composer.json

  (PHP)

Output

A "Framework context" block (~5-10 lines) containing:

• Language and runtime version
• DI framework name and version (if any)
• Test framework name and version
• UI/web framework name and version
• Any other domain-relevant frameworks (ORM, messaging, etc.) with versions

This block is a hint for downstream agents, not a definitive reference. Pattern-level investigation (which patterns are available and whether they are used or unused) is the responsibility of root cause agents (Phase 2) who have file access to the actual code.

This block is passed to the explorer agent, all root cause agents, all analysis agents, and all design agents.

Phase 1: Explore (Organic Discovery)

Pre-Exploration Context

• RECOMMENDED: Consult

  crucible:cartographer

  (consult mode) — load known module boundaries, conventions, landmines
• RECOMMENDED: Consult

  crucible:forge

  (feed-forward mode) — check past retrospectives for known pain points

Write Invocation State

At run start, write

scratch/<run-id>/invocation.md

• Focus mode: "default" | "testability" | "coupling" | "complexity" | "depth"
• Directory scope: user-specified scope or "Entire codebase"

The Organic Explorer

Dispatch:

Agent tool (subagent_type: Explore, model: Opus)

./explorer-prompt.md

The explorer receives:

• Cartographer data (if available) — module map, conventions, landmines
• Forge signals (if available) — known pain points from past work
• Framework context block (from Phase 0.5) — language, framework names and versions
• The guiding friction examples (full set or focus-specific subset)
• Instruction: "You're a senior developer joining this codebase for the first time. Navigate it naturally. Note where you experience friction."

Guiding friction examples (default mode):

• Understanding one concept requires bouncing between many small files
• A module's interface is nearly as complex as its implementation
• Testing requires elaborate mock setups that mirror internal structure
• Changing one behavior requires edits across many unrelated files
• An abstraction exists but doesn't actually simplify anything
• Pure functions extracted for testability, but the real bugs hide in how they're called
• Tightly-coupled modules create integration risk in the seams between them
• Domain concepts scattered across layers with no clear owner
• Code that's hard to navigate — you keep getting lost or losing context

Focus mode subsets:

testability

coupling

complexity

depth

The explorer outputs a structured list of friction points (capped at top 8, ranked by severity x frequency), each with:

• Location: Files/modules involved
• Friction description: What was confusing or resistant
• Severity: How much this friction would slow down a developer working in this area (High/Medium/Low)
• Frequency estimate: How often a developer would hit this friction (daily, weekly, rarely)

Write-on-complete: The orchestrator writes the explorer's output to

scratch/<run-id>/explorer-findings.md

Explorer Context Budget

The explorer should target 50% of its context window for exploration, reserving the remainder for output generation. For large codebases:

• Start with high-level structure (directory layout, key entry points)
• Drill into areas where friction signals appear
• Report at 50% context usage if significant friction already found
• Do NOT attempt to read every file — organic exploration means following threads, not enumerating
• Maximum ~30 files read at full source depth; use directory listings and interface scanning for breadth

Large Codebase Scoping

For codebases with 20+ top-level modules or directories:

1. Perform a breadth-first pass first — read top-level directory structure, key entry points, existing architectural docs
2. Produce a directory-level heat map indicating which areas look most promising for friction discovery
3. Present the heat map to the user as part of the exploration review gate

If the explorer produces fewer than 3 friction points, report to the user and offer to re-run with: (a) a different starting area, (b) a

--focus

User Gate: Exploration Review

USER GATE: Present the explorer's friction points to the user before committing genealogy and analysis agent dispatches (~16 agents). The user may:

• Prune: Remove friction points that aren't interesting or are already known
• Reorder: Adjust priority ranking
• Adjust severity: Upgrade a finding to High (triggers root cause analysis in Phase 2) or downgrade a High finding (skips root cause analysis)
• Refocus: Ask the explorer to re-run with a different

  --focus

  or in a different area
• Proceed: Approve the friction points for genealogy and analysis

Write

scratch/<run-id>/exploration-approved.md

Phase 1.5: Friction Genealogy

After user approves exploration results, trace the causal origin of each approved friction point using git archaeology. Root cause analysis agents (Phase 2) run in parallel with genealogy — both investigate the same friction points independently.

Genealogist Agents

Dispatch: One agent per approved friction point, parallel (max 5), via

Agent tool (subagent_type: general-purpose, model: Sonnet)

./genealogist-prompt.md

general-purpose

Explore

git log

git blame

git show

Enhanced Output: Change Metrics

In addition to the standard genealogy data (origin classification, key commits, narrative), the genealogist agent's output now includes two structured numeric fields per friction point file:

• Change frequency: Number of commits touching this file in the last 6 months, with rate classification (monthly/weekly/daily)
• Bug-fix commit count: Number of commits with bug-fix indicators (e.g., "fix", "bug", "hotfix" in message) touching this file in the last 6 months

The genealogist already runs

git log

git blame

Git Metrics Aggregation

When a friction point spans multiple files, the genealogist reports per-file metrics for each file. The orchestrator aggregates these into the analysis agent's prompt as follows:

• Headline metric: The hottest file's change frequency and bug-fix commit count are reported as the headline values (e.g., "Change frequency: 14 commits/6mo (weekly) --

  src/services/PaymentProcessor.ts

  ").
• Range summary: A one-line range summary follows: "Range across N files: [lowest]-[highest] commits/6mo, [lowest]-[highest] bug-fix commits."
• Inaction rules key on the hottest file. A single hot file within a friction point's scope makes inaction indefensible — the cost is being paid regardless of whether other files are stable.

Each agent classifies the friction's origin:

Graceful degradation: Genealogy enriches when available but is never required. If git history is too shallow or all results are Indeterminate, downstream phases proceed without genealogy data.

Write-on-complete: The orchestrator writes each genealogist's output to

scratch/<run-id>/genealogy-<n>.md

Phase 2: Root Cause Analysis

Root cause analysis runs in parallel with genealogy. Root cause looks at code structure ("why is this designed this way?"), genealogy traces git history ("how did it get this way?"). Both feed into Phase 2.5 convergence, then Phase 3.

Dispatch Criteria

Root cause agents are dispatched only for High-severity friction points. In a typical run with 8 friction points, 3-4 are High-severity.

• High-severity findings: Full root cause analysis via competing causal hypotheses (agent dispatch).
• Medium/Low-severity findings: No dedicated root cause agent. These findings receive a lightweight root cause signal: if a neighboring High-severity finding's surviving hypothesis covers the same code area or pattern, the orchestrator extracts a one-line root cause note from it. Otherwise, the finding proceeds with "Root cause not analyzed -- severity below threshold."

Agent Spec

Dispatch: One agent per approved High-severity friction point, parallel with genealogy (shares max-5 concurrency budget with genealogists, dispatched in round-robin fashion), via

Agent tool (subagent_type: general-purpose, model: Sonnet)

./root-cause-prompt.md

Each agent receives:

• Friction point description and file locations
• Framework context block (from Phase 0.5, as a hint — agent investigates which patterns are actually used)
• Genealogy data (if available; otherwise runs without it)

Each agent uses the competing causal hypotheses method: generates 2-3 plausible causal hypotheses, defines a falsification criterion for each, tests the criteria against the code, and reports which hypotheses survived.

Root Cause Types

Scope and Termination

• File read budget: Maximum 15 file reads per agent. Maximum 100 lines per targeted read. After reading 10 files, begin synthesizing regardless of investigation state.
• Read strategy: Prefer targeted reads (specific functions/classes, 100-line windows) over full-file reads for large files.
• Codebase boundary: If hypothesis testing leads outside the codebase (into framework internals, language runtime, or third-party library code), stop at the codebase boundary. Record the external dependency as the terminal cause.
• Hypothesis count: 2-3 hypotheses per friction point. Stop when one hypothesis survives falsification, or when all hypotheses have been tested.

Write-on-complete: The orchestrator writes each root cause agent's output to

scratch/<run-id>/root-cause-<n>.md

Phase 2.5: Root Cause Convergence

After all root cause agents and genealogy agents complete, the orchestrator checks whether multiple friction points share the same root cause. When they do, it collapses them into a single "friction cluster" with a unified remediation scope. This prevents producing interfering partial fixes for what is really a single architectural problem.

No agent dispatch — this is orchestrator-local work (Opus reads N root-cause files, groups them, writes one file).

How It Works

1. Read all

   root-cause-<n>.md

   outputs
2. Group by: same root cause type AND surviving hypothesis root cause statements describe the same architectural decision (semantic match, not string equality)
3. Merge threshold: Two friction points merge only when they share the same root cause type AND their root cause statements describe the same underlying architectural decision or missing pattern. Overlapping symptoms or co-located files alone are not sufficient.
4. Split criterion: Before merging, ask: "Would a single design change plausibly fix BOTH friction points?" If no, do not merge even if root cause type and statement match.

Merge Confidence

• High confidence: Same root cause type, same architectural decision, AND a single design change would plausibly fix both. High-confidence merges auto-approve (no user confirmation needed).
• Low confidence: Same root cause type and similar statements, but unclear whether a single design change covers both (e.g., similar root causes in different subsystems). Low-confidence merges require explicit user confirmation.

Medium/Low Finding Overlap Check

Before writing the draft, the orchestrator also checks whether any Medium/Low-severity finding (which did not receive a root cause agent) has symptom descriptions and file locations that overlap with a High-severity finding's root cause scope. Overlaps are flagged as Low-confidence potential merges for user confirmation.

Two-Step Convergence (Compaction-Safe)

1. Draft step: Write proposed groupings to

   scratch/<run-id>/convergence-draft.md

   . Each proposed merge includes its confidence rating (High/Low) and the split criterion assessment. This is a checkpoint — if compaction occurs, the draft survives.
2. Confirmation step: Present the draft to the user. High-confidence merges auto-approve; the user decides on Low-confidence merges (approve or split). The user may also split any auto-approved merge or force-merge missed connections. After confirmation, write the final

   scratch/<run-id>/convergence.md

   .

Downstream Impact

• Analysis agents (Phase 3) receive merged clusters instead of individual findings
• Candidate list (Phase 4) shows clusters as single candidates with combined leverage scores
• Agent budget is reduced in practice — fewer analysis agents and design cycles for merged clusters

Phase 3: Structured Analysis (Enhanced)

The orchestrator reads explorer findings, genealogy results, root cause outputs, and convergence data from disk, then dispatches Structured Analysis Agents via

Task tool (general-purpose, model: Sonnet)

./analysis-prompt.md

Trajectory Context Loading

Before dispatching analysis agents, the orchestrator reads

~/.claude/projects/<project-hash>/memory/prospector/trajectory.jsonl

If matches are found, the orchestrator computes the trajectory status:

• NEW: No prior observations.
• STABLE (N runs): Observed in N prior runs with similar metrics.
• ACCELERATING: Change frequency or modification friction has increased across observations (e.g., monthly→weekly→daily, or Medium→High).
• DECLINING: Metrics have decreased (the friction is getting better, possibly from a prior fix).

The trajectory status and a one-line metric summary ("change freq: monthly→weekly→daily over 3 runs") are included in the analysis agent's input alongside the root cause summary and genealogy data. This costs ~2-3 lines of prompt budget per friction point.

Fingerprint matching degradation: If files are renamed or moved (common after acting on Prospector recommendations), path overlap drops below 50% and the match breaks. This is a known limitation — trajectory degrades gracefully to "NEW" for refactored code. The trajectory file retains the old entries for auditability. A future enhancement could add semantic similarity matching on friction descriptions, but for v2, structural fingerprinting is sufficient.

Track Only resurfacing: If a friction point was previously

track-only

Each analysis agent receives:

• The friction point description and file locations (or cluster of merged friction points with combined scope)
• Genealogy classification and key commits (if available)
• Root cause summary (max 10 lines, mechanically extracted — see below)
• Framework context block (from Phase 0.5)
• Change metrics from genealogy (change frequency and bug-fix commit counts, aggregated per Git Metrics Aggregation rules)
• Relevant source files (subject to 2000-line hard cap — increased from 1500 to accommodate four new output sections)
• The relevant REFERENCE.md section for the friction type being analyzed

Root Cause Summary Extraction

The orchestrator produces the root cause summary by extracting four fields verbatim from the root cause agent's output — no summarization, no paraphrasing:

1. Root cause type (1 line) — copied verbatim from "Type:" field
2. Root cause statement (1 line) — copied verbatim from "Root cause statement:" field
3. Pattern-level fix (1-2 lines) — copied verbatim from "Pattern-level fix:" field
4. Framework-native solution (1-2 lines) — copied verbatim from "Framework-native solution:" field

For convergence clusters, append: "Cluster scope: merged from friction points #X, #Y, #Z — addresses shared root cause as a unit."

For Medium/Low-severity findings without a dedicated root cause agent: use either a one-line note from a neighboring High-severity finding (if applicable) or "Root cause not analyzed -- severity below threshold."

Source Prioritization for Convergence Clusters

When an analysis agent processes a convergence cluster:

1. Full source for the highest-severity constituent finding's files
2. Interface-only excerpts (function signatures, class declarations, public API surfaces) for other constituent findings' files
3. If the cluster still exceeds the 2000-line cap after prioritization, the orchestrator splits the cluster into sub-clusters that each fit. The orchestrator warns the user: "Cluster [X] exceeds context budget and was split into sub-clusters. This partially reduces the convergence benefit." The decision journal logs the split and rationale. Sub-cluster analysis results are re-merged in the Phase 4 candidate presentation.

Each analysis agent outputs:

• Friction type classification — which category from the reference doc
• Applicable philosophy/framework — which architectural philosophy best explains this friction
• Causal origin — from genealogy (if available), factored into effort estimate
• Cluster: Which modules/concepts are involved
• Why they're coupled: Shared types, call patterns, co-ownership
• Dependency category: In-process, local-substitutable, remote-but-owned, or true external
• Estimated improvement impact: High/Medium/Low
• Estimated effort: High/Medium/Low — refined by genealogy
• Friction dimensions — comprehension friction (High/Medium/Low), modification friction (High/Medium/Low), primary dimension
• ROI assessment — leverage score with justification, change frequency, bug correlation
• Framework check — framework patterns available, pattern evidence source, applicability
• Cost of inaction — change frequency (hottest file + range), bug origin rate, blocking planned work, inaction assessment
• Interface surface summary — current public API
• Top caller patterns — 3-5 most common usage patterns
• Structural summary — module boundaries, data flow direction, dependency graph fragment

The last three fields form the design brief consumed by Phase 6 competing design agents.

Write-on-complete: The orchestrator writes each analysis agent's output to

scratch/<run-id>/analysis-<n>.md

The orchestrator reads all analysis results from disk and synthesizes into a ranked candidate list using the formula

leverage_score x modification_friction_score

scratch/<run-id>/candidates.md

USER GATE: Candidate Selection — Present candidates to the user. Do not proceed until user picks one:

### Prospector Candidates

#### Active Candidates (ranked by leverage x modification_friction)

1. **[Score: 9] [Effort: Medium] [Full analysis] Payment processing cluster**
   - Friction: Understanding payment flow requires reading 8 files across 3 directories
   - Root cause: Missing or underused pattern -- no aggregate module, each concern handled individually
   - Origin: Incomplete Migration (commit abc123)
   - Comprehension: High | Modification: High | Leverage: High
   - Framework check: None identified
   - Cost of inaction: Modified weekly, 4 bug-fix commits in 6 months. Not defensible.
   - Trajectory: STABLE (2 runs)

2. **[Score: 6] [Effort: Low] [Limited -- no root cause] Auth middleware duplication**
   - Friction: Auth checks duplicated across 4 route handlers
   - Root cause: Root cause not analyzed -- severity below threshold
   - Origin: Accretion (no single commit)
   - Comprehension: Medium | Modification: High | Leverage: Medium
   - Framework check: Express middleware pattern (framework hint only -- pattern usage not verified)
   - Cost of inaction: Modified weekly, 2 bug-fix commits in 6 months. Not defensible.
   - Trajectory: NEW

---

#### Track Only (inaction defensible -- low modification friction or low leverage)

3. **[Score: 3] [Effort: Low] [Limited -- no root cause] GameBootstrap god-class**
   - Friction: Hard to read (2,393 lines) but modification pattern is clear (~5 lines per change)
   - Root cause: Missing or underused pattern -- no self-registration, but modification cost is low
   - Comprehension: High | Modification: Low | Leverage: Low
   - Framework check: VContainer IInitializable would solve this (framework hint only -- pattern usage not verified)
   - Cost of inaction: Modified monthly, 0 bug-fix commits. Defensible -- rarely modified, clear patterns.
   - Trajectory: STABLE (4 runs)

Data Quality Indicators

Each candidate is tagged with:

• [Full analysis]

  — High-severity finding that received a dedicated root cause agent. Framework check is based on code-level investigation.

• [Limited -- no root cause]

  — Medium/Low-severity finding that did not receive a root cause agent. Framework check is based on Phase 0.5 hint only.

Constraint-Driven Root Cause Warning

When a candidate's root cause type is "Other / Constraint-driven," the candidate presentation includes a warning: "Root cause is an external constraint -- designs address symptoms, not the underlying cause." The orchestrator does NOT auto-demote these.

Just-in-Time Root Cause for Limited Candidates

If the user selects a

[Limited -- no root cause]

After the JIT root cause agent completes, the orchestrator compares its output against existing root-cause files and convergence clusters. If the JIT root cause matches an existing cluster's shared root cause, the orchestrator warns the user: "This finding appears to share a root cause with [cluster X]. Continue separately, merge into cluster X, or skip?" The user decides before design agents are dispatched.

User selects by number. Orchestrator proceeds to problem framing for that candidate.

Phase 5: Frame the Problem Space

Before spawning competing design agents, write a user-facing explanation:

• The constraints any new interface would need to satisfy
• The dependencies it would need to rely on
• The dependency category and what that means for testing strategy
• A rough illustrative code sketch — NOT a proposal, just grounding for the constraints

Write to

scratch/<run-id>/problem-frame.md

USER GATE: Present the problem framing to the user and wait for confirmation before dispatching design agents. The framing directly determines the constraint selection in Phase 6 — dispatching 3 Opus agents with wrong inputs is expensive. User may adjust constraints, dependencies, or dependency category before proceeding.

Phase 6: Competing Designs (Contextual Constraints)

Constraint Selection

The orchestrator selects 3 design constraints from a deterministic mapping in REFERENCE.md. The mapping is keyed by friction type classification (from Phase 3 analysis). Each friction type has exactly 3 associated constraints — the orchestrator looks up the friction type and uses its constraints. This is a routing decision, not a creative one.

Friction-type-to-constraint mapping (canonical, in REFERENCE.md):

If a friction point doesn't match any defined type, the orchestrator falls back to a generic set: "Minimize interface," "Maximize flexibility," "Optimize for most common caller." The decision journal must log which constraint set was selected and why.

Dynamic Constraint Overrides

The constraint table above is the default. The following overrides apply when root cause analysis provides additional signal:

Root-Cause-Aware Framework Override

When the root cause type is "Missing or underused pattern" AND a framework-native solution was identified in Phase 3:

• Slot 1: "Adopt framework-native pattern: [specific pattern from Phase 3 framework check]"
• Slot 2: From friction-type mapping (custom approach)
• Slot 3: From friction-type mapping (custom approach)

Root-Cause-Type-Derived Override

When the root cause type suggests a specific design direction:

• "Wrong abstraction": One slot becomes "Replace abstraction with correct domain model: [domain concept from surviving hypothesis]"
• "Absent boundary": One slot becomes "Introduce boundary at [identified seam from surviving hypothesis]"

These overrides apply to Slot 3. If a framework-native override already occupies Slot 1, the root-cause-type override replaces Slot 3 — both can coexist. Root cause types "Misaligned ownership" and "Other / Constraint-driven" do not trigger this override.

Standard Framework-Native Slot

When Phase 3 identified a framework-native solution BUT root cause type is NOT "Missing or underused pattern":

• Slot 1: From friction-type mapping
• Slot 2: From friction-type mapping
• Slot 3: "Framework-native solution" — design agent's constraint is to use only existing framework/language features

When no framework-native solution was identified: all 3 slots from friction-type mapping (unchanged).

The decision journal must log which constraint set was selected and which overrides applied.

Design Agent Dispatch

Spawn 3 agents in parallel via

Agent tool (subagent_type: general-purpose, model: Opus)

./design-competitor-prompt.md

Each agent receives (subject to 2000-line hard cap):

• Technical brief from the analysis output (interface surface, caller patterns, structural summary)
• Genealogy context: causal origin classification and key commits (if available)
• Full competing hypotheses output from Phase 2 root cause analysis (all hypotheses with verdicts, surviving hypothesis, root cause classification, framework investigation, remediation direction)
• Framework context block (from Phase 0.5)
• Its assigned design constraint
• The applicable architectural philosophy and why it applies

Write-on-complete: The orchestrator writes each design agent's output to

scratch/<run-id>/design-<n>.md

Each agent outputs:

1. Interface signature — types, methods, params
2. Usage example — how callers use the new interface
3. What complexity it hides internally
4. Dependency strategy — how deps are handled (mapped to the dependency category)
5. Testing strategy — what tests look like at the new boundary
6. Trade-offs — what you gain and what you give up
7. Root cause coverage — Does this design address the root cause? Yes/Partially/No, with explanation

Design agents are instructed: "Your proposal must address the surviving root cause hypothesis, not just the symptom identified by the explorer. Review the falsified hypotheses to understand what the root cause is NOT."

Presentation

Present designs sequentially, then compare in prose. Give an opinionated recommendation: which design is strongest and why. If elements from different designs combine well, propose a hybrid. The user wants a strong read, not just a menu.

"Do Nothing" Comparison

After all designs are presented, include a mandatory comparison table with a "Do Nothing" column:

| Dimension | Design A | Design B | Design C | Do Nothing |
|---|---|---|---|---|
| Root cause addressed? | Yes | Partially | Yes | No |
| Effort | Medium | Low | High | None |
| Leverage | High | Medium | High | N/A |
| Risk | Medium | Low | High | None |
| Lines changed (est.) | ~200 | ~80 | ~500 | 0 |
| Cost of inaction | -- | -- | -- | [from analysis] |

The orchestrator still gives an opinionated recommendation, but "do nothing" is explicitly on the table.

Phase 7: User Picks a Design

User selects a design, accepts the recommendation, or requests a hybrid. Orchestrator records the decision to

scratch/<run-id>/decision.md

Phase 8: Output

Design Doc

Write a design doc to

docs/plans/YYYY-MM-DD-prospector-<topic>-design.md

<topic>

-2

-3

• Friction analysis — what was found and why it matters
• Friction genealogy — causal origin, key commits, how the friction developed (if genealogy data available)
• Chosen design — interface, usage, hidden complexity, dependency strategy, testing strategy
• Competing designs summary — what was considered and why the winner was chosen
• Implementation recommendations — durable architectural guidance not coupled to current file paths

Trajectory Snapshot

At the end of every run — regardless of whether the user proceeds to build, files an issue, or keeps the design doc — the orchestrator writes a friction trajectory snapshot to persistent storage.

File:

~/.claude/projects/<project-hash>/memory/prospector/trajectory.jsonl

Each approved friction point (from the exploration review gate) becomes one JSONL line:

{"timestamp": "2026-03-23T14:30:00", "fingerprint": {"files": ["src/GameBootstrap.cs", "src/Services/"], "friction_type": "Coupling / shotgun surgery", "root_cause_type": "Missing or underused pattern"}, "metrics": {"change_freq": "weekly", "bug_fix_count": 4, "modification_friction": "High", "leverage": "High"}, "disposition": "selected-for-design", "run_id": "2026-03-23T14-30-00"}

Fields:

• fingerprint: Primary file paths (sorted, normalized) + friction type + root cause type. Used for cross-run matching.
• metrics: Change frequency, bug-fix count, modification friction, leverage — from Phase 3 analysis.
• disposition:

  selected-for-design

  |

  track-only

  |

  pruned-by-user

  — what happened to this finding.
• run_id: Links back to the scratch directory for full details.

Fingerprint matching across runs uses: same friction type AND overlapping file paths (>50% overlap). Root cause type is included for context but not required to match (root cause classification may evolve as the codebase changes).

The trajectory file is append-only. Each run appends N lines (one per approved finding). Reading the file is a single file read at the start of Phase 3.

User Choice

After saving the design doc, ask the user:

"Design doc saved. Would you like to: (a) File this as an issue in your tracker (b) Kick off build in refactor mode to implement it (c) Just keep the design doc for now (d) Explore another candidate from the list"

Option (a): File as an issue using whatever tools are available in the environment. Tracker-agnostic — no hardcoded assumption about GitHub, Jira, Linear, or anything else. If tracker preference isn't stored, ask the user. Persist preference.

Option (b): Invoke

crucible:build

Option (c): Done. Design doc is committed and available for future reference.

Option (d): Return to Phase 4 (candidate selection). Reuse existing exploration and analysis results from disk — no re-exploration needed. Budget resets for Phases 5-7 only (3 Opus design agents). New candidate's design doc saved alongside the first.

End-of-Run Cleanup

Delete

scratch/<run-id>/

Cartographer Recording

After Phase 8, dispatch

crucible:cartographer

Dependency Categories

Classification system for the target code's dependencies:

1. In-Process

Pure computation, in-memory state, no I/O. Always improvable — merge modules and test directly.

2. Local-Substitutable

Dependencies with local test stand-ins (e.g., SQLite for Postgres, in-memory filesystem). Improvable if the stand-in exists.

3. Remote but Owned (Ports & Adapters)

Your own services across a network boundary. Define a port at the module boundary; inject transport. Tests use an in-memory adapter.

4. True External (Mock)

Third-party services you don't control (Stripe, Twilio, etc.). Mock at the boundary via injected port.

Compaction Recovery

After context compaction:

1. Read

   scratch/<run-id>/invocation.md

   first — recover focus mode and directory scope before any other state
2. Read remaining

   scratch/<run-id>/

   files to determine current state

3. explorer-findings.md

   exists → Phase 1 exploration complete

4. exploration-approved.md

   exists → user gate passed. If missing but

   explorer-findings.md

   exists, re-present friction points for confirmation.
5. Check completion state of BOTH parallel tracks before advancing: a. Read

   explorer-findings.md

   to determine expected count N (total) and H (High-severity count) b. Count existing

   genealogy-<n>.md

   files. If fewer than N, dispatch remaining genealogy agents c. Count existing

   root-cause-<n>.md

   files. If fewer than H, dispatch remaining root cause agents (High-severity findings only) d. Wait for ALL dispatched agents from BOTH tracks to complete before proceeding

6. convergence-draft.md

   exists but

   convergence.md

   does not → re-read draft and present to user for confirmation (skip grouping analysis)

7. convergence.md

   exists → Phase 2.5 complete. If neither convergence file exists but all root-cause and genealogy files are complete, re-run convergence from scratch (orchestrator-local, cheap).

8. candidates.md

   exists → Phase 3 complete, re-present to user if no selection recorded

9. problem-frame.md

   exists → Phase 5 complete

10. design-*.md

    files → count competing designs, dispatch remaining if incomplete

11. decision.md

    exists → Phase 7 complete, proceed to output
12. Output status update before continuing

Guardrails

The explorer must NOT:

• Modify any code (prospector is read-only until output phase)
• Follow rigid heuristics — explore organically
• Report friction without specific file/location evidence

Analysis agents must NOT:

• Exceed 2000 lines of total prompt content
• Classify friction without evidence from the source code provided in their prompt (analysis agents are Task tool dispatches — they receive pasted source, not file access)
• Speculate about problems they can't point to evidence for

Design agents must NOT:

• Produce identical designs with different names — designs must be radically different
• Ignore the assigned constraint
• Propose changes without showing the caller-side impact

The orchestrator must NOT:

• Proceed past any user gate without confirmation
• Select design constraints before the analysis phase classifies the friction
• File issues without user approval
• Skip narration between dispatches

Red Flags

• Explorer producing a checklist instead of organic friction observations
• All three competing designs converging on the same solution (constraints weren't different enough)
• Design agents ignoring dependency category in their testing strategy
• Orchestrator hardcoding tracker-specific commands
• Skipping the problem-framing step (Phase 5)
• Root cause agent restating the symptom instead of identifying an architectural cause
• Convergence merging friction points that share a root cause type but describe different architectural decisions
• All three competing designs ignoring the surviving root cause hypothesis
• Inaction assessment missing when change metrics show weekly+ modification frequency

Integration

• Consults:

  crucible:cartographer

  (consult mode),

  crucible:forge

  (feed-forward mode)
• Records to:

  crucible:cartographer

  (record mode) — user-approved friction point locations and classifications only
• Hands off to:

  crucible:build

  (refactor mode) — design doc becomes context for build's design phase
• Complementary to:

  crucible:audit

  — audit finds bugs, prospector finds structural improvements. Run prospector before audit when both are planned.
• Called by: Standalone only (user invokes directly)
• Does NOT use:

  crucible:quality-gate

  (prospector is advisory, not a fix loop),

  crucible:red-team

• Does not dispatch /recon -- organic exploration serves a different purpose than structured investigation. Does not dispatch /assay -- competing design evaluation is more specialized than assay for this use case. See #147 for rationale.

Subagent Dispatch Summary

./explorer-prompt.md

./genealogist-prompt.md

./root-cause-prompt.md

./analysis-prompt.md

./design-competitor-prompt.md

Prompt Templates

• ./explorer-prompt.md

  — Phase 1 organic exploration dispatch

• ./genealogist-prompt.md

  — Phase 1.5 git archaeology, causal origin classification, and change metrics

• ./root-cause-prompt.md

  — Phase 2 competing causal hypotheses agent dispatch

• ./analysis-prompt.md

  — Phase 3 structured friction analysis dispatch (enhanced with ROI, friction dimensions, framework check, cost of inaction)

• ./design-competitor-prompt.md

  — Phase 6 competing design agent dispatch (enhanced with root cause integration)

• ./REFERENCE.md

  — Friction taxonomy, philosophy mappings, constraint menu, dependency categories, origin type definitions, root cause type taxonomy, ROI scoring, framework check guidance, cost-of-inaction criteria