Explore

Systematically research codebases to build accurate mental models before acting.

When to Explore

• Starting work on a new/unfamiliar codebase
• Investigating a bug or error
• Planning a new feature
• Reviewing code you didn't write
• Context feels incomplete or ambiguous
• About to make assumptions

Exploration Principles

1. Outside-In (Macro → Micro)

Start broad, then drill down:

Project Structure → Module Organization → File Purpose → Implementation Details

2. Follow the Data

Trace how information flows:

Input → Validation → Transformation → Storage → Output

3. Question Everything

Before assuming:

• "What is this file's responsibility?"
• "Who calls this function?"
• "What would break if I changed this?"
• "Is this used in production or just tests?"

Modern CLI Tools

Use modern alternatives for faster, more ergonomic exploration. Install them if available:

Tool Comparison

Installation

# macOS (Homebrew)
brew install ripgrep fd bat delta

# Ubuntu/Debian
sudo apt install ripgrep fd-find bat
# Note: Ubuntu binary is 'fdfind', symlink: sudo ln -sf $(which fdfind) /usr/local/bin/fd

# Arch Linux
sudo pacman -S ripgrep fd bat delta

# Check if installed
command -v rg fd bat delta 2>/dev/null || echo 'Some tools not installed'

Quick Usage

# ripgrep - faster grep
grep -r 'TODO' src/           # Traditional
rg 'TODO' src/                # Modern (faster, cleaner output)
rg -t ts 'interface'          # Search only TypeScript files

# fd - faster find
find . -name '*.ts'           # Traditional
fd '\.ts$'                    # Modern (regex support)
fd -e ts                      # By extension

# bat - better cat
cat README.md                 # Traditional
bat README.md                 # Modern (syntax highlighting)
bat -l yaml config.yml        # Force language

# delta - better diffs
git diff                      # Traditional
git diff | delta              # Modern (syntax highlighting)
delta --side-by-side          # Side-by-side view

Phase 1: Project Reconnaissance (5 min)

Read Entry Points

# Start here — every project has these
cat README.md                    # Project overview, setup, conventions
cat package.json 2>/dev/null     # Dependencies, scripts, metadata
cat AGENTS.md 2>/dev/null        # Project-specific agent instructions

# Or with bat (if available)
bat README.md                     # Syntax-highlighted view with line numbers
bat package.json 2>/dev/null     # Better readability for JSON

Map Structure

# Understand directory layout
ls -la                           # Root contents
find . -maxdepth 2 -type d       # Top-level directories
tree -L 2 2>/dev/null || find . -maxdepth 2 -type d | head -20

# Or with fd (if available)
fd -d 2 -t d                    # Top-level directories (simpler syntax)
fd -d 3 -e ts -e go             # Find source files up to 3 levels deep

Identify Technology Stack

# Detect frameworks and patterns
grep -l "react\|vue\|angular" package.json 2>/dev/null && echo "Frontend framework detected"
grep -l "express\|fastify\|hono" package.json 2>/dev/null && echo "Backend framework detected"
grep -l "prisma\|drizzle\|typeorm" package.json 2>/dev/null && echo "ORM detected"

# Or with ripgrep (if available)
rg -l 'react|vue|angular' package.json 2>/dev/null && echo "Frontend framework detected"
rg -l 'prisma|drizzle' package.json 2>/dev/null && echo "ORM detected"

Output: Create SESSION.md Entry

## Exploration: Project Overview

**Stack:** React + Node + Prisma
**Structure:** src/{components,pages,api}/
**Conventions:**

- Feature-based folders
- Tests co-located (\*.test.ts)
- API routes in src/api/

Phase 2: Architecture Mapping (10 min)

Find the Core Modules

# Identify high-traffic files
git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -20

# Or find most imported modules
grep -r "^import.*from" --include="*.ts" --include="*.js" | cut -d'"' -f2 | sort | uniq -c | sort -rg | head -20

# With ripgrep (faster)
rg -o 'from ["\'][^"\']+["\']' -t ts | sed 's/from //g' | sort | uniq -c | sort -rg | head -20

Trace Data Flow

Pick a key entity (e.g., "User", "Order") and trace it:

# Find where it's defined
grep -r "interface User\|type User\|class User" --include="*.ts" | head -5

# With ripgrep
rg 'interface User|type User|class User' -t ts | head -5

# Find where it's used
grep -r "User" --include="*.ts" | grep -v node_modules | wc -l

# With ripgrep (auto-ignores node_modules)
rg -c 'User' -t ts | head -10

# Find API endpoints that handle it
grep -r "user\|User" src/api/ --include="*.ts" | head -10

# With ripgrep
cd src/api && rg -i 'user' -t ts | head -10

Map Dependencies

# What does this module depend on?
cat src/auth/login.ts | grep "^import"

# Or with bat + rg
bat src/auth/login.ts | rg '^import'

# What depends on this module?
grep -r "from.*auth/login" --include="*.ts" | head -10

# With ripgrep
rg 'from.*auth/login' -t ts | head -10

Document in STRUCTURE.md

# Architecture

## Entry Points

- `src/main.ts` — Application bootstrap
- `src/api/index.ts` — API route registration

## Core Modules

- `auth/` — Authentication, session management
- `models/` — Database schemas (Prisma)
- `services/` — Business logic

## Data Flow

Request → Middleware → Handler → Service → Model → DB

## Key Files
| File | Purpose |
|------|---------|
| `src/auth/jwt.ts` | Token generation/validation |
| `src/models/user.ts` | User entity definition |

Phase 3: Deep Dive (Targeted)

Locate Relevant Code

Given a task (e.g., "fix login bug"):

# Search for keywords
grep -r "login\|signin\|authenticate" --include="*.ts" | grep -v test | head -10

# With ripgrep (cleaner, faster)
rg -g '!*.test.ts' 'login|signin|authenticate' -t ts | head -10

# Find related tests (show usage patterns)
grep -r "login" --include="*.test.ts" | head -5

# With ripgrep
fd -e test.ts && rg 'login' -g '*.test.ts' | head -5

# Check recent changes
git log --oneline --all --grep="login" | head -5

Read Call Stacks

Start from entry point, trace down:

# API route
cat src/api/auth.ts
# → Calls authService.login()

# Implementation
cat src/services/auth.ts
# → Calls userRepository.findByEmail()

# Data layer
cat src/repositories/user.ts
# → Calls prisma.user.findUnique()

# With bat (better readability)
bat src/api/auth.ts src/services/auth.ts src/repositories/user.ts

Understand Edge Cases

Look for:

• Error handling (throw, catch, if (error))
• Validation logic (zod, joi, manual checks)
• Permissions/authorization (canAccess, requireAuth)
• Environment-specific code (process.env, import.meta.env)

Phase 4: Context Clarification

When You're Stuck

If something doesn't make sense:

1. Find examples — How is this used elsewhere?

   grep -r "similarFunctionName" --include="*.ts" -A 3 | head -20

1. Check tests — Tests show intended behavior

   cat src/auth/login.test.ts | grep -A 10 "should"

1. Look for docs — Comments, JSDoc, READMEs

   grep -B 5 "function login" src/auth/login.ts

1. Trace git history — Why was this added?

   git log -p --all -S "suspiciousCode" -- src/auth/login.ts | head -50

Validate Assumptions

Before proceeding, verify:

# "This function is only called from X"
grep -r "functionName" --include="*.ts" | grep -v "def\|export" | wc -l

# With ripgrep
rg -c 'functionName' -t ts  # Shows count per file

# "This is always a string"
grep -r "variableName:" --include="*.ts" | head -5

# With ripgrep
rg 'variableName:' -t ts | head -5

# "This mutation updates the database"
grep -A 10 "mutationName" src/services/*.ts | grep -E "prisma|save|update"

# With ripgrep
rg -A 10 'mutationName' -t ts | rg 'prisma|save|update'

Exploration Outputs

Required: CONTEXT.md

After exploration, create/update:

# Context: <Feature/Area>

## What I Learned

- X is handled by Y module
- Z is the source of truth for W data
- Authentication uses JWT with 24h expiry

## Open Questions

- [ ] Why is X implemented as Y instead of Z?
- [ ] How does the caching layer work?

## Relevant Files

| File                     | Why It Matters         |
| ------------------------ | ---------------------- |
| `src/auth/jwt.ts`        | Token generation logic |
| `src/middleware/auth.ts` | Route protection       |

## Risks/Watchouts

- Changing X requires updating Y and Z
- No tests for edge case A

Optional: Update Project Files

Based on your exploration:

• Add to DECISIONS.md if you discovered why something is the way it is
• Update TODO.md with tasks that emerged
• Create SPEC.md for areas you now understand

Common Exploration Patterns

Pattern: Bug Investigation

# 1. Find error location
grep -r "errorMessage" --include="*.ts"

# 2. Trace backward
cat src/fileWithError.ts
# → Find caller
# → Find caller's caller

# 3. Check recent changes
git log --oneline --all -- src/fileWithError.ts | head -5

# 4. Reproduce
# Look for test that exercises this path

Pattern: Feature Addition

# 1. Find similar features
grep -r "similarFeature" --include="*.ts" -l

# 2. Study the pattern
cat src/features/similar/index.ts

# 3. Identify all touchpoints
grep -r "similarFeature" --include="*.ts" | grep -v "def\|export" | cut -d: -f1 | sort -u

# 4. Note conventions
# - How are routes registered?
# - How are tests structured?
# - What validation is used?

Pattern: Code Review Prep

# 1. Understand the change
git diff main...feature-branch --stat

# 2. Read modified files in dependency order
# (models → services → handlers → tests)

# 3. Check for missing pieces
# - Are there tests?
# - Is there error handling?
# - Are types defined?

# 4. Verify assumptions
# - Does this break existing code?
# - Are there migration concerns?

# 5. Review with delta (if available)
git diff main...feature-branch | delta          # Syntax-highlighted diff
delta --side-by-side main...feature-branch     # Side-by-side view

Anti-Patterns (DON'Ts)

• Don't skim — Read code line by line when it matters
• Don't guess types — Check the actual definitions
• Don't assume single usage — Always grep for callers
• Don't ignore tests — They document expected behavior
• Don't skip error paths — Understand failure modes
• Don't make changes during exploration — Research first, act second

Quick Reference: Grep Patterns

# Find function definitions
grep -r "function name\|const name\|async function name" --include="*.ts"

# Find all imports of a module
grep -r "from.*module-name" --include="*.ts"

# Find where a variable is used (excluding definition)
grep -r "varName" --include="*.ts" | grep -v "const\|let\|var\|import"

# Find exported items
grep -r "^export" --include="*.ts" src/some-module/

# Find TODO/FIXME comments
grep -r "TODO\|FIXME\|XXX\|HACK" --include="*.ts" src/

With ripgrep (faster alternatives)

# Find function definitions
rg '(function|const|async function) name' -t ts

# Find all imports of a module
rg 'from.*module-name' -t ts

# Find exported items
rg '^export' -t ts src/some-module/

# Find TODO/FIXME comments
rg 'TODO|FIXME|XXX|HACK' -t ts src/