# dev-scout

> Explore and document existing codebases at various depths

- Author: toai.tran
- Repository: codihaus/claude-skills
- Version: 20260125060628
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/codihaus/claude-skills
- Web: https://mule.run/skillshub/@@codihaus/claude-skills~dev-scout:20260125060628

---

---
name: dev-scout
description: Explore and document existing codebases at various depths
version: 2.5.0
---

# /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:
```markdown
## 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:

```bash
# 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 .
```

```bash
# 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):

```bash
# 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:**
```markdown
# 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:**
```markdown
# File Structure

## Directory Tree
```
{full tree output}
```

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

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

**plans/scout/features.md:**
```markdown
# 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:

```markdown
## 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:

```bash
# 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