story-repo-scout

Story Repo Scout

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.

Required Input

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.

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.

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.

Workflow

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.