edwinhu/dev-explore

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
• What Explore Does
• Process
• Test Infrastructure Discovery
• Key Files List Format
• 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.
• A SPEC.md that prescribes manual testing is a spec bug — fix SPEC.md or ask the user; assuming the user "won't want tests" decides on their behalf without asking. </EXTREMELY-IMPORTANT>

Project Test Framework

# Find test directories across common locations
ls -d tests/ test/ spec/ __tests__/ 2>/dev/null

# Find test frameworks in build configuration
cat meson.build 2>/dev/null | grep -i test

# Find test frameworks in Node package manifest
cat package.json 2>/dev/null | grep -E "(test|jest|mocha|vitest)"

# Find pytest configuration in Python projects
cat pyproject.toml 2>/dev/null | grep -i pytest

# Find dev dependencies in Rust projects
cat Cargo.toml 2>/dev/null | grep -i "\[dev-dependencies\]"

# Find and list existing test files
find . -name "*test*" -type f | head -20

Available Tools for REAL Testing

| What to Test | Tool | How It's a REAL Test | |--------------|------|----------------------| | Functions | pytest, jest, cargo test | Calls function, checks return value | | CLI | subprocess, execa | Runs binary, checks output | | Web UI | Playwright MCP | Clicks button, verifies DOM | | Desktop UI | ydotool + grim | Simulates input, screenshots result | | API | requests, fetch | Sends request, checks response | | D-Bus apps | dbus-send | Invokes method, checks return |

# Check for desktop automation tools
which ydotool grim dbus-send 2>/dev/null

# List available D-Bus services for desktop app automation
dbus-send --session --print-reply --dest=org.freedesktop.DBus \
  /org/freedesktop/DBus org.freedesktop.DBus.ListNames 2>/dev/null | grep -i appname

Document in Exploration Output

REQUIRED findings for SPEC.md:

• Test framework: meson test / pytest / jest / etc.
• Test command: Exact command to run tests
• How to verify core functionality: What EXECUTES the code
• Available automation: Playwright MCP, ydotool, D-Bus interfaces
• Blocker: If no way to run REAL tests, flag immediately

Code Path Discovery (CRITICAL FOR REAL TESTS)

<EXTREMELY-IMPORTANT> **You MUST discover the actual code paths that need testing.**

A test that exercises the wrong code path is a FAKE test. For example:

• Testing HTTP when the app uses WebSocket
• Testing sync calls when the app uses async
• Testing direct function calls when users click UI

What to Discover

| Question | Why It Matters | |----------|----------------| | What protocol/transport does the feature use? | Tests must use SAME protocol | | How does user input reach the code? | Tests must follow SAME path | | What does the user actually see? | Tests must verify SAME output | | What UI elements are involved? | Tests must interact with SAME elements |

Discovery Checklist

[ ] Protocol identified (HTTP / WebSocket / IPC / D-Bus / etc.)
[ ] Entry point traced (UI click / API call / CLI command / etc.)
[ ] Data flow mapped (user action → ... → visible result)
[ ] UI components identified (panels, buttons, status bars, etc.)

Example Discoveries

Example 1: Web app with GraphQL

- **Protocol:** GraphQL over HTTP POST (NOT REST)
- **Entry point:** User clicks "Save" button
- **Data flow:** click → mutation → server response → UI update
- **UI component:** Toast notification shows "Saved successfully"

A REAL test must use GraphQL mutations, not REST endpoints.

Example 2: CLI tool

- **Protocol:** Command-line invocation with arguments
- **Entry point:** User runs `mytool --format json input.txt`
- **Data flow:** argv → parser → processing → stdout
- **UI component:** Terminal output

A REAL test must invoke the CLI binary, not call internal functions.

Example 3: Electron app with WebSocket

- **Protocol:** WebSocket (NOT HTTP)
- **Entry point:** User highlights text in editor
- **Data flow:** selection → WebSocket message → panel update
- **UI component:** Panel shows status

A REAL test must use WebSocket, not HTTP endpoint.

Fake Test Prevention

If you skip code path discovery, you WILL write fake tests. See references/constraints/real-test-enforcement.md for the full fake test detection tables and the Iron Law of REAL Tests.

Update SPEC.md with code path findings before proceeding. </EXTREMELY-IMPORTANT>

Key Files List Format

Each agent MUST return files in this format:

## Key Files to Read

| Priority | File:Line | Purpose |
|----------|-----------|---------|
| 1 | `src/auth/login.ts:45` | Entry point for auth flow |
| 2 | `src/services/session.ts:12` | Session management |
| 3 | `src/middleware/auth.ts:78` | Auth middleware |
| 4 | `src/types/user.ts:1` | User type definitions |
| 5 | `tests/auth/login.test.ts:1` | Existing test patterns |

Output

Exploration complete when:

• 2-3 explore agents returned findings
• Key files list consolidated (10-15 files)
• All key files read by main chat
• Patterns and architecture documented
• Test infrastructure documented OR blocker raised
• Questions for clarification identified

Required Output Sections

1. Key Files - 10-15 files with line numbers
2. Architecture - Layers, patterns, conventions
3. Test Infrastructure - Framework, tools, patterns
4. Code Paths - Protocol, entry points, data flow, UI components
5. Questions - For clarify phase

Exit Gate

Checkpoint type: human-verify

Run the canonical 5-step gate before chaining to dev-clarify — the two gate checks below are its READ/VERIFY content:

1. IDENTIFY: exploration findings captured (codebase map, test infra, code paths) for the SPEC.md requirements.
2. RUN:      Read SPEC.md and the exploration notes; run the detected test command once to confirm the harness exists.
3. READ:     inspect the Test Infrastructure + Code Path gate checks below.
4. VERIFY:   every required box is checked; protocol/transport and testing skill are identified (no "TBD").
5. CLAIM:    only if 1-4 hold, chain to dev-clarify.

If any sub-check box is unchecked → do NOT proceed; complete discovery first.

Test Infrastructure Gate Check (MANDATORY)

Before proceeding to clarify, verify:

[ ] Test framework identified (pytest/jest/playwright/etc.)
[ ] Test command documented (how to run tests)
[ ] At least one existing test file found OR
[ ] User approved adding test infrastructure as Task 0

If ALL boxes are unchecked → STOP. Ask user how to proceed.

Code Path Gate Check (MANDATORY FOR REAL TESTS)

Before proceeding to clarify, verify code paths documented:

[ ] Protocol/transport identified (WebSocket/HTTP/IPC/etc.)
[ ] User entry point traced (what action triggers the feature)
[ ] Data flow mapped (input → ... → output)
[ ] UI components identified (what user sees)
[ ] Testing skill determined (dev-test-electron/playwright/etc.)

If any box is unchecked → You WILL write fake tests. Complete discovery first.

This is not optional. Fake tests are worse than no tests because they create false confidence.

Phase Complete

Phase summary (append to LEARNINGS.md):

## Phase: Explore

---
phase: explore
status: completed
implements: []          # exploration produces findings, implements no requirement IDs
requires: [SPEC.md]
provides: [codebase-map, testing-infra-discovery, dependency-audit]
affects: []             # read-only phase; no files modified
key-findings:
  - [one-liner per significant discovery]
---

REQUIRED SUB-SKILL: After completing exploration, IMMEDIATELY invoke:

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