Explore

---
name: explore
description: "Read-only codebase exploration: discovery, structural reading, and emission of architecture/pattern/tooling/dependency summaries. Use to understand existing code, map files, trace function flow, locate symbols, or build pre-implementation context. Uses 1/3/5 Explore-agent escalation scaled to scope. Trigger on \"explore\", \"find where X is\", \"how does X work in the code\", \"map the codebase\", \"what files handle Y\", or any architecture/pattern/tooling/dependency context request on a local repo — even without naming /explore."
---

# Explore Command

Read-only codebase orientation. Emit architecture, pattern, tooling, and dependency summaries for a repo-local task. Do NOT write, edit, or commit files.

## When to Apply / NOT

**Apply:**
- Pre-implementation codebase orientation (feature, fix, refactor)
- File and symbol mapping — "where is X defined", "what uses Y"
- Architectural surveys — module boundaries, control flow, coupling
- Dependency tracing — import graphs, transitive deps, config files

**NOT apply:**
- External library docs, SDK APIs, or framework behavior — use a doc-retrieval workflow instead
- User wants a packed repo file as a deliverable artifact
- Implementation, editing, or committing anything

## Process

1. **Scope** — parse the task. Identify files/dirs/concerns. State scope explicitly before dispatching.
2. **Dispatch decision** — for multi-file or uncertain tasks: dispatch Explore agent(s) instead of reading directly. Escalation: 1 agent for single-concern known scope; 3 agents for multiple concerns or unknown scope; 5 agents for cross-module or architectural survey. Auto-skip (direct reads allowed) only for single file under 50 LOC.
3. **Discovery** — token-efficient flags mandatory:
   - File discovery: `fd -e <ext> --max-results 50`
   - Symbol search: `ast-grep run -p 'PATTERN' -l <lang> -C 1` or `git --no-pager grep -n -C 2 'pattern'`
   - Content preview: `bat -P -p -n -r START:END file` or `Read -offset -limit`
   - Directory structure: `eza --tree --level=2`
4. **Synthesis** — emit all Required Output sections. No file writes.
5. **Heavy-codebase escape hatch** — scope > 50 files: use a codebase-packing tool if available as an internal analysis aid (not handed to the user as output); search the packed output for targeted extraction.

## Required Output

Emit all 8 sections. Omit a section only when genuinely not applicable; state why.

### Task Understanding

Brief restatement of the task and identified scope boundaries.

### Architecture Context

```
[Module/Layer Name]
- path/to/file.ts:L10-50 — [Purpose] — [Relevance]
- path/to/interface.ts — [Purpose] — [Relevance]
```

### Pattern Context

```
[Pattern Category]
- path/to/reference.ts — [Pattern description] — [How to apply]
```

### Tooling Context

```
- Build: [command] — [when to run]
- Test: [command] — [scope/coverage]
- Lint: [command] — [config location]
```

### Dependency Map

```
Internal:
- module-a -> module-b (reason)

External:
- library-name@version — [usage context]
```

### Critical Files Summary

Prioritized list of files most relevant to the task:

| Priority | File | Purpose | Action Hint |
|----------|------|---------|-------------|
| P0 | path/to/core.ts | Core logic | Modify |
| P1 | path/to/types.ts | Type definitions | Extend |
| P2 | path/to/utils.ts | Helpers | Reference |

### Constraints & Considerations

- [Constraint 1]: [Impact on implementation]
- [Constraint 2]: [Impact on implementation]

### Recommended Next Steps

1. [First action with specific file reference]
2. [Second action with specific file reference]

## Tool Restrictions

**Allowed (read-only):** `eza`, `fd`, `ast-grep` (find-only), `git grep`, `rg`, `bat`, `tokei`, `Read`, `codebase_search`, and any available codebase-analysis or codebase-packing MCP tooling

**Banned:** `Edit`, `Write`, `mcp__edit__edit_file`, `git commit`, any state-mutating bash command

## Anti-Patterns

- Reading whole files when line ranges suffice — use `bat -r` or `Read -offset -limit`
- Grepping/globbing before dispatching Explore agents on multi-file tasks — dispatch first
- Bypassing token-efficient flags — `bat -P -p -n`, `rg -l`, `fd --max-results 50`
- Re-entering a router or orchestrator skill from within this leaf skill — forbidden (recursion guard)