/dev-scout - Codebase Explorer

Skill Awareness: See skills/_registry.md for all available skills.

• Before: Use /debrief if requirements unclear
• After: Use /dev-specs for implementation plans
• Related: /diagram for architecture visualization

Explore and document codebases. Works at project level or per feature.

When to Use

• Understand existing codebase before adding features
• Document current state for team
• Analyze specific area before implementation
• Update scout after implementation

Usage

/dev-scout                      # Project-level, medium mode
/dev-scout deep                 # Project-level, deep mode
/dev-scout auth                 # Feature-level (plans/features/auth/)
/dev-scout deep billing         # Feature-level, deep mode
/dev-scout /path/to/code        # Custom path

Output Structure

Outputs to unified plans/ structure:

plans/
├── scout/                       # Project-level (/dev-scout)
│   ├── README.md                # Current summary
│   ├── structure.md             # File tree, tech stack
│   ├── features.md              # Existing features
│   └── history/                 # Previous snapshots
│       └── {date}.md
│
└── features/
    └── {feature}/
        ├── scout.md             # Feature-level (/dev-scout {feature})
        └── ...

Modes

Mode	What It Does	When to Use
medium (default)	Structure, files, UI inventory	Quick overview
deep	+ API, models, logic, patterns	Before implementation

Exploration Strategy

Parallel Directory Search

For large codebases, use parallel exploration with Task tool:

Divide codebase into logical sections:
- Agent 1: src/app/, src/pages/ (routes & pages)
- Agent 2: src/components/, src/ui/ (UI components)
- Agent 3: src/lib/, src/utils/, src/services/ (utilities)
- Agent 4: src/api/, prisma/, db/ (backend)

When to parallelize:

• Project has 100+ files
• Multiple distinct directories
• Deep mode analysis

When to stay sequential:

• Small codebases (<50 files)
• Feature-level scout (focused area)
• Simple structure

Priority Directories

Search high-value directories first based on task:

Task	Priority Directories
General overview	README, package.json, src/app/
Feature analysis	Feature folder, related components, API routes
API understanding	api/, routes/, controllers/, services/
Data model	prisma/, models/, schema/, types/
UI inventory	components/, ui/, views/, pages/

Resilience

Handle exploration failures gracefully:

• If a directory doesn't exist: Skip, note in coverage
• If file read fails: Continue, mark as "unreadable"
• If pattern returns nothing: Try alternative patterns
• If timeout on large dir: Summarize what was found, note gap

Track coverage in output:

## Coverage
| Area | Status | Notes |
|------|--------|-------|
| src/app/ | ✓ Complete | 45 files |
| src/lib/ | ✓ Complete | 12 files |
| src/legacy/ | ⚠ Partial | Timeout after 50 files |
| docs/ | ✗ Skipped | Directory not found |

Workflow

Step 0: Check Documentation Graph

Before exploring code, check existing documentation context:

1. Read plans/docs-graph.json (if exists)
2. Find related nodes:
   - For feature scout: Find use cases, existing specs for that feature
   - For project scout: Get overview of documented features
3. Use relationships to focus exploration

How docs-graph helps:

Scout Type	Graph Provides
Project	List of documented features, existing UCs to validate
Feature	Related use cases, specs, dependencies

Example: /dev-scout auth

From docs-graph.json:
- uc-auth-001 (Login) → focus on login flow
- uc-auth-002 (Signup) → focus on registration
- [[feature-billing]] referenced → check billing integration

This context helps:

• Focus exploration on relevant areas
• Validate discovered features against documented UCs
• Find integration points via graph edges

Step 0.5: Initial Assessment

Before diving in, run quick assessment:

# Option 1: Use scout-analyze script (recommended)
./scripts/scout-analyze.sh . --check

# If tools missing, ask user:
# "Missing tools: tree, scc. Install for better analysis? (--install)"

# Run full analysis
./scripts/scout-analyze.sh .

# Option 2: Manual (if script not available)
find . -type f | wc -l
ls -la && ls -d */

Determine strategy based on file count:

File Count	Strategy
<50	Sequential, thorough
50-200	Sequential, prioritized
200+	Parallel exploration

Check for existing docs:

• README.md → Project description
• CLAUDE.md → AI instructions, patterns
• docs/ → Additional documentation
• package.json / requirements.txt → Dependencies

Step 1: Determine Scope

Project-level (/dev-scout):

• Scans entire codebase
• Outputs to plans/scout/
• Creates history snapshot if scout exists

Feature-level (/dev-scout auth):

• Scans specific area only
• Outputs to plans/features/auth/scout.md
• Links to BRD use cases

Step 2: Check for Existing Scout

If plans/scout/ exists:

