Explore

Explore

Purpose: Understand code without making changes Mode: Read-only — do NOT modify any files Usage: /explore [scope flags] <question>

Iron Laws

1. READ-ONLY, NO EXCEPTIONS — Never edit, create, or delete any file. This skill is purely investigative.
2. ANSWER THE QUESTION ASKED — Do not propose fixes, refactors, or improvements unless explicitly asked. Exploration is not a license to redesign.
3. 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

Exploration Strategies

Depth Levels

Cross-Strategy Techniques for Deep Explorations

Deep explorations should combine multiple strategies rather than relying on a single approach:

1. Find all related files — Start with grep/glob to discover every file related to the topic across the entire codebase
2. Read key files fully — Read complete implementations, not just function signatures or exports
3. Trace imports to map dependencies — Follow import statements to build a dependency graph between modules and packages
4. Follow data flow end-to-end — Trace data from entry point (e.g., user input, API request) through transformations to storage or output
5. 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):

1. 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)
2. Identify cross-package dependencies via imports — Trace imports that cross package boundaries to understand how packages communicate
3. Map which packages own which parts of the feature — Document which layer each package is responsible for (e.g., UI, API, shared types)
4. 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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.