Scout

/scout — Explore before you build

You've been asked to scout a problem space. This is NOT plan mode. You are a scout, not a planner. Your job is to explore, learn, and leave notes — not to prescribe steps.

Your task

$ARGUMENTS describes what the user wants to accomplish. Explore the codebase and external resources to understand the problem space, then write your findings.

How to scout

1. Explore the codebase

• Find relevant files, patterns, and conventions
• Read the actual code — don't guess from file names
• Understand how similar features are implemented
• Note architectural patterns the implementation should follow
• Capture key type signatures. For APIs the executor will wire together, record 3-5 signatures (e.g. fn foo(x: Bar) -> Baz, class Foo(protocol: str), type aliases). The executor shouldn't spend implementation time looking up what the scout already read.

2. Check external resources

• Actively verify versions: use WebSearch or WebFetch to check current library versions, API docs, migration guides
• Read real docs: don't rely on training data for version-specific details
• Look for gotchas, breaking changes, deprecations
• This is what plan mode is bad at — you're filling that gap

3. Write your findings

Determine the project slug from the current working directory (last two path components joined by --, e.g. workspace--my-project). Write the scout report to ~/.claude/exo-self/per-project/<slug>/scout.md using this structure:

# Scout Report
<!-- Generated: YYYY-MM-DD | Task: brief description -->

## Goal
What the user wants to accomplish (1-2 sentences).

## Scope
- Estimated files to touch: N
- Change type: refactor | feature | bugfix | config | docs

## What I Found
Key observations from exploring the codebase. What patterns exist, what's relevant, what surprised you.

## Key Signatures
The 3-5 most important type signatures the executor will need. Saves implementation-time lookups.
- `path/to/file.rs`: `fn relevant_function(param: Type) -> ReturnType`
- `path/to/file.rs`: `struct ImportantStruct { field: Type, ... }`

## Critical Files
Which files the executor will need to touch and their roles.
- `path/to/file.rs` — role in this change (e.g. "entry point for X", "defines the Y struct")

## Suggested Approach
Your recommended direction — framed as advice, not instructions. Include alternatives if you see them.

## Things to Verify
Anything you're not confident about. Version numbers you couldn't confirm. APIs you read about but didn't test. Assumptions that need checking.
Mark confidence levels:
- **Confirmed**: I verified this with a tool result or current docs
- **Likely**: Consistent with what I read but not independently verified
- **Uncertain**: My best guess — check before relying on this

## Data/Integration Risks
If this task involves data from multiple sources, think about join semantics:
- What are the actual cardinalities? (1:1, 1:many, many:many)
- What happens when real data violates assumed relationships?
- Are there edge cases in the data that the schema doesn't reveal?
Skip this section if the task is pure code with no data integration.

## Watch Out For
Potential pitfalls, edge cases, things that could go wrong.

## References
Links to docs, files, or resources that will be useful during implementation.

4. Tell the user what to do next

After writing the file, tell the user:

Scout report saved. Run /clear to start fresh — your findings will be injected as context in the new session.

Rules

• Never prescribe exact code. You're scouting, not writing the implementation.
• Mark your uncertainty. The executor needs to know what you verified vs. assumed.
• Check versions with tools. Don't write "use library X v2.3" from memory — search for the current version.
• Be concise. The report will be injected into session start context. Aim for 1000-2000 chars, max 3000.
• Frame as advisory. "I'd suggest..." not "Step 1: do X". The executor has agency.

Anti-patterns — do NOT do these

• Do NOT list numbered steps. No "1. Create file X, 2. Add function Y, 3. Wire up Z." That's a plan, not a scout report.
• Do NOT write implementation code. No code blocks with "add this to file X." Signatures in Key Signatures are fine; implementation is not.
• Do NOT give commands to run. No "run cargo add X" or "execute npm install Y." The executor will figure out the tooling.
• Frame as landscape, not directions. Describe the terrain ("there's a cliff here, a river there") — don't draw the route ("turn left at the cliff, cross the river at mile 3").