248 added, 136 removed. Audit A to A.
---
name: story-repo-scout
- description: Repo scouting workflow for using a story card, ticket, or acceptance criteria to scour the current repository, find relevant files and file paths, and append compact implementation context. Use before coding when a story needs repo context; avoid for story drafting, broad architecture review, security review, or implementation.
+ description: Inspect a repository for story-specific implementation evidence, applicable decisions, validation prior art, and bounded planning-critical external primary sources, then produce compact Repo Context. Use for pre-implementation file discovery and greenfield path grounding; use tester-mindset for test strategy and avoid requirements clarification, implementation planning, broad context management, security review, or code changes.
---
# Story Repo Scout
- Use a story card to find the repo files most likely to matter before
- implementation starts. Favor evidence, exact paths, and small output.
+ Turn a searchable change request into evidence-backed `Repo Context`. This skill
+ owns that artifact; it does not clarify product intent, design the solution, or
+ implement the change.
- ## When To Use
+ ## Required Input
- - append repo context to a generated story card or implementation ticket
- - find likely implementation, test, config, migration, or docs files before coding
- - give a human or implementation agent a better starting point for a story
- - run a lightweight repo scout when the model is smaller or context is limited
+ Accept a story card, ticket, issue, acceptance criteria, or rough request when
+ it provides at least one distinctive search anchor, such as an observable
+ behavior, domain term, route, command, UI label, error, config key, data field,
+ or known symbol. A complete story card is useful but not required.
- ## Not For
+ When the input names a path, issue, or URL, treat that source as part of the
+ input rather than relying on its title or excerpt. Read the full accessible,
+ authorized body plus material comments and linked decisions. Record its stable
+ identifier and exposed revision, update time, or commit. If access is partial
+ or unavailable, record the exact gap and its planning consequence.
- - drafting or clarifying the story itself; use `user-story-clarifier`
- - implementing code after the relevant context is already clear
- - broad architecture review, dependency mapping, or whole-repo documentation
- - security review or threat modeling; use `security`
+ If the intended behavior is too ambiguous to establish a search boundary, use
+ `story-clarifier`. If repository access or every available input lacks a
+ searchable anchor, return a truthful non-ready artifact instead of guessing.
- ## Core Workflow
+ ## Workflow
- 1. Read the story card first. If the story is too vague to search, use
- `user-story-clarifier` or ask for the missing behavior before scouting.
- 2. Extract 3-7 search handles:
- - domain nouns, actors, entities, commands, routes, UI labels, errors, config
- names, data fields, and acceptance-criteria verbs
- - avoid generic terms such as `user`, `data`, `page`, `service`, and `feature`
- unless paired with a specific qualifier
- 3. Map the repo cheaply:
- - list files with `rg --files` when available
- - inspect root docs, manifests, package files, route/config directories, and
- test directories only enough to orient the search
- - note documented commands, domain glossaries, ADRs, or context docs when
- they explain the story terms
- 4. Identify workspace boundary. If the repo has `packages/`, `apps/`,
- `services/`, `crates/`, or workspace manifests (`pnpm-workspace.yaml`,
- `lerna.json`, `turbo.json`, `nx.json`, `go.work`, Cargo workspaces, Bazel
- `WORKSPACE`/`MODULE.bazel`), restrict the search to the workspace implied by
- the story. Record the workspace in `Repo Context`. If the story spans
- multiple workspaces, name them and search each separately.
- 5. Search in passes:
- - exact handles from the story
- - obvious filename/path variants
- - nearby synonyms only if exact searches miss
- - recent git history for files changed near the story domain when exact
- searches miss
- - tests, docs, configs, migrations, fixtures, and generated examples last
- 6. Open candidate files before including them. When a test file names the
- behavior or acceptance criterion directly, treat it as an anchor — use it to
- find the implementation file it exercises. Record the observed evidence:
- symbol, route, test name, docs phrase, config key, or nearby behavior. Do not
- include a file based only on a filename guess.
- 7. Rank by implementation value:
- - entry points and handlers
- - behavior owners and domain services
- - data models, schemas, migrations, and config
- - tests, fixtures, and validation commands
- - docs that explain current behavior
- 8. Compare story language with repo language. If terms conflict with code or
- docs, add an open repo question instead of silently renaming concepts.
- 9. Mark likely unrelated or do-not-touch files when the search finds tempting
- nearby paths that should not shape the implementation.
- 10. Keep the result compact. Default cap by target executor:
- - `local-small`: 6-8 paths
- - `standard-agent` / `frontier-gpt` / `human` (default): 10-12 paths
- - up to 15 only when the story explicitly spans multiple workspaces
- Mark speculative or weak matches instead of overstating certainty.
- If no strong hits appear after all passes, report the handles tried and the
- most plausible directories to inspect next; do not invent paths.
- 11. If the story is in a file and the user asked to update it, append the repo
- context there. Otherwise output an appendable Markdown block.
+ 1. **Establish scope.** From the required input, identify the repository,
+ likely workspace or component, requested change, search anchors, and
+ provenance or access gap.
+ 2. **Read governing instructions and decisions.** Inspect the applicable root
+ and nested `AGENTS.md` files or equivalent repository policy before drawing
+ boundaries. As candidate paths emerge, read any more-specific instructions
+ that govern them. Follow relevant current domain glossaries, ADRs, and design
+ decisions, including supersession links. Record each item's exact scope,
+ status, and planning consequence. A decision record is a hard boundary only
+ when its authority, current status, and scope establish one; do not treat all
+ ADRs or design notes as do-not-edit rules.
+ 3. **Map the repository cheaply.** Use a fast file listing such as `rg --files`
+ when available, then inspect enough root docs, manifests, workspace
+ definitions, directory structure, and repository metadata to understand how
+ the project is organized. Discover the layout generically; do not assume a
+ language, build system, or fixed set of workspace directory names.
+ 4. **Search evidence-first.** Search exact anchors and their path or naming
+ variants, then follow imports, registrations, callers, tests, docs, config,
+ schemas, history, or neighboring conventions only where observed evidence
+ points. Tests may be early anchors when their names or assertions express
+ the requested behavior; do not defer them to a final pass.
+ 5. **Inspect every candidate.** Include an existing path only after inspecting
+ its content or directory listing for support. Record the observed symbol,
+ route, assertion, key, phrase, ownership rule, or structural convention. A
+ filename alone is not evidence.
+ 6. **Classify useful evidence.** Give each existing path a role, planning
+ priority, reason, and evidence strength. Docs, generated sources, vendored
+ code, fixtures, and migrations are legitimate when their role matters;
+ distinguish source-of-truth, generated-output, ownership, and integration
+ roles rather than rejecting categories wholesale. Apply the external-
+ evidence contract below to bounded planning-critical claims.
+ 7. **Ground greenfield paths.** When the change needs a file that does not yet
+ exist, list it under `Proposed Paths`, never as existing evidence. Support it
+ with an inspected parent directory, sibling pattern, manifest, registration
+ point, or documented convention. If no such basis exists, state the missing
+ decision as an open question instead of inventing a path.
+ 8. **Separate boundaries from distractions.** Treat a path as an
+ `Authoritative Constraint / Do Not Edit` only when a user instruction,
+ applicable repository policy, ownership rule, source-generation rule, or
+ similarly authoritative source establishes that boundary. Put tempting but
+ apparently unrelated paths in optional `Nearby Non-targets`; do not turn
+ scout inference into a hard constraint.
+ 9. **Reconcile language and classify gaps.** Surface material conflicts between
+ request terms and repository terms, behavior, or structure. Do not silently
+ rewrite the request to match the code. Label inspectable evidence work as a
+ `[Fact]` action and resolve it through authorized inspection; never ask the
+ user to speculate about a repository fact the scout can inspect. Label an
+ authority choice as a `[Decision]` question and name its owner. When a
+ material fact cannot be inspected, record the access or evidence gap and
+ make the artifact non-ready.
+ 10. **Stop on diminishing returns.** Keep evidence that changes where an
+ implementer would read, edit, add, or validate. Do not target a model-based
+ path quota, summarize whole files, or keep collecting equivalent weak hits.
+ 11. **Write idempotently.** Return an appendable artifact. When the user asks
+ to update a source file that already contains `Repo Context`, replace that
+ artifact in place while preserving surrounding content; never append a
+ second copy.
- ## Repo Context Output
+ ## Artifact Contract
- Use this structure by default:
+ Start every output with this common header:
```markdown
- ## Repo Context
+ Artifact Type: Repo Context
+ Status: Ready | Needs Input | Blocked
+ Reason: None | <concise readiness reason>
+ ```
- ### Workspace
- - Workspace, package, or app the story targets. Omit only for single-workspace repos.
+ Always include all three fields. Use `Reason: None` for `Ready`; otherwise name
+ the input, access, or evidence gap that prevents readiness.
- ### Search Handles
- - Concrete terms searched or derived from the story.
+ Status reflects whether the artifact can support honest planning, not how many
+ files were found:
- ### Relevant Files
- | Path | Evidence | Why It Matters | Confidence |
- |---|---|---|---|
- | path/to/file.ext | Route, symbol, test, docs phrase, or config key observed. | One-line rationale. | High/Medium/Low |
+ - `Ready`: the search produced enough existing evidence and, when needed,
+ grounded proposed paths for a planner to proceed without inventing context.
+ Any open repo questions are explicitly non-blocking to planning, and every
+ material external claim has applicable primary-source support.
+ - `Needs Input`: scouting produced a useful partial or no-hit result, but a
+ named answer, scope decision, or additional repository evidence is required
+ before planning because an unresolved unknown affects paths, authoritative
+ boundaries, or planning feasibility.
+ - `Blocked`: scouting could not be performed truthfully because required
+ repository or planning-critical primary-source access, readable inputs, or
+ search capability was unavailable.
- ### Likely Entry Points
- - path/to/file.ext: where implementation probably starts.
+ A `Ready` artifact may contain `Open Repo Questions` only when every question
+ is labeled non-blocking and states why planning can proceed without its answer.
+ If an unresolved question could change path selection, an authoritative
+ boundary, or whether a plan is feasible, use `Needs Input`; use `Blocked` when
+ the required input, repository access, or search capability is unavailable.
- ### Tests to Update
- - path/to/test.ext: existing test that will need modification for this story.
+ Apply these presence labels to every Repo Context section. Keep the output
+ headings exactly as shown in the template.
- ### Tests and Validation Targets
- - path/to/test.ext: behavior or command this may validate.
+ | Section | Presence | Rule |
+ |---|---|---|
+ | Scope and Instructions | Required | Always record the input basis, searched scope, and applicable scoped instructions. |
+ | Search Record | Required | Always record anchors, the evidence trail, and material gaps or negative results. |
+ | Existing Evidence | Required | Always include; an honest empty section is valid only for a no-hit, non-ready result. A Ready greenfield result records its inspected convention basis here. |
+ | External Evidence | Conditional | Include only for planning-critical, story-specific external claims supported by an owning primary source. |
+ | Proposed Paths | Conditional | Include only when one or more new paths are proposed from an inspected basis. |
+ | Documented Validation | Conditional | Include when trusted repository evidence identifies analogous tests, an observable seam, a documented command or probe, or other relevant prior art. |
+ | Authoritative Constraints / Do Not Edit | Required | Always include; write `None identified` when no authoritative boundary exists. |
+ | Nearby Non-targets | Optional | Include only when an attractive but unrelated lead would otherwise distract planning. |
+ | Open Repo Questions | Conditional | Include only when unresolved repository questions remain; apply the readiness rules above. |
- ### Documented Commands
- - Commands found in repo docs or manifests that may validate the story.
+ Use this structure, omitting conditional or optional sections only when their
+ stated inclusion condition does not apply. When
+ `story-to-plan-orchestrator` embeds the artifact in a Preparation Packet, it
+ may shift internal Markdown heading levels by one while preserving every
+ heading label, field, and section order:
- ### Likely Unrelated / Do Not Touch
- - path/to/file.ext: why it is nearby but outside this story.
- - `None identified` when this output will feed
- `story-implementation-orchestrator` and no boundary was found.
+ ```markdown
+ Artifact Type: Repo Context
+ Status: Ready
+ Reason: None
- ### Open Repo Questions
- - Only unresolved repo questions that materially affect implementation.
+ ## Scope and Instructions
+ - Input source and revision: story, ticket, criterion, or request identifier; revision when exposed, otherwise `no stable revision exposed`, or the exact access gap.
+ - Repository scope: repository, workspace, package, or component searched.
+ - Applicable instructions: source path and the scoped rule that affects this work.
+ - Domain language and decisions: glossary, ADR, or design source; current status, exact scope, and planning consequence.
+
+ ## Search Record
+ - Anchors: concrete terms and variants searched.
+ - Evidence trail: short note on the passes or relationships followed.
+ - Gaps: searches that produced no useful hit and plausible next leads.
+
+ ## Existing Evidence
+ | Role | Priority | Path | Observed Evidence | Why It Matters | Evidence Strength |
+ |---|---|---|---|---|---|
+ | behavior owner | Primary | path/to/file.ext | Opened symbol, route, assertion, key, phrase, or rule. | Planning consequence. | Direct |
+
+ ## External Evidence
+ | Evidence ID | Claim | Owning Primary Source and Section | Applicable Version/Date | Planning Consequence |
+ |---|---|---|---|---|
+ | EXT-1 | Planning-critical API, specification, vendor, or platform fact. | Stable source and owning section. | Version, effective date, or retrieval date when no version exists. | Constraint, compatibility consequence, or validation implication. |
+
+ ## Proposed Paths
+ | Proposed Path | Intended Role | Existing Basis | Why It Is Plausible |
+ |---|---|---|---|
+ | path/to/new_file.ext | test or implementation role | Inspected path or convention from Existing Evidence. | Planning consequence. |
+
+ ## Documented Validation
+ | Evidence Type | Source | Observable Seam or Behavior | Prior-Art Basis and Limits |
+ |---|---|---|---|
+ | analogous test, observable seam, or documented command/probe | Inspected path and symbol, or sourced command | Behavior the evidence can observe | Convention it supports and what remains undecided |
+
+ ## Authoritative Constraints / Do Not Edit
+ - `None identified`, or path/scope: authoritative source and boundary reason.
+
+ ## Nearby Non-targets
+ - path: why it is an attractive but currently unrelated lead.
+
+ ## Open Repo Questions
+ - `[Fact][Non-blocking]` evidence action: source to inspect and why planning can proceed meanwhile.
+ - `[Decision][Non-blocking]` owner and authority question: why planning can proceed without the choice.
```
- Omit empty sections when they add no signal, except keep `Likely Unrelated / Do
- Not Touch` as `None identified` when a full story-to-plan packet or orchestrator
- quality gate will consume the output. Prefer exact paths over prose. Include
- line numbers only when (a) the symbol's location is non-obvious from the file or
- (b) the implementer will need to navigate directly there. Never paste line
- numbers as decoration.
+ For `Needs Input` or `Blocked`, label each readiness-affecting question
+ `[Fact][Blocking]` or `[Decision][Blocking]`, state its planning consequence and
+ required resolution, and align the header `Reason` with that gap. A Fact entry
+ is an evidence action, not a request for the user to guess; ask the user only
+ for missing access or a source they control. A Decision entry asks the named
+ authority to choose.
- Confidence uses the same High/Medium/Low scale as `user-story-clarifier` story
- confidence. See
- `story-implementation-orchestrator` for the canonical vocabulary block when run
- end-to-end.
+ Use roles such as entry point, behavior owner, interface, schema, migration,
+ configuration, test, fixture, documentation, generated output, vendor
+ integration, or validation source. Use priority `Primary`, `Supporting`, or
+ `Context` according to planning value.
- ## Anti-Patterns
+ Evidence strength is local to each inspected path:
- Reject and rewrite when these appear:
+ - `Direct`: content explicitly owns, exercises, configures, or documents the
+ requested behavior.
+ - `Indirect`: content establishes a dependency, registration, boundary, or
+ convention that materially constrains the change.
+ - `Speculative`: inspected content provides a plausible lead, but the
+ relationship remains unconfirmed. State the gap and do not make a
+ speculative path critical without a follow-up.
- - **Filename-only match.** Path included because the name looks right but no
- symbol, route, or test was opened to confirm relevance.
- - **README phrase, no code.** Documentation mentions the feature but no
- implementation file was found. Record as an open repo question, not as a
- relevant file.
- - **Generated code.** `*.pb.go`, `*.generated.*`, `dist/`, `build/`, `target/`,
- `__generated__/`. Point to the source/schema instead.
- - **Inflated confidence.** Marking a path `High` when only the filename was
- inspected. Default to `Low` when evidence is thin.
+ For `External Evidence`, cite the source that owns each claim, not a secondary
+ summary of it. Record the applicable version or date and the specific section
+ that supports the claim. Give each row a stable `EXT-*` ID so downstream plans
+ can cite it without copying the claim, URL, and version. If authoritative
+ sources conflict, or the repository targets a version different from the
+ available source, keep the conflict visible and use a non-ready status when it
+ could change the plan.
- ## Small-Model Rules
+ For a partial or no-hit result, keep the searches tried, useful negative
+ evidence, inspected conventions, and next leads. An empty `Existing Evidence`
+ section is honest only for a non-ready no-hit result; a fabricated row is not.
+ A grounded greenfield result may be `Ready` when no implementation file exists,
+ but it must record at least one inspected parent, sibling, manifest,
+ registration point, or documented convention in `Existing Evidence` and cite
+ that row from each `Proposed Paths` entry.
- - Use short search handles and one search pass at a time.
- - Cap output at 6-8 paths (see step 10).
- - Prefer file paths and one-line rationales over summaries of code.
- - Stop when the next file would be another weak guess.
- - If no strong hits appear, report the handles tried and the most plausible
- directories to inspect next.
+ Keep `Authoritative Constraints / Do Not Edit` and write `None identified` when
+ no authoritative boundary exists. `Nearby Non-targets` is optional and must
+ not be promoted into a constraint by the planner or orchestrator.
- For executor-specific planning rules (token budget, first-action, stop-and-
- report), see `story-implementation-planner` `local-small` profile — this skill
- does not duplicate that guidance.
+ `Documented Validation` records available evidence, not a selected test
+ strategy. Capture analogous tests, the behavior or seam they observe, commands
+ or probes documented by trusted repository sources, and the precise prior-art
+ basis and limits. Leave test-level, sequencing, and validation-strategy choices
+ to `story-implementation-planner`.
- ## Universal Rules
+ ## Read-Only Boundary
- - Never invent files, symbols, commands, or repo structure.
- - Do not paste code snippets unless the user asks.
- - Do not run install, build, migration, or test commands while scouting unless
- the user explicitly asks.
- - Keep evidence short and concrete; do not summarize whole files.
+ - Use read-only repository inspection while scouting. Access external primary
+ sources only when the story-specific lookup is authorized and available.
+ - Do not run install, build, test, migration, generator, formatter, or
+ application commands. You may record commands found in trusted repository
+ docs or manifests without executing them.
+ - Do not edit code or repository configuration. The only permitted write is
+ replacing or adding the `Repo Context` artifact when the user explicitly
+ asks for that file update.
+ - Do not create a separate research note or authenticate to gain new access
+ unless the user separately authorizes that side effect.
+ - Never invent files, symbols, commands, policies, or repository structure.
## Composition Boundaries
- - **Pipeline position.** Input comes from `user-story-clarifier` (story card).
- Output is consumed by `story-implementation-planner`. Preserve `Likely
- Unrelated / Do Not Touch` paths verbatim — the planner relies on those
- boundaries.
- - Use `user-story-clarifier` first when acceptance criteria, boundaries, or
- expected behavior are unclear.
- - Use `story-implementation-planner` after this skill has appended repo context.
- - Use `tester-mindset` when the main question is what risk or evidence matters,
- not where the current implementation lives.
- - Use `security` for exploit-focused review or threat modeling.
+ - Use `story-clarifier` when product behavior, acceptance criteria, or story
+ boundaries are the primary unknowns. This scout can start from any searchable
+ input and does not require a fully formatted story card.
+ - Use `story-implementation-planner` after `Repo Context` is ready. The planner
+ owns solution steps, file dispositions, sequencing, executor adaptation,
+ risks, and validation design.
+ - Use `story-to-plan-orchestrator` when the request spans clarification,
+ scouting, planning, packet resumption, or cross-stage validation. The
+ orchestrator coordinates transitions; this skill remains the source of truth
+ for the `Repo Context` contract.
+ - Use `context-engineering` for context packets, retrieval strategy, context
+ rot, or long-running handoffs; use this skill to find story-specific
+ repository evidence.
+ - Use `tester-mindset` when the requested artifact is validation strategy,
+ coverage judgment, or oracle design; this skill only records existing
+ validation seams and prior art for the planner.
+ - Use `security` when exploit analysis, threat modeling, or security posture is
+ the primary task. Ordinary repository scouting for an auth-related story does
+ not by itself become a security review.
+ - Use the relevant implementation guidance when the user wants code or other
+ repository changes rather than a pre-implementation evidence artifact.
+
+ ## Completion Check
+
+ Before returning, verify that every existing path was inspected, every proposed
+ path has an inspected basis, the full accessible supplied source and any
+ exposed revision were recorded, lack of a stable revision was stated when
+ applicable, relevant current language and design decisions have their scope and
+ status, every material external claim has version-appropriate primary evidence,
+ validation prior art is evidence rather than selected strategy, Fact actions
+ were not delegated to user speculation, hard boundaries have authoritative
+ support, status matches downstream usability, and no execution or
+ implementation side effect occurred.