dev-scout

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

```

/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

```

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})

└── ...

```

| Mode | What It Does | When to Use |

|------|--------------|-------------|

| medium (default) | Structure, files, UI inventory | Quick overview |

| deep | + API, models, logic, patterns | Before implementation |

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

| 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 |

```

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

1. 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/]

{Brief description of the app}

| Layer | Technology |

|-------|------------|

| Frontend | {framework} |

| Backend | {framework} |

| Database | {db} |

| Auth | {method} |

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}

```

src/

├── app/ # {description}

├── components/ # {description}

└── lib/ # {description}

```

| Feature | Evidence | Confidence |

|---------|----------|------------|

| Auth | app/auth/, LoginForm.tsx | High |

| Dashboard | app/dashboard/ | High |

| Path | File | Description |

|------|------|-------------|

| / | app/page.tsx | Home |

| /login | app/login/page.tsx | Login |

{List key components}

| Method | Path | Handler |

|--------|------|---------|

| GET | /api/users | users.list |

{How to connect new features}

| Area | Status | Files | Notes |

|------|--------|-------|-------|

| src/app/ | ✓ | 45 | Routes, pages |

| src/components/ | ✓ | 32 | UI components |

| src/lib/ | ✓ | 8 | Utilities |

• {Any areas not fully explored}
• {Questions for follow-up}

{Observations, potential issues}

```

plans/scout/structure.md:

```markdown

# File Structure

```

{full tree output}

```

| Directory | Purpose | File Count |

|-----------|---------|------------|

| File | Purpose |

|------|---------|

```

plans/scout/features.md:

```markdown

# Existing Features

{Feature 1}

• Status: Complete | Partial | Planned
• Files: {list}
• Depends on: {other features}

{Feature 2}

...

```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]]

{What this feature does currently}

| File | Purpose |

|------|---------|

| {path} | {description} |

{How it works}

| Method | Path | Description |

|--------|------|-------------|

| Model | Fields | Relations |

|-------|--------|-----------|

{How to extend or modify}

• 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

• Added: {new files/features}
• Modified: {changed areas}
• Removed: {deleted items}

```

| 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.

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

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/file-patterns.md - Search patterns
• references/feature-patterns.md - Feature inference
• references/tech-detection.md - Tech stack detection