/deep-explore

name: deep-explore
description: "Multi-wave parallel code exploration orchestrator. Use when: large-scale codebase research, understanding complex cross-domain systems, deep investigation needing multiple perspectives simultaneously. Not for: quick lookup (use code-explore), dual confirmation (use code-investigate), code review (use codex-code-review). Output: unified exploration report with completeness scoring."
allowed-tools: Read, Grep, Glob, Bash, Agent

Deep Explore Skill

Trigger

• Keywords: deep explore, large-scale research, multi-agent explore, codebase survey, parallel investigation, comprehensive research, deep dive multiple areas

When NOT to Use

| Scenario | Alternative | |----------|------------| | Quick single-area lookup | `/code-explore` | | Dual Claude+Codex confirmation | `/code-investigate` | | Git history tracking | `/git-investigate` | | Code review | `/codex-review-fast` |

Workflow Overview

flowchart TD
    A[Phase 0: Intent Analysis] --> B{Files > 25?}
    B -->|No| C[Redirect to /code-explore]
    B -->|Yes| D[Wave 1: Breadth]
    D --> E[Gather + Claim Registry]
    E --> F[Wave 2: Depth]
    F --> G{Completeness Gate}
    G -->|score >= 80 + no critical Qs| H[Report]
    G -->|score < 80 OR critical Qs| I[Wave 3: Cross-cutting]
    I --> H

Phase 0: Intent Analysis

1. Parse user's research question 2. Estimate scope: `Grep` for related keywords → count unique files 3. Routing guard: if estimated files <= 25, redirect to `/code-explore` 4. Plan shards: identify 2-3 non-overlapping exploration areas

Shard Planning Strategy

| Priority | Method | When | |----------|--------|------| | 1 | User-specified areas (`--areas`) | User knows what to split | | 2 | Domain-based clustering | Auto-detect service/provider/hooks/rules boundaries | | 3 | Directory-based fallback | When domain boundaries unclear |

Output: ownership matrix (shard → files).

Wave 1: Breadth (Mandatory)

Fan-out 2-3 Explore agents in parallel. Each agent explores one shard.

Agent({
  description: "Wave 1 Shard A: <area description>",
  subagent_type: "Explore",
  run_in_background: true,
  prompt: <agent-prompt template from references/agent-prompt.md>
});

All agents dispatched in a **single message** (parallel). Wait for all to complete.

Agent Contract (80/20)

| Allocation | Scope | Limit | |-----------|-------|-------| | 80% | Primary assigned shard | Unlimited findings | | 20% | Peripheral vision (security, edge cases, cross-cutting) | Max 2 peripheral findings |

Peripheral findings must be evidence-backed (file:line) and tagged: `cross-cutting | security | reliability | operability`.

Inter-Wave: Gather + Plan

After each wave, the orchestrator:

1. **Collect** all agent results 2. **Build claim registry** (see `references/synthesis.md`) 3. **Rank open questions** by `impact × uncertainty` 4. **Build context packet** for next wave

Context Packet (what to pass forward)

| Pass | Don't Pass | |------|-----------| | Evidence-backed facts (file:line) | Prior wave conclusions as truth | | Open Qs ranked by impact × uncertainty | Narrative interpretations | | Do-not-repeat ledger (explored files, executed queries) | Full raw findings dump | | Contradiction list | Agent opinions without evidence |

Wave 2: Depth (Mandatory)

Focus on top hotspots from Wave 1, ranked by `impact × uncertainty × blast_radius`.

• 2-3 agents, each assigned one hotspot for deep dive
• Context packet from Wave 1 provided (facts + questions, not conclusions)
• Agents verify Wave 1 hypotheses independently

Completeness Gate

After Wave 2 (and Wave 3 if run), compute completeness score.

2-Signal Completeness Score

score = round(100 × (0.7 × (1 - novelty_rate) + 0.3 × is_zero(critical_open)))

Where:
  novelty_rate = unique_new_findings / max(1, total_valid_findings)
  critical_open = count(questions where impact=high AND uncertainty=high)
  is_zero(x) = 1 if x == 0, else 0

Zero findings → `novelty_rate = 0` → `score = 70` (below threshold → continue).

Stop Conditions

| Condition | Action | |-----------|--------| | `score >= 80` AND `critical_open == 0` | Stop, output report | | `score >= 80` AND `critical_open > 0` | Wave 3 (if not yet run) | | Wave 3 done AND `score < 80` | Stop with `Inconclusive` + next actions |

Hard-Fail Overrides (force continue)

• Unanswered critical user question
• High-severity contradiction unresolved
• Evidence missing for high-impact claim

Precedence (`--waves` is hard ceiling)

| User `--waves` | Hard-fail active | Behavior | |----------------|-----------------|----------| | `--waves 2` | No | Stop after Wave 2 | | `--waves 2` | Yes | Stop after Wave 2 with `Inconclusive` | | `--waves 3` | No | Adaptive (stop early if score met) | | `--waves 3` | Yes | Force Wave 3 |

User `--waves` never exceeded. Hard-fail emits `Inconclusive` with explanation.

Wave 3: Cross-cutting (Optional)

Triggered only when:

• Unresolved critical open questions are cross-cutting, OR
• Findings >70% concentrated in 1 subsystem, OR
• High-risk domain flags (auth/security/migration)

If no trigger conditions met, skip Wave 3 even if `score < 80`.

Agents in Wave 3 follow 80/20 contract. If trigger is cross-cutting, one agent may operate as conditional scout with broader mandate.

Agent Dispatch Contract

// Primary: Agent tool with subagent_type=Explore
Agent({
  description: "Wave N Shard X: <description>",
  subagent_type: "Explore",
  run_in_background: true,
  prompt: `<from references/agent-prompt.md>`
});

**Fallback** (if Explore dispatch fails): 1. Retry with `subagent_type: "general-purpose"` 2. If still fails → degrade to single-agent inline exploration 3. Mark coverage gap in report

Claim Registry (Synthesis)

See `references/synthesis.md` for full algorithm.

| Step | Action | |------|--------| | 1. Normalize | `{claim, evidence(file:line), shard, wave, confidence}` | | 2.