deep-explore

Files (3)

• SKILL.md
• agent-prompt.md · references/
• synthesis.md · references/

SKILL.md (first lines)

# 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

```mermaid
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 |

From sd0xdev/sd0x-harness, MIT.

More from sd0xdev/sd0x-harness