flow-scout-instructions

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- flow-instructions-sentinel: flow-scout-instructions -->

# Scout instructions

These instructions are read by the scout subagent that `/flow-new-feature`'s
SKILL.md spawns via the Task tool. The subagent runs in an isolated context —
its file reads, codebase scans, reference loads, and analytical prose stay
inside its own session and are never returned to the caller. The only outputs
it produces are the artifact it writes to disk (`.flow-tmp/scout.md`) and a
brief one-paragraph summary it returns on completion.

Same shape as `/flow-product-planning`'s discovery subagent (PR #95). The
context-cost win is identical: the supervisor never sees the codebase reads
that the Critical Analysis depends on, but still gets a structured artifact
with everything Critical Analysis needs to assess scope, debt risk, and
composability.

The wrapper passes you these inputs in its spawn prompt:

- The verbatim user feature description.
- The absolute worktree path (your working directory).
- The absolute skill base directory (`SKILL_DIR`). Resolve every sibling
  template/reference path under it. Those files do not exist relative to the
  worktree you `cd`'d into — they live in the skill directory, which is
  somewhere else on disk (typically `~/.flow/claude-home/.claude/skills/flow-new-feature/` or
  `<flow-checkout>/skills/pipeline/flow-new-feature/`).
- The absolute path to write `scout.md` (`SCOUT_PATH`).
- The approved plan path (`PLAN_PATH`) — an absolute path when an approved
  plan with a heading (any level, case-insensitive) matching `Task
breakdown` exists, the literal string `absent` otherwise. A non-`absent`
  value switches step 2 into verify-not-rederive mode (see step 2b).

Follow the steps below in order.

## 1. Load Project Context

Before forming opinions about scope or strategy, load background context so
your scouting is informed:

- Read `README.md` (if present) for architecture, tech stack, and existing
  capabilities.
- Read `AGENTS.md` / `CLAUDE.md` (if present) for project-level rules and
  conventions. A scout report that conflicts with documented constraints
  is a rework risk.
- Scan the project's source tree to understand existing modules and domain
  models. Don't read every file — read the ones the user description
  implicates plus their immediate neighbours.
- List `.claude/skills/` (or the project's skill directory) to identify
  skills that may apply. The scout reports _which_ skills are relevant via
  `recommended_strategy`; it does not pre-load them.

This is read-only background — these reads stay in your context and don't
propagate to the supervisor.

## 2. Identify the Affected Surface

Decide what the feature actually touches. The user description names some
modules; the codebase will reveal others (call sites, sibling components,
shared types, related tests). Collect:

- **Concrete files and modules** the feature edits or creates.
- **Adjacent files** that would feel surprising if left untouched (e.g. a
  page that consumes a renamed export, a test that asserts the old shape).
- **Public API surface** — what other code imports from the affected
  modules. Renaming or restructuring a public surface is much more
  expensive than a private-only change; flag this early.

Be specific: a path, not "the auth module". A function name, not "some
helpers".

**Existing-code assessment.** For every surface the feature would extend,
decide: **keep** (the shape fits; extend in place), **simplify** (extend
after a small local cleanup — name it), or **rewrite** (extending compounds
debt — name the smell: stacked workarounds, god-module, obsolete
abstraction, dead branches). Write the verdict on the `## affected_modules`
bullet as `— assessment: <verdict> — <why, path:line>`, and mirror every
non-keep verdict as `EXISTING-CODE: <path> — <verdict> — <why>` under
`## anti_patterns`.

## 2b. Verify-not-rederive (plan-supplied runs only)

When `PLAN_PATH` is not `absent`, an approved plan has already made the
interface-level decisions, and your step-2 job shifts from re-deriving the
affected surface to **verifying the plan's contract against the code**:

- Read ONLY the plan's Task breakdown section (the heading matching
  `Task breakdown`, any level, case-insensitive) — not the PRD prose. The
  upstream rationale dilutes your codebase focus; the per-task Contract
  blocks (Files / Interfaces / Call-site edits / acceptance command) are
  the claims you verify.
- Verify each Contract claim against the codebase, per the Files list's
  create-vs-edit marking: for an **edit**-type claim, verify the named
  file exists, the named symbol exists, and the stated signature matches;
  for a **create**-type claim the file and symbol don't exist yet by
  design — verify non-collision instead (the path isn't already taken,
  the symbol isn't already exported elsewhere). Also verify `Call-site
edits:` claims (named existing file + symbol) the same way as edit-type
  claims.
- Fill genuine gaps the plan left unspecified — adjacent files, tests,
  public-API fan-out — exactly as steps 2–3 describe.
- Record each contradiction as a `PLAN-DEVIATION:`-prefixed bullet in
  `## open_questions`: what the plan claims, what the code actually shows,
  and the corrected interface. Never silently follow a contradicted
  contract and never silently rewrite the plan — the contract is a strong
  prior, not a straitjacket.

The six-section artifact shape (step 7) is **unchanged** in this mode —
`PLAN-DEVIATION:` bullets live inside the existing `## open_questions`
section; there is no seventh section. When `PLAN_PATH` is `absent`, skip
this step entirely.

## 3. Identify Relevant Tests

For each affected file, find the test that covers it. Note:

- **Existing tests** that this feature must keep green (regression risk).
- **Missing tests** — places where the feature touches code with no
  coverage. The Critical Analysis can decide whether to expand coverage
  as part of the feature; the scout just reports the gap.

From gavingolden/flow, MIT.

More from gavingolden/flow