Scout Skill

Purpose

Perform systematic codebase reconnaissance to answer questions about structure, conventions, patterns, and architecture. Scout is the eyes and ears of the agent system -- it goes in first and reports back what it finds so that other skills (plan, debug, refactor, etc.) can make informed decisions.

Scout does not change code. It reads, maps, and reports.

Workflow

Mode 1: Full Reconnaissance (default for new codebases)

1. Project structure scan

   • List top-level directories and files
   • Identify project type (monorepo, single app, library, etc.)
   • Read configuration files: package.json, tsconfig.json, Cargo.toml, pyproject.toml, .env.example, etc.
   • Identify build tools, test frameworks, and CI/CD configuration

2. Tech stack identification

   • Framework(s) and version(s)
   • Language(s) and version(s)
   • Database(s) and ORM(s)
   • Key dependencies (UI libraries, state management, API clients)
   • Dev tooling (linters, formatters, type checkers)

3. Architecture mapping

   • Identify architectural pattern (MVC, hexagonal, feature-sliced, etc.)
   • Map directory structure to responsibilities
   • Identify shared/common code locations
   • Find the entry points (main files, route definitions, API handlers)
   • Map data flow: where does data come from, how does it transform, where does it go?

4. Convention detection

   • Naming conventions (files, functions, components, variables)
   • File organization patterns (co-location, separation by type, feature folders)
   • Import patterns (barrel files, direct imports, path aliases)
   • Error handling patterns
   • Testing conventions (test file location, naming, framework)

5. Produce the reconnaissance report using the template below.

Mode 2: Targeted Exploration (for specific questions)

1. Parse the question -- What specifically is the user looking for?

   • A feature: "Where is authentication handled?"
   • A pattern: "How does this project handle errors?"
   • A file/function: "Where is the user model defined?"
   • A dependency: "How is Redis used?"

2. Search strategy

   • Start with file/directory name search (Glob)
   • Then content search for keywords (Grep)
   • Then read key files to trace relationships
   • Follow imports to map the dependency graph for the target

3. Trace the feature/pattern

   • Find the entry point
   • Follow the call chain
   • Identify all files involved
   • Map the data flow specific to this feature
   • Note any tests associated with this feature

4. Report findings with file paths, code snippets, and a summary of how the pieces connect.

Mode 3: Diff Reconnaissance (for understanding changes)

1. Analyze recent changes -- What files have been modified recently?
2. Map change impact -- What other files/features might be affected?
3. Identify test coverage gaps -- Are the changed areas tested?
4. Report risk areas -- Where are changes most likely to cause breakage?

Reconnaissance Report Template

# Codebase Reconnaissance: [Project Name]

## Overview
- **Type**: [monorepo | app | library | ...]
- **Primary language**: [language + version]
- **Framework**: [framework + version]
- **Architecture**: [pattern name]

## Tech Stack
| Category | Technology | Version | Notes |
|----------|-----------|---------|-------|
| Runtime | Node.js | 20.x | |
| Framework | Next.js | 14.x | App Router |
| Database | PostgreSQL | 15 | Via Prisma |
| ... | ... | ... | ... |

## Directory Structure

project/ ├── src/ # Application source │ ├── app/ # Next.js app router pages │ ├── components/# Shared UI components │ ├── lib/ # Utilities and shared logic │ └── ... ├── tests/ # Test files └── ...

## Key Entry Points
| Purpose | File | Notes |
|---------|------|-------|
| App entry | `src/app/layout.tsx` | Root layout |
| API routes | `src/app/api/` | REST endpoints |
| Database | `prisma/schema.prisma` | Data model |

## Conventions
- **File naming**: kebab-case for files, PascalCase for components
- **Imports**: Path aliases via `@/` prefix
- **Testing**: Jest + React Testing Library, tests co-located with source
- **Error handling**: [pattern description]

## Architecture Notes
[Key observations about how the system is structured]

## Notable Patterns
- [pattern 1]: [where and how it is used]
- [pattern 2]: [where and how it is used]

## Potential Concerns
- [concern 1]
- [concern 2]

Usage

Full reconnaissance

/scout

Targeted exploration

/scout Where is authentication handled?
/scout How does the payment flow work?
/scout Find all API endpoints

Focused on a directory

/scout Explore src/lib/

Change impact

/scout What would be affected if we change the User model?

Examples

Example: Feature exploration

Input: "/scout How does file upload work?"

Process:

1. Grep for "upload", "file", "multer", "formdata" across codebase
2. Find src/app/api/upload/route.ts -- the API endpoint
3. Find src/components/FileUploader.tsx -- the UI component
4. Find src/lib/storage.ts -- the storage abstraction
5. Trace: Component calls API endpoint, which uses storage lib to write to S3
6. Find tests/upload.test.ts -- tests exist

Output: Detailed map of the upload feature with file paths, data flow diagram, and notes about the S3 configuration.

Example: Architecture mapping

Input: "/scout"

Process:

1. Read package.json -- Next.js 14, Prisma, Tailwind, etc.
2. Scan directory structure -- feature-sliced design with app router
3. Read tsconfig.json -- path aliases, strict mode
4. Check for .env.example -- environment variables needed
5. Read a few representative files to confirm patterns

Output: Full reconnaissance report with tech stack table, directory map, conventions, and notable findings.

Guidelines

• Read, do not write -- Scout never modifies files. It is purely observational.
• Start broad, go deep -- Begin with structure, then drill into specifics as needed.
• Be efficient with file reads -- Use Glob and Grep before reading full files. Read selectively.
• Report absolute paths -- All file references must be absolute paths for downstream tools.
• Flag what is unusual -- Note deviations from common conventions. These are often the most important findings.
• Do not assume -- If a pattern is ambiguous, say so. Do not guess the intent behind code.
• Respect scale -- On very large codebases, focus on the relevant subsystem rather than trying to map everything.
• Cache findings -- Store reconnaissance results in working memory for other skills to consume without re-scanning.