dev-explore

What this skill does

**Announce:** "I'm using dev-explore (Phase 2) to map the codebase."

**Iteration topology:** parallel (background explore subagents fan out over subsystems)

### Context Check

Before starting this phase, check remaining context:

| Level | Remaining | Action |
|-------|-----------|--------|
| Normal | >35% | Proceed |
| Warning | 25-35% | Finish the current step, then invoke dev-handoff |
| Critical | ≤25% | Invoke dev-handoff immediately — resume fresh |

At Warning/Critical: Read `${CLAUDE_SKILL_DIR}/../../skills/dev-handoff/SKILL.md` and follow its instructions. A clean handoff beats degraded exploration.

## Contents

- [The Iron Law of Exploration](#the-iron-law-of-exploration)
- [What Explore Does](#what-explore-does)
- [Process](#process)
- [Test Infrastructure Discovery](#test-infrastructure-discovery)
- [Key Files List Format](#key-files-list-format)
- [Output](#output)

# Codebase Exploration

Map relevant code, trace execution paths, and return prioritized files for reading.
**Prerequisite:** `.planning/SPEC.md` must exist with draft requirements.

<EXTREMELY-IMPORTANT>
## The Iron Law of Exploration

**RETURN KEY FILES LIST. This is not negotiable.**

Every exploration, you MUST return:
1. Summary of findings
2. **5-10 key files** with line numbers and purpose
3. Patterns discovered

After agents return, **you MUST read all key files** before proceeding.

**STOP if you're about to move on without reading all key files.**
</EXTREMELY-IMPORTANT>

### Exploration Facts

- Agent summaries and file names compress away the implementation details design decisions hinge on. A design built from summaries alone is built against imagined code — reading the key files costs minutes; the resulting wrong architecture costs days of rework.

### No Pause After Completion

After reading all key files and updating `.planning/SPEC.md` with findings, IMMEDIATELY invoke:

Read `${CLAUDE_SKILL_DIR}/../../skills/dev-clarify/SKILL.md` and follow its instructions.

DO NOT:
- Summarize findings (proceed directly)
- Ask "should I proceed to clarify?"
- Wait for user confirmation
- Write status updates

The workflow phases are SEQUENTIAL. Complete explore → immediately start clarify.

## What Explore Does

| DO | DON'T |
|----|-------|
| Trace execution paths | Ask user questions (that's clarify) |
| Map architecture layers | Design approaches (that's design) |
| Find similar features | Write implementation tasks |
| Identify patterns and conventions | Make architecture decisions |
| Return key files list | Skip reading key files |

**Explore answers: WHERE is the code and HOW does it work**
**Design answers: WHAT approach to take** (separate skill)

## Process

### 1. Launch 3-5 Explore Agents in Parallel + Background

<EXTREMELY-IMPORTANT>
**Launch ALL agents in a SINGLE message with multiple Task calls.**

**Use `run_in_background: true` for ALL explore agents.**

This enables true parallel execution:
- All agents start immediately
- Main conversation continues without blocking
- Results collected asynchronously with TaskOutput

Pattern from oh-my-opencode: Default to background + parallel for exploratory work.
</EXTREMELY-IMPORTANT>

Based on `.planning/SPEC.md`, spawn 3-5 agents with different focuses:

```
# PARALLEL + BACKGROUND: All Task calls in ONE message

Task(
    subagent_type="Explore",
    description="Find similar features",
    run_in_background=true,
    prompt="""
Explore the codebase for [FEATURE AREA].

Focus: Find similar features to [SPEC REQUIREMENT]

Use ast-grep for semantic search:
- sg -p 'function_name($$$)' --lang [language]
- sg -p 'class $NAME { $$$ }' --lang [language]

Tasks:
- Trace execution paths from entry point to data storage
- Find similar implementations to follow
- Identify patterns used
- Return 5-10 key files with line numbers

Context from SPEC.md:
[paste relevant requirements]
""")

Task(
    subagent_type="Explore",
    description="Map architecture layers",
    run_in_background=true,
    prompt="""
Explore the codebase for [FEATURE AREA].

Focus: Map architecture and abstractions for [AREA]

Use ast-grep for semantic search:
- sg -p 'class $NAME($BASE):' --lang [language]
- sg -p 'interface $NAME { $$$ }' --lang [language]

Tasks:
- Identify abstraction layers
- Find cross-cutting concerns (logging, auth, errors)
- Map module dependencies
- Return 5-10 key files with line numbers

Context from SPEC.md:
[paste relevant requirements]
""")

Task(
    subagent_type="Explore",
    description="Find test infrastructure",
    run_in_background=true,
    prompt="""
Explore the codebase for [FEATURE AREA].

Focus: Test infrastructure and patterns

Use ast-grep for test discovery:
- sg -p 'def test_$NAME($$$):' --lang python
- sg -p 'it($DESC, $$$)' --lang javascript
- sg -p '@pytest.fixture' --lang python

Tasks:
- Find test directory and framework
- Identify existing test patterns
- Check for fixtures, mocks, helpers
- Return 5-10 key test files with line numbers

Context from SPEC.md:
[paste relevant requirements]
""")
```

**After launching all agents in parallel:**
- Continue immediately to other work (don't wait)
- Check agent status with `/tasks` command
- Collect results when ready with TaskOutput tool

### 1b. Collect Background Results

Once agents complete, collect their findings:

```
# Check running tasks
/tasks

# Get results from completed agents
TaskOutput(task_id="task-abc123", block=true, timeout=30000)
TaskOutput(task_id="task-def456", block=true, timeout=30000)
TaskOutput(task_id="task-ghi789", block=true, timeout=30000)
```

**Stop Conditions** (from oh-my-opencode):
- Enough context to proceed confidently
- Same info appearing across multiple agents
- 2 search iterations yielded nothing new
- Direct answer found

**DO NOT over-explore. Time is precious.**

### 2. Consolidate Key Files

After all agents return, consolidate their key files lists:
- Remove duplicates
- Prioritize by relevance to requirements
- Create master list of 10-15 files

### 3. Read All Key Files

**CRITICAL: Main chat must read every file on the key files list.**

```
Read(file_path="src/auth/login.ts")
Read(file_path="src/services/session.ts")
...
```

This builds deep understanding before asking clarifying questions.

### 4. Document Findings

Write exploration summary (can be verbal or in `.planning/EXPLORATION.md`):
- Patterns discovered
- Architecture insights
- Dependencies identified
- Questions raised for clarify phase

## Code Search Tools

**Prefer semantic search over text search when exploring code.**

Use ast-grep (`sg`) for precise AST-based pattern matching and ripgrep-all (`rga`) for searching non-code files.

**For detailed patterns and usage, see:** `references/ast-grep-patterns.md`

## Test Infrastructure Discovery (GATE - NOT OPTIONAL)

<EXTREMELY-IMPORTANT>
**CRITICAL: You MUST discover how to run REAL automated tests.**

**NO TEST INFRASTRUCTURE = NO IMPLEMENTATION. This is a gate, not a finding.**

REAL automated tests EXECUTE code and verify RUNTIME behavior.
Grepping source files is NOT testing. Log checking is NOT testing.

See `references/constraints/real-test-enforcement.md` for the canonical REAL vs FAKE test tables.

### The Gate Function

```
DISCOVER test framework → FOUND?
├─ YES → Document in SPEC.md, continue to clarify
└─ NO → STOP. This is a BLOCKER. Cannot proceed without test strategy.
```

**If no way to EXECUTE and VERIFY exists:**
1. **STOP exploration** - do not proceed to clarify
2. **Report to user** - "No test infrastructure found. This blocks TDD."
3. **Propose solution** - "Should I add test infrastructure as Task 0?"
4. **Wait for resolution** - Do not rationalize around this

### Test Infrastructure Facts

- A project without tests gets test infrastructure as Task 0 — absence of a harness is a setup task, not a TDD waiver.
- UI/DOM and GUI features are testable: Playwright, ydotool, and screenshot comparison cover them. "Hard to test" is a tooling gap to solve, not an exemption.