| name | scope |
| description | Use when you're about to work a task and want the exact file set to read FIRST instead of crawling the tree — "what files are involved in X", "scope this task", "what does the auth/search/sheets/onboarding feature touch", "give me a context pack for <task>", "which files advance <intention>", "where do I start on <feature>". Maps a task description or an intention id to the intention(s) it advances, then emits a SCOPED CONTEXT PACK: every file advancing it with its one-line role/why + reach + dependencies BOTH directions + blast-radius. Exploration → lookup. Lives in tooling/scope/. |
scope — task → scoped context pack
The delivery end of the codebase-intelligence suite. Instead of an agent crawling
the tree to discover what a task touches, scope answers it from the already-built
graph: a task (or intention id) → the metadata-first file set advancing it,
each file annotated so the agent reads the pack and opens source only where it
edits. Exploration becomes lookup.
Run it
node tooling/scope/scope.mjs <intention-id> # e.g. layered-auth (or intent-layered-auth)
node tooling/scope/scope.mjs "harden auth scoping" # free-text task → best-matching intention(s)
node tooling/scope/scope.mjs --list # every intention id + member count
node tooling/scope/scope.mjs <task> --json # machine-readable pack
node tooling/scope/scope.mjs <task> --top 40 # cap the file list (default 30, by reach)
It reads tooling/barkpark-sync/nodes.json (generated by the suite — run
node tooling/status/status.mjs once if it's missing). No deps, no network, no
source mutation.
How matching works
- Exact id — the bare slug (
layered-auth) or the full intent-layered-auth.
- Name match — substring on slug or intention title.
- Keyword match — word-overlap on title + description (stop-words dropped);
returns up to the top 3 intentions, union'd into one pack.
Start with --list when unsure which intention a task maps to.
What the pack contains
Per matched intention: id, title, scale, description. Then the files advancing it,
ranked by reach (the single value root — normalized transitive dependents),
each carrying:
- role / why — the one-line purpose (no need to read the file to know it).
- reach — 0–100 normalized transitive-dependent count.
- blast-radius — # files that break if this one changes (
dependentCount).
- depends on (→) and depended on by (←) — dependencies both directions.
- whatBreaks — the failure mode if changed wrong.
- tested / UNTESTED flag.
--json returns { query, matchedBy, intentions[], fileCount, shown, files[], note }
for an agent to consume directly.
When to reach for it
- About to implement / refactor / debug a feature and want the file set up front.
- Briefing a sub-agent — paste the pack so it never re-derives the dependency graph.
- Estimating blast-radius before a change touches a high-reach file.
See .claude/skills/codebase-quality/SKILL.md for how the underlying graph and the
canonical roots (tooling/SIGNALS.md) are built.
