Dev Scout

What Scout Does vs Doesn't

Scout documents EXISTING code:

• ✅ How the project currently works (patterns, conventions)
• ✅ Complete list of existing features
• ✅ How each feature is implemented (for understanding/extending)

Scout does NOT plan NEW features:

• ❌ NOT for creating implementation specs
• ❌ NOT for planning new features
• ❌ Use /dev-specs for new feature planning

Not for: Listing files, counting components, inventorying routes (use Glob/Grep fresh instead)

Usage

/dev-scout                      # Project-level, medium mode
/dev-scout deep                 # Project-level, deep mode
/dev-scout auth                 # Feature-level
/dev-scout deep billing         # Feature-level, deep mode

Core Rule: Capture Patterns, Not Inventory

Capture (Stable):

• Patterns & abstractions (e.g., apiRequest() wrapper)
• Architecture decisions (e.g., Server Actions)
• Code conventions (e.g., naming, structure)
• Tech choices (e.g., Zod, Prisma)
• Team process (e.g., git workflow)

Don't Capture (Volatile):

• File trees → use Glob fresh
• Component/route lists → discover when needed
• File counts → meaningless
• Exhaustive inventories → stale immediately

Output

Project-Level

Location: plans/brd/tech-context.md (~150-200 lines) History: plans/brd/history/tech-context-{date}.md

Answers:

• How do we make API calls?
• How do we access data?
• How do we structure code?
• How does our team work?

Feature-Level

Location: plans/features/{feature}/codebase-context.md

Prerequisite: MUST have tech-context.md first (patterns already documented)

Answers:

• How does THIS feature work? (not patterns - those are in tech-context.md)
• Where are the key files for this feature?
• How to extend this feature?
• What to watch out for?

Does NOT repeat:

• Project-wide patterns (already in tech-context.md)
• Tech stack info (already documented)
• Code conventions (already documented)

Expected Outcome

Project-Level: tech-context.md (~150-200 lines)

Answers: How does this project work?

For new developers, provide:

• Patterns - How we make API calls, access data, structure code (with file/location references)
• Conventions - Team standards for naming, formatting, git workflow
• Stack - Tech choices and why
• All existing features - Complete list (important: don't miss any!)

Format: Overview + location reference, NOT do/don't lists

Example:

### API Communication
**Pattern:** All API calls go through `lib/api/client.ts` wrapper
**Location:** See `lib/api/client.ts` for implementation
**Usage:** Import `apiClient` and call methods

NOT:

✅ DO: Use apiClient
❌ DON'T: Use fetch directly

Feature-Level: codebase-context.md

Answers: How does THIS already-implemented feature work?

Purpose: Document existing implementation for understanding/extending, NOT create specs

Prerequisite: MUST have tech-context.md first

Captures:

• How this feature uses the patterns (reference tech-context.md)
• Where key files are (locations, entry points)
• How it currently works (flow, architecture)
• How to extend it (what to modify where)

Does NOT:

• Create implementation specs (this is for EXISTING code)
• Repeat patterns (reference tech-context.md instead)
• Include do/don't lists (show pattern usage with locations)

Success Criteria

• New engineer can follow patterns from output
• Patterns shown with examples, not theory
• Rules captured, not procedures
• No file inventories or counts
• Feature scout reuses patterns from tech-context.md
• ~150-200 lines for tech-context.md

Discovery Approach

Project-Level

Medium Mode (default):

• Read project docs (CLAUDE.md, README, configs)
• Detect tech stack from package.json, configs
• Sample 2-3 files per category to discover patterns
• Extract conventions from configs
• Discover ALL existing features (don't miss any - scan routes, pages, API endpoints)

Deep Mode:

• All of Medium +
• Deeper pattern analysis (API, data access)
• Code convention detection
• Git & team process

Output: tech-context.md with patterns + complete feature list

Feature-Level

Purpose: Document existing implementation for understanding/extending

NOT FOR: Creating specs or planning new features

Lightweight approach:

1. Check prerequisite: tech-context.md exists? If not, run project-level first
2. Read patterns: Load tech-context.md (now you know API pattern, data access, conventions)
3. Focus on feature: Find files (Glob/Grep), read 2-3 key files, identify entry points
4. Document existing code: How it works NOW, where files are, how to extend

Output: codebase-context.md describing current implementation

Pattern Discovery Rules

1. Sample, don't exhaust - Read 2-3 representative files, not all
2. Find abstractions - Wrappers, base classes, shared utilities
3. Capture with example - Show the pattern in action
4. Ask "what's the rule?" - Not "what files exist?"

Strategy by Codebase Size

Version Management

When tech-context.md exists:

• Move current to history/tech-context-{date}.md
• Note what changed (pattern changes, not file changes)

When feature scout requested:

• Check tech-context.md exists first
• If not, run project-level scout first

Output Template

See references/output-template.md for structure.

Tools

Large Codebase Strategy

For 500+ files, use /utils/gemini:

1. Gemini scans full codebase (1M context)
2. Claude reads Gemini output
3. Claude deep dives on key patterns identified
4. Creates pattern-focused scout

Anti-Patterns

General: ❌ Listing every file in a directory ❌ Counting components/routes ❌ Including full file trees ❌ Documenting file locations (use Glob instead) ❌ Reading every file (sample instead)

Feature Scout Specific: ❌ Rediscovering project patterns (already in tech-context.md) ❌ Repeating API/data/validation patterns (reference, don't rewrite) ❌ Re-documenting tech stack (already known) ❌ Running full project analysis (lightweight, feature-focused only)

Reference

See references/output-template.md for output structure (principle + empty template).