Orc Scout

---
description: Phase-scoped codebase discovery and cross-phase context bridge.
argument-hint: [slug] [phase-num]
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash(git log:*)
  - Bash(wc:*)
  - Bash(tree:*)
  - Bash(madge:*)
model: inherit
context: fork
hooks: {}
user-invocable: false
---

# Orc Scout

Phase-scoped codebase discovery that runs forked (non-interactive). Explores files referenced in PLAN.md and their surrounding code. For phases > 1, reads prior phase artifacts for cross-phase awareness.

## Input

- **$ARGUMENTS** — `{slug} {phase-num}` (e.g., `my-feature 2`)

## Template

See [templates/SCOUT.md](templates/SCOUT.md) for output format.

## Process

### Step 1: Parse Arguments and Locate Phase

```
slug = first word of $ARGUMENTS
phase_num = second word of $ARGUMENTS
```

Find phase directory:
```
Glob .claude/plans/{slug}/phases/0{phase_num}-*/PLAN.md
```

Read the matched PLAN.md.

### Step 2: Extract Target Files

From PLAN.md, collect all target files:
- `files_modified` from frontmatter
- `must_haves.artifacts` paths
- `<files>` sections from each task

Deduplicate into a single list.

### Step 3: Analyze Each Target File

For each target file:

**Existence & size:**
```
Glob for the file path
Bash: wc -l {file}
```

**Imports (what it depends on):**
```
Grep: import.*from in the file
```

**Imported by (what depends on it):**
```
Grep: import.*{filename} across src/
```

**Related tests:**
```
Glob: **/{basename}.test.* and **/{basename}.spec.*
```

**Dependency graph:**
```
Bash: madge --depends {file}
```

### Step 4: Analyze Target Directories

For each unique directory containing target files:
```
Bash: tree -L 2 -P '*.ts' {target-dir}
```

### Step 5: Discover Conventions

From the target files and their neighbors, document:
- Naming conventions (files, exports, variables)
- Error handling patterns
- Testing patterns (framework, mocking, location)
- Import organization

Include `file:line` references for each convention.

### Step 6: Cross-Phase Context (phase > 1 only)

If phase_num > 1, read prior phase artifacts:
```
Glob .claude/plans/{slug}/phases/0{prior}-*/PROGRESS-*.md  → Read each match
Glob .claude/plans/{slug}/phases/0{prior}-*/SUMMARY-*.md   → Read each match
Glob .claude/plans/{slug}/phases/0{prior}-*/IMPL-VERIFICATION.md  → Read if exists

Fallback: If PROGRESS-*.md not found, try reading PROGRESS.md (single-executor phases)
Fallback: If SUMMARY-*.md not found, try reading SUMMARY.md (single-executor phases)
```

For each prior phase:
- Extract deliverables and key files modified
- Identify files that overlap with current phase targets
- Note patterns established by prior phases

### Step 7: Write SCOUT.md

Write `.claude/plans/{slug}/phases/0{N}-{name}/SCOUT.md` using the template.

Fill all sections. For phase 1, omit the "Prior Phases" section.

## Constraint

Cannot use AskUserQuestion — forked context is non-interactive.

## Completion Criteria

- [ ] All target files from PLAN.md analyzed (existence, size, imports, importers, tests)
- [ ] `madge --depends` run on key files
- [ ] `tree` run on target directories
- [ ] Conventions documented with `file:line` references
- [ ] Cross-phase context included (if phase > 1)
- [ ] SCOUT.md written to phase directory