| name | explore |
| description | Understand code without making changes. Read-only exploration of codebase structure, patterns, data flow, and dependencies. Use when asked "how does X work" or to investigate code before planning. |
| category | process |
| triggers | ["how does X work","what would change affect","understand code","investigate","find existing code","code architecture"] |
Explore
Purpose: Understand code without making changes
Mode: Read-only — do NOT modify any files
Usage: /explore [scope flags] <question>
Iron Laws
- READ-ONLY, NO EXCEPTIONS — Never edit, create, or delete any file. This skill is purely investigative.
- ANSWER THE QUESTION ASKED — Do not propose fixes, refactors, or improvements unless explicitly asked. Exploration is not a license to redesign.
- SCOPE BEFORE SEARCHING — Define what you're looking for before reading files. Unbounded exploration fills context and degrades performance.
When to Use
- "How does X work?" — Understand a feature's implementation
- "Why does X behave this way?" — Investigate behavior with history
- "What would be affected if I change X?" — Impact analysis
- "Is there existing code for X?" — Find reusable patterns
- Before
/plan or /implement when the codebase is unfamiliar
When NOT to Use
- You already know the answer from files in context → just answer
- You need to fix a bug →
/debug
- You need to make changes →
/implement
- You need to review code quality →
/review
Scope Flags
| Flag | Description |
|---|
--files=<paths> | Focus exploration on specific files/directories |
--project=<path> | Project root for monorepos |
--depth=<level> | Exploration depth: surface, standard, deep |
Exploration Strategies
| Question Type | Strategy | Approach |
|---|
| "How does X work?" | Trace | Find entry point → follow code path → document the flow |
| "Why does X behave this way?" | Investigate | Read implementation → check tests → review git blame/history |
| "What would change X affect?" | Impact | Find all references → trace dependents → map blast radius |
| "Is there existing code for X?" | Search | Glob for patterns → grep for keywords → check test files for usage |
| "What's the architecture of X?" | Map | Find module boundaries → trace data flow → document interfaces |
Depth Levels
| Level | Scope |
|---|
| Surface | File list + purpose — quick inventory |
| Standard | Code flow + patterns + dependencies — full explanation (default) |
| Deep | Architecture + history + alternatives + edge cases — comprehensive |
Cross-Strategy Techniques for Deep Explorations
Deep explorations should combine multiple strategies rather than relying on a single approach:
- Find all related files — Start with grep/glob to discover every file related to the topic across the entire codebase
- Read key files fully — Read complete implementations, not just function signatures or exports
- Trace imports to map dependencies — Follow import statements to build a dependency graph between modules and packages
- Follow data flow end-to-end — Trace data from entry point (e.g., user input, API request) through transformations to storage or output
- Check tests for behavior documentation — Tests often document expected behavior, edge cases, and integration points that code alone does not reveal
Monorepo Guidance
For monorepo projects (multiple packages/workspaces in one repository):
- Search across ALL packages/workspaces — Do not stop after finding results in one package. A feature often spans multiple packages (e.g., frontend, backend, shared utilities)
- Identify cross-package dependencies via imports — Trace imports that cross package boundaries to understand how packages communicate
- Map which packages own which parts of the feature — Document which layer each package is responsible for (e.g., UI, API, shared types)
- Note shared types/utilities used across packages — Shared packages are dependency hubs; identify what they export and who consumes it
Context Management
- Delegate deep explorations. When exploring a large area (6+ files), delegate to a parallel agent to prevent context exhaustion. The agent reports a summary; the main session stays clean.
- Set a scope budget. Before exploring, estimate how many files you'll need. If >10 files, narrow the question or delegate to parallel agents.
- Stop when answered. Don't keep reading files after finding the answer. Report what you found.
Workflow
Step 1: Parse Scope and Select Strategy
git branch --show-current
Identify: (1) question type from strategy table, (2) depth level, (3) scope from flags or question.
Step 2: Search for Relevant Files
Start narrow, widen only if needed. Use file search and content search to find entry points before reading full files.
Step 3: Read and Analyze
Trace: Find entry point → follow code path → document transformations and decision points.
Investigate: Read implementation → check tests → review git blame → check for TODOs.
Impact: Find all imports/references → trace dependents → map blast radius (direct → transitive).
Search: File patterns → content keywords → check test files → review package.json.
Map: Identify module boundaries → trace data flow → document public interfaces → note coupling.
Step 4: Summarize Findings
Every exploration must include:
## Exploration: [Question]
### Key Files
| File | Purpose |
|------|---------|
| `path/to/file.ts` | [what it does] |
### How It Works
[Explanation with numbered steps referencing file:line]
### Patterns Found
- [Pattern — with example location]
### Considerations
- [Things to be aware of for future changes]
Deep explorations use the following expanded template instead:
## Deep Exploration: [Topic]
### Architecture Overview
[High-level description of the system/feature — how components relate, what patterns are used]
### Component Map
| File | Package/Module | Role |
|------|----------------|------|
| `path/to/file.ts` | [package] | [what it does] |
### Data Flow
[Numbered steps showing how data moves through the system — from entry point to storage/output, referencing file:line]
### Dependencies
**Internal:** [Cross-module/cross-package imports — which modules depend on which]
**External:** [Third-party libraries used and their role]
### Key Design Decisions
- [Decision — why this approach was chosen, with evidence from code/comments/history]
### Security Implications
- [Security-relevant observations — NOT fixes, just observations]
### Areas for Further Exploration
- [Related topics the developer should investigate next]
Step 5: Indicate Confidence
For each finding, note what was verified vs. inferred:
- Verified — Read the code and confirmed
- Inferred — Based on naming/patterns but not traced end-to-end
- Unknown — Couldn't determine; needs manual verification
Acceptance Tests
| ID | Type | Prompt / Condition | Expected |
|---|
| EXP-T1 | Positive | "How does the auth module work?" | Skill triggers |
| EXP-T2 | Positive | "What would change if I modify the API?" | Skill triggers |
| EXP-T3 | Positive | "Is there existing code for email validation?" | Skill triggers |
| EXP-T4 | Negative | "Fix the auth module" | Does NOT trigger (→ /debug) |
| EXP-T5 | Negative | "Add a new API endpoint" | Does NOT trigger (→ /implement) |
| EXP-T6 | Negative | "Plan the new feature" | Does NOT trigger (→ /plan) |
| EXP-T7 | Boundary | "Investigate and then fix the bug" | Triggers for investigation phase only |