scout

name	scout
description	Research & analysis workflow. Investigates questions, gathers findings, optionally validates with a fresh subagent. Produces a report — no code, no PRs, no commits. Use standalone or as a fellowship teammate.

Scout — Research & Analysis

Overview

Investigates questions and analyzes codebases without producing code changes. Runs autonomously through Investigate → (Validate) → Deliver phases. When used as a fellowship teammate, the scout agent definition enforces read-only tool access. Also works standalone.

When to Use

• Research questions about a codebase ("how does X work?")
• Deep analysis ("what are all the entry points for auth?")
• Data collection ("list all API endpoints and their middleware chains")

Phase Flow

Investigate ──→ (Validate) ──→ Deliver

Process

Investigate

Goal: Gather thorough, factual findings about the question.

Actions:

1. Invoke /council to load task-relevant context
2. Use Explore agents (Agent tool, subagent_type=Explore) to scan relevant code paths
3. Read key files, trace call chains, understand behavior
4. Document findings with specific file paths and line references

Investigate must produce:

• Specific file paths and line ranges for every claim
• Clear explanation of how things work (not just where they are)
• Constraints, edge cases, and dependencies identified
• Confidence level for each finding (High/Medium/Low)

High confidence = verified by reading actual code at specific lines. Medium confidence = inferred from patterns, naming, or partial evidence. Low confidence = assumption based on conventions or incomplete information.

If findings are incomplete, keep investigating. Don't move to validation or delivery with gaps.

Validate (conditional)

Goal: Adversarially verify findings using a fresh subagent with no context pollution.

When to validate:

• Deep analysis involving multiple systems or complex interactions
• Findings that will inform architectural decisions or code changes
• Questions where being wrong would waste significant downstream effort
• Any time there are Medium or Low confidence findings that matter

When to skip validation:

• Simple lookups ("where is X defined?")
• Straightforward questions with all High confidence answers
• Time-sensitive quick questions

Validation procedure:

1. Write your findings to a working file (e.g., docs/research/<topic>.md) — do NOT commit
2. Spawn a validator subagent via the Agent tool with subagent_type "general-purpose":

You are a research validator. Your job is adversarial: challenge
assumptions, verify factual claims, and flag anything wrong or unsupported.

FINDINGS TO VALIDATE:
<paste findings here, including file paths and line references>

INSTRUCTIONS:
1. For each factual claim, read the referenced file and line range.
   Does the code actually do what the finding says?
2. For each Medium/Low confidence finding, investigate independently.
   Can you confirm or refute it?
3. Produce a validation report:
   - CONFIRMED: claims you verified are correct
   - CONTESTED: claims that are wrong or misleading, with evidence
   - UNVERIFIED: claims you couldn't confirm or deny

BOUNDARIES:
- Read any file. Do NOT modify any files or run commands.
- Be adversarial — your value is in catching errors, not agreeing.

3. Review the validation report
4. For contested findings: re-investigate, correct or remove the finding
5. For unverified findings: downgrade confidence or investigate further

Deliver

Goal: Send findings to the requester in a structured format.

Fellowship teammate: Send via SendMessage to the lead (Gandalf). Standalone: Present findings directly to the user.

Write findings file: In both modes, write the full report to .fellowship/scout-findings-{scout_name}.md (using the configured dataDir if overridden). This file enables scout-to-quest promotion — without it, findings can't be promoted into a quest. The {scout_name} comes from the scout's name (e.g., scout-auth-analysis). Do NOT commit this file.

Report format:

## Scout Report: <question>

### Findings
- <finding 1> (`path/to/file.ts:42-58`)
- <finding 2> (`path/to/other.ts:10-25`)
- ...

### Confidence
- High: <list>
- Medium: <list>
- Low: <list>

### Validation
- Confirmed: <validated claims>
- Contested: <claims corrected after validation>
- Skipped: <if validation was not performed, say why>

### Files Written
- <list any research files written, noting they are not committed>

Routing (fellowship only): If the spawn prompt includes a routing target (e.g., "→ send to quest-auth-bug"), also send findings to that teammate via SendMessage in addition to the lead.

Fellowship Integration

When running as a fellowship teammate, the scout agent definition restricts your tools to read-only source access plus Write for research notes (Read, Glob, Grep, Agent, Skill, TaskUpdate, SendMessage, Write). Phase metadata names for task updates: "Investigating", "Validating", "Done". See agents/scout.md for full details.

Key Principles

1. Evidence over opinion. Every finding needs a file path and line reference.
2. Confidence is honest. Don't mark something High if you inferred it.
3. Validation catches errors. When in doubt, validate. Fresh eyes find what you missed.
4. No side effects. In fellowship, tool restrictions enforce this. Standalone, respect it by convention.