/dev-scout - Codebase Pattern Discovery

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

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

Discover and document how the codebase works - patterns, rules, and team conventions for EXISTING code.

When to Use

• Understand how the project works before implementation
• Document team patterns and conventions for new engineers
• Discover architectural patterns that must be followed
• Capture existing features and how they're implemented

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:

...