1. Move current README.md to history/{date}.md
2. Create fresh analysis
3. Note what changed since last scout

If first scout:

1. Create plans/scout/ folder
2. Generate initial analysis

Step 3: Medium Mode Analysis

3.1 Documentation Check

Patterns:
- README.md, CLAUDE.md
- docs/**/*.md
- package.json, requirements.txt

Extract:

• App description
• Tech stack
• Setup instructions

3.2 File Structure Scan

Get folder tree (depth 3):
- /src, /app, /pages
- /components, /views
- /lib, /utils
- /api, /server

3.3 Frontend File Inventory

See references/file-patterns.md:

Include: **/*.vue, **/*.tsx, **/*.jsx
Exclude: node_modules/**, dist/**

Group by:

• Pages/Routes → Screens
• Components → UI inventory
• Views → Layouts

3.4 Feature Inference

See references/feature-patterns.md:

Pattern	Feature
auth/, login.*	Authentication
payment/, checkout/	Payments
dashboard/	Dashboard

3.5 Tech Stack Detection

See references/tech-detection.md:

File	Tech
next.config.*	Next.js
prisma/schema.prisma	Prisma

Step 4: Deep Mode Analysis (if requested)

Additional to medium mode:

4.1 API Analysis

Patterns:
- **/api/**/*.ts
- **/routes/**/*.ts

Document:

• Endpoints (method, path)
• Authentication requirements
• Patterns used

4.2 Data Model Analysis

Patterns:
- prisma/schema.prisma
- **/models/**/*.ts

Document:

• Entities
• Relationships
• Key fields

4.3 Code Pattern Identification

Read representative files for:

• State management
• API client patterns
• Authentication flow
• Error handling

4.4 Project Conventions Detection

Code Style (read from config or infer from code):

Check for configs:
- .eslintrc.* → Linting rules
- .prettierrc.* → Formatting
- tsconfig.json → TypeScript strictness
- .editorconfig → Tabs/spaces, line endings

Infer from code (sample 3-5 files):
- Naming: camelCase, PascalCase, snake_case
- File naming: Component.tsx vs component.tsx
- Import style: absolute (@/) vs relative (./)
- Quote style: single vs double
- Semicolons: yes/no

Git Conventions (read from history):

# Check commit style
git log --oneline -20

Detect patterns:
- Conventional commits? (feat:, fix:, chore:)
- Emoji commits? (✨, 🐛, 🔧)
- Ticket refs? (JIRA-123, #123)
- Simple messages? (no pattern)

# Check branch naming
git branch -a | head -20

Detect patterns:
- feature/*, bugfix/*, hotfix/*
- feat/*, fix/*
- username/feature-name
- No pattern

Project Conventions:

Check for:
- CLAUDE.md → AI instructions (HIGH VALUE)
- CONTRIBUTING.md → Team guidelines
- .github/PULL_REQUEST_TEMPLATE.md → PR format
- .github/ISSUE_TEMPLATE/* → Issue format

Document:
- How to name files
- How to structure components
- How to write tests
- PR/commit requirements

Step 5: Generate Output

Project-Level Output

plans/scout/README.md:

# Codebase Analysis

> **Last Updated**: {date}
> **Mode**: Medium | Deep
> **Previous**: [→ history/]

## Summary
{Brief description of the app}

## Tech Stack
| Layer | Technology |
|-------|------------|
| Frontend | {framework} |
| Backend | {framework} |
| Database | {db} |
| Auth | {method} |

## Conventions (deep mode)

### Code Style
| Aspect | Convention |
|--------|------------|
| Naming | camelCase (variables), PascalCase (components) |
| File naming | kebab-case.tsx |
| Imports | Absolute (@/lib/*) |
| Quotes | Single |
| Semicolons | No |

### Git Conventions
| Aspect | Convention |
|--------|------------|
| Commits | Conventional (feat:, fix:, chore:) |
| Branches | feature/*, bugfix/* |
| PR template | Yes (.github/PULL_REQUEST_TEMPLATE.md) |

### Project Rules
{From CLAUDE.md or CONTRIBUTING.md}
- {Rule 1}
- {Rule 2}

## Structure Overview

src/ ├── app/ # {description} ├── components/ # {description} └── lib/ # {description}

## Existing Features
| Feature | Evidence | Confidence |
|---------|----------|------------|
| Auth | `app/auth/`, `LoginForm.tsx` | High |
| Dashboard | `app/dashboard/` | High |

## Pages/Routes
| Path | File | Description |
|------|------|-------------|
| / | `app/page.tsx` | Home |
| /login | `app/login/page.tsx` | Login |

## Components ({count})
{List key components}

## API Endpoints (deep mode)
| Method | Path | Handler |
|--------|------|---------|
| GET | /api/users | users.list |

## Integration Points
{How to connect new features}

## Coverage
| Area | Status | Files | Notes |
|------|--------|-------|-------|
| src/app/ | ✓ | 45 | Routes, pages |
| src/components/ | ✓ | 32 | UI components |
| src/lib/ | ✓ | 8 | Utilities |

## Gaps / Unresolved
- {Any areas not fully explored}
- {Questions for follow-up}

## Notes
{Observations, potential issues}

plans/scout/structure.md:

# File Structure

## Directory Tree

{full tree output}

## Key Directories
| Directory | Purpose | File Count |
|-----------|---------|------------|

## Config Files
| File | Purpose |
|------|---------|

plans/scout/features.md:

# Existing Features

## Feature Inventory

### {Feature 1}
- **Status**: Complete | Partial | Planned
- **Files**: {list}
- **Depends on**: {other features}

### {Feature 2}
...

## Feature Relationships
```mermaid
graph LR
    Auth --> User
    User --> Dashboard
    Billing --> User

#### Feature-Level Output

**plans/features/{feature}/scout.md:**
```markdown
# {Feature} - Scout Analysis

> **Date**: {date}
> **Mode**: Medium | Deep
> **Feature**: [[feature-{feature}]]
> **Related UCs**: [[uc-{group}-001]], [[uc-{group}-002]]

## Summary
{What this feature does currently}

## Files
| File | Purpose |
|------|---------|
| {path} | {description} |

## Current Implementation
{How it works}

## API Endpoints (if applicable)
| Method | Path | Description |
|--------|------|-------------|

## Data Models (if applicable)
| Model | Fields | Relations |
|-------|--------|-----------|

## Integration Points
{How to extend or modify}

## For Implementation
- Entry point: {file}
- Key patterns: {patterns used}
- Dependencies: {what to be aware of}

Step 6: Update History (project-level)

If updating existing scout:

1. Move current to history/{date}.md
2. In new README.md, add:

## Changes Since Last Scout
- Added: {new files/features}
- Modified: {changed areas}
- Removed: {deleted items}

Tools Used

Tool	Purpose
Task	Parallel exploration (Explore agents)
Glob	Find files by pattern
Grep	Search code patterns
Read	Read file contents
Bash	Directory listing, file counts
Write	Output files

Parallel Exploration Example

For large codebases (200+ files), spawn parallel agents:

Task 1 (Explore): "Search src/app/ and src/pages/ for route definitions, page components. List files with brief purpose."

Task 2 (Explore): "Search src/components/ for UI components. Group by type (forms, buttons, layouts, etc.)."

Task 3 (Explore): "Search src/lib/, src/utils/, src/services/ for utilities. Identify patterns, shared logic."

Task 4 (Explore): "Search api/, prisma/, db/ for backend code. Document endpoints, models."

Synthesize results from all agents into unified scout output.

Tips

General:

• Run project-level scout first for overview
• Use feature-level before /dev-specs
• Update scout after major implementations
• History helps track codebase evolution

For large codebases:

• Start with Step 0 assessment to choose strategy
• Parallelize with 3-5 agents max (diminishing returns beyond)
• Focus deep analysis on areas relevant to task
• Accept partial coverage if codebase is huge - note gaps

For monorepos:

• Treat each package/app as separate scout target
• Document inter-package dependencies
• Use feature-level scout for specific packages

Quality over speed:

• Better to have thorough analysis of key areas than shallow scan of everything
• Flag uncertainties rather than guessing
• Include "Gaps / Unresolved" section honestly

Scripts

scout-analyze.sh

Quick codebase analysis with optional tool installation:

# Check available tools
./scripts/scout-analyze.sh . --check

# Run analysis with available tools
./scripts/scout-analyze.sh /path/to/code

# Auto-install missing tools and analyze
./scripts/scout-analyze.sh . --install

# Output as JSON (for parsing)
./scripts/scout-analyze.sh . --json

Tools checked:

Tool	Purpose	Fallback
tree	Visual directory structure	find -type d
scc	Code stats (fast, accurate)	wc -l
jq	Parse JSON configs	grep
rg	Fast search	grep -r

Output includes:

• File/directory counts
• Directory structure (depth 2)
• Code statistics by language
• Top file extensions
• Dependencies (package.json, requirements.txt, go.mod)
• Git activity (recent commits, active files, contributors)
• Config files detected

Usage in workflow:

1. Run ./scripts/scout-analyze.sh . --check in Step 0
2. Offer user to install missing tools
3. Run full analysis to inform exploration strategy

References

• references/file-patterns.md - Search patterns
• references/feature-patterns.md - Feature inference
• references/tech-detection.md - Tech stack detection