@codihaus/claude-skills 1.6.6 → 1.6.8

package/skills/dev-scout/SKILL.md

@@ -1,936 +1,212 @@
 ---
 name: dev-scout
-description: Explore and document existing codebases at various depths
-version: 2.9.0
+description: Discover and document how the codebase works - patterns, rules, and team conventions
+version: 3.0.0
 ---
 
-# /dev-scout - Codebase Explorer
+# /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
 
-Explore and document codebases. Works at project level or per feature.
+Discover and document **how the codebase works** - patterns, rules, and team conventions. Not a file inventory.
 
 ## When to Use
 
-- Understand existing codebase before adding features
-- Document current state for team
-- Analyze specific area before implementation
-- Update scout after implementation
+- Understand **how the project works** before implementation
+- Document **team patterns and conventions** for new engineers
+- Discover **architectural patterns** that must be followed
+- Capture **the rules** that won't change soon
+
+**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 (plans/features/auth/)
+/dev-scout auth                 # Feature-level
 /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
-│   ├── stack.md                 # HOW the project works (API, data, patterns)
-│   └── history/                 # Previous snapshots
-│       └── {date}.md
-│
-└── features/
-    └── {feature}/
-        ├── scout.md             # Feature-level (/dev-scout {feature})
-        └── ...
-```
-
-**stack.md is critical** - it tells `/dev-specs` HOW to write specs that fit the project:
-- Use the right SDK (not raw fetch)
-- Follow existing patterns (composables, hooks, services)
-- Respect data access method (BaaS vs direct DB)
-- Use correct validation/form libraries
-
-## 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
-
-### Large Codebase Strategy (500+ files)
-
-For very large codebases, use `/utils/gemini` for initial scan:
-
-```
-1. Count files
-   → find . -type f | wc -l
-   → If 500+, use Gemini
-
-2. Run Gemini scan
-   → python skills/utils/gemini/scripts/gemini-scan.py \
-       --path . \
-       --output plans/scout/gemini-summary.md
-
-3. Read Gemini output
-   → Gemini provides: structure, patterns, key files
-
-4. Claude refines
-   → Deep dive on key files Gemini identified
-   → Add analysis and recommendations
-   → Create final scout.md
-```
-
-**Why Gemini for large codebases?**
-- Gemini Flash: 1M token context (can fit entire codebase)
-- Claude: 200K context (may not fit all files)
-- Gemini scans cheap/fast, Claude analyzes precisely
-
-### Parallel Directory Search
-
-For medium codebases (100-500 files), use parallel exploration:
-
-```
-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 use which strategy:**
-
-| Files | Strategy |
-|-------|----------|
-| <50 | Sequential (simple) |
-| 50-100 | Sequential or parallel |
-| 100-500 | Parallel agents |
-| 500+ | Gemini first, then focused Claude 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 -1: Ensure Project Scout Exists (for Feature Scouts)
-
-**IMPORTANT**: If running a feature-level scout, check if project-level scout exists first:
-
-```
-If user requested: /dev-scout {feature} (feature-level)
-1. Check: plans/scout/stack.md exists?
-   → No: Run project-level scout FIRST
-      - Notify: "No project scout found. Analyzing entire project first, then {feature}..."
-      - Execute: Project-level scout (steps below)
-      - Output: plans/scout/README.md, structure.md, features.md, stack.md
-   → Yes: Continue to feature-level scout
-
-If user requested: /dev-scout (project-level)
-→ Skip this check, proceed directly to Step 0
-```
-
-**Why this matters:**
-- Feature scouts need project context (tech stack, patterns, structure)
-- `stack.md` is critical for understanding HOW the project works
-- Prevents isolated feature analysis without understanding the whole
-- Downstream skills (`/dev-specs`, `/dev-coding`) depend on `stack.md`
-
-**User Experience:**
-```
-User: /dev-scout auth
-Assistant: "No project scout found. I'll analyze the entire project first to understand the tech stack and structure, then focus on the auth feature specifically."
-
-[Runs project-level scout]
-✓ Project scout complete: plans/scout/
-
-[Then runs feature scout]
-✓ Feature scout complete: plans/features/auth/scout.md
-```
-
-### 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
+## Core Rule: Capture Patterns, Not Inventory
 
-#### 4.4 Project Conventions Detection
+**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)
 
-**Code Style** (read from config or infer from code):
+**Don't Capture (Volatile):**
+- File trees → use Glob fresh
+- Component/route lists → discover when needed
+- File counts → meaningless
+- Exhaustive inventories → stale immediately
 
-```
-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):
+## Output
 
-```bash
-# Check commit style
-git log --oneline -20
+### Project-Level
+**Location:** `plans/brd/tech-context.md` (~150-200 lines)
+**History:** `plans/brd/history/tech-context-{date}.md`
 
-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: Stack Analysis (CRITICAL)
-
-Generate `stack.md` - tells downstream skills HOW to work with this project.
-
-See `references/stack-patterns.md` for detection patterns.
-
-#### 5.1 Detect API Layer Type
-
-```
-Check for BaaS first (higher priority):
-1. .env vars: DIRECTUS_URL, STRAPI_URL, SUPABASE_URL, etc.
-2. package.json: @directus/sdk, @supabase/supabase-js, etc.
-
-If no BaaS:
-3. Check for API framework: express, fastify, hono
-4. Check for GraphQL: @apollo/client, urql, graphql
-5. Check for tRPC: @trpc/server
-```
+**Answers:**
+- How do we make API calls?
+- How do we access data?
+- How do we structure code?
+- How does our team work?
 
-#### 5.2 Detect Data Access Pattern
+### Feature-Level
+**Location:** `plans/features/{feature}/codebase-context.md`
 
-```
-If BaaS detected:
-- Data managed by BaaS (don't suggest raw SQL)
-- Note which collections/content types exist
-
-If no BaaS:
-- Check for ORM: prisma/, drizzle.config.*
-- Check schema files for models
-- Direct DB access pattern
-```
+**Prerequisite:** MUST have `tech-context.md` first (patterns already documented)
 
-#### 5.3 Detect API Client Pattern
+**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?
 
-```
-Search for how the project calls APIs:
+**Does NOT repeat:**
+- Project-wide patterns (already in tech-context.md)
+- Tech stack info (already documented)
+- Code conventions (already documented)
 
-React projects:
-- hooks/use*.ts → Custom hooks pattern
-- services/*.ts → Service layer pattern
-- @tanstack/react-query → React Query pattern
+## Expected Outcome
 
-Vue projects:
-- composables/use*.ts → Composables pattern
-- stores/*.ts → Pinia stores
-- @tanstack/vue-query → Vue Query pattern
+### Project-Level: `tech-context.md` (~150-200 lines)
 
-Next.js:
-- actions/*.ts → Server Actions
-- app/api/** → API Routes
-- Server components with direct calls
+Answers the question: **How does this project work?**
 
-Identify the PRIMARY pattern used (not all).
-```
+**Captures (stable patterns):**
+- How we make API calls (wrapper, pattern, error handling)
+- How we access data (ORM, queries, abstractions)
+- How we structure code (folders, naming, organization)
+- What our conventions are (naming, formatting, git workflow)
+- Tech stack choices (framework, libraries, tools)
 
-#### 5.4 Detect Validation & Forms
+**Does NOT capture (volatile):**
+- File trees (use Glob fresh)
+- Component/route lists (discover when needed)
+- File counts (meaningless)
+- Exhaustive inventories (stale immediately)
 
-```
-Validation:
-- zod in package.json → Zod schemas
-- yup → Yup schemas
-- Find: schemas/, validators/, *.schema.ts
-
-Forms:
-- react-hook-form → useForm pattern
-- vee-validate → VeeValidate
-- formik → Formik pattern
-```
+### Feature-Level: `codebase-context.md`
 
-#### 5.5 Detect External Services
+Answers the question: **How does THIS feature work?**
 
-```
-Parse .env.example or .env:
-- STRIPE_* → Payment (Stripe)
-- RESEND_* → Email (Resend)
-- AWS_S3_* → Storage (S3)
-- SENTRY_* → Monitoring (Sentry)
+**Prerequisite:** MUST have `tech-context.md` first (patterns already documented)
 
-Match with package.json to confirm SDK.
-```
+**Captures:**
+- How this feature implements the patterns (not the patterns themselves)
+- Where the key files are (entry points, core logic)
+- How to extend this feature
+- Feature-specific gotchas
 
-#### 5.6 Detect Local Services
+**Does NOT repeat:**
+- Project-wide patterns (already in tech-context.md)
+- Tech stack info (already documented)
+- Code conventions (already documented)
 
-```
-Parse docker-compose.yml or compose.yml:
-- postgres → PostgreSQL
-- redis → Redis
-- minio → S3-compatible storage
-- directus → Directus CMS
-```
+## Success Criteria
 
-#### 5.7 Detect Available MCPs
+- 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
 
-```
-Check .claude/settings.local.json or mcp.json:
-- context7 → Library docs lookup
-- playwright → Browser automation
-- shadcn → UI components
-- Custom MCPs → Project-specific tools
-```
+## Discovery Approach
 
-#### 5.8 Generate stack.md
-
-Output `plans/scout/stack.md`:
-
-```markdown
-# Project Stack
-
-> Auto-detected by /dev-scout. Verify and update as needed.
-
-## API Layer
-| Aspect | Value |
-|--------|-------|
-| Type | {REST/GraphQL/tRPC/BaaS} |
-| Service | {Directus/Supabase/Custom/etc.} |
-| SDK | {package name if applicable} |
-
-## Data Access
-| Aspect | Value |
-|--------|-------|
-| Method | {BaaS-managed/ORM/Direct SQL} |
-| ORM | {Prisma/Drizzle/none} |
-| Models | {list key models} |
-
-## API Client Pattern
-| Aspect | Value |
-|--------|-------|
-| Pattern | {hooks/composables/services/direct} |
-| Location | {folder path} |
-| Example | {primary function used} |
-
-## Validation & Forms
-| Aspect | Value |
-|--------|-------|
-| Validation | {Zod/Yup/none} |
-| Schemas | {folder path} |
-| Forms | {react-hook-form/vee-validate/native} |
-
-## External Services
-| Service | Provider | Env Var |
-|---------|----------|---------|
-| {type} | {provider} | {var} |
-
-## Local Services (docker-compose)
-| Service | Purpose | Port |
-|---------|---------|------|
-| {name} | {purpose} | {port} |
-
-## Available MCPs
-| MCP | Capability |
-|-----|------------|
-| {name} | {what it provides} |
-
-## Specs Guidelines
-
-Based on this stack, implementation should:
-1. {guideline based on API layer}
-2. {guideline based on data access}
-3. {guideline based on patterns}
-4. {guideline based on validation}
-
-## Stack Knowledge References
-
-For best practices and patterns, downstream skills should read:
-{list only those that apply to this project}
-- `knowledge/stacks/directus/_index.md` - Directus SDK patterns, queries, auth
-- `knowledge/stacks/nuxt/_index.md` - Nuxt composables, SSR, server routes
-- `knowledge/stacks/nextjs/_index.md` - Server Components, Actions, App Router
-```
+### Project-Level
 
-### Step 6: 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}
-```
+**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
 
-## 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}
-```
+**Deep Mode:**
+- All of Medium +
+- Deeper pattern analysis (API, data access)
+- Code convention detection
+- Git & team process
 
-**plans/scout/structure.md:**
-```markdown
-# File Structure
+### Feature-Level
 
-## Directory Tree
-```
-{full tree output}
-```
+**Lightweight approach - reads patterns, not rediscovering:**
 
-## Key Directories
-| Directory | Purpose | File Count |
-|-----------|---------|------------|
+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:** How THIS feature uses the patterns, where code lives, how to extend
 
-## Config Files
-| File | Purpose |
-|------|---------|
-```
+## Pattern Discovery Rules
 
-**plans/scout/features.md:**
-```markdown
-# Existing Features
+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?"
 
-## Feature Inventory
+## Strategy by Codebase Size
 
-### {Feature 1}
-- **Status**: Complete | Partial | Planned
-- **Files**: {list}
-- **Depends on**: {other features}
+| Size | Strategy |
+|------|----------|
+| Small (<100 files) | Sequential discovery |
+| Medium (100-500) | Parallel by concern (API, data, UI, conventions) |
+| Large (500+) | Use `/utils/gemini` first, then focused Claude analysis |
 
-### {Feature 2}
-...
+## Version Management
 
-## Feature Relationships
-```mermaid
-graph LR
-    Auth --> User
-    User --> Dashboard
-    Billing --> User
-```
-```
+**When tech-context.md exists:**
+- Move current to `history/tech-context-{date}.md`
+- Note what changed (pattern changes, not file changes)
 
-#### Feature-Level Output
+**When feature scout requested:**
+- Check tech-context.md exists first
+- If not, run project-level scout first
 
-**plans/features/{feature}/scout.md:**
-```markdown
-# {Feature} - Scout Analysis
+## Output Template
 
-> **Date**: {date}
-> **Mode**: Medium | Deep
-> **Feature**: [[feature-{feature}]]
-> **Related UCs**: [[uc-{group}-001]], [[uc-{group}-002]]
+See `references/output-template.md` for structure.
 
-## 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
+## Tools
 
 | Tool | Purpose |
 |------|---------|
-| `Task` | Parallel exploration (Explore agents) |
-| `Glob` | Find files by pattern |
+| `Read` | Docs, configs, sample files |
+| `Glob` | Find patterns (wrappers, configs) |
 | `Grep` | Search code patterns |
-| `Read` | Read file contents |
-| `Bash` | Directory listing, file counts |
-| `Write` | Output files |
-| `Playwright` | Capture UI screenshots |
-
-### Playwright for Visual Documentation
-
-When scouting a web app, capture screenshots of key UI:
-
-```
-1. Start the dev server (if not running)
-   → Bash: npm run dev
-
-2. Navigate to app
-   → mcp__playwright__browser_navigate({ url: "http://localhost:3000" })
+| `Bash` | Git history for conventions |
+| `Task` | Parallel pattern discovery |
+| `Context7` | Library patterns |
 
-3. Take screenshots of key pages
-   → mcp__playwright__browser_take_screenshot({
-       filename: "plans/scout/screenshots/home.png"
-     })
+## Large Codebase Strategy
 
-4. Capture different states
-   → Login page
-   → Dashboard (if accessible)
-   → Key feature pages
-```
-
-**When to capture UI:**
-- Initial project scout (what does app look like?)
-- Before major UI changes (for comparison)
-- Feature scout (existing UI in that area)
-
-**Output:**
-```
-plans/scout/screenshots/
-├── home.png
-├── login.png
-├── dashboard.png
-└── feature-{name}.png
-```
+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
 
-Include in scout.md:
-```markdown
-## Current UI
-
-### Home Page
-![Home](./screenshots/home.png)
-
-### Dashboard
-![Dashboard](./screenshots/dashboard.png)
-```
-
-### 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
+## Anti-Patterns
 
 **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
+❌ Listing every file in a directory
+❌ Counting components/routes
+❌ Including full file trees
+❌ Documenting file locations (use Glob instead)
+❌ Reading every file (sample instead)
 
-### scout-analyze.sh
+**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)
 
-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
-```
+## Reference
 
-**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
-- `references/stack-patterns.md` - Deep stack analysis (API, data, patterns)
+See `references/output-template.md` for output structure (principle + empty template).