sparq: Skill for Claude Code

ast-grep + outline: read STRUCTURE, not whole files

[OPUS-4.8] Internal agent skill. Authored by Opus 4.8 (Fable unavailable — flag for re-review when Fable returns). Design basis: research/agent-effectiveness-program.md §2.2 (the query-type → tool map) and the shared A/B protocol in research/dogfooding-sparq-knowledge-graph.md §5.

The single load-bearing idea: a "where / how is X done" question over a big file or a 37-crate workspace usually does not need the file's bytes — it needs the file's skeleton (signatures) or a structural match (all impls of a trait, all call sites of a function). Reading the whole file to answer it spends tokens proportional to the file, not the answer. ast-grep gives you the answer-sized view: tree-sitter structural matching with file:line hits, zero runtime deps.

This is a tool, not a verdict. Whether ast-grep + outline actually beats the Grep + Read baseline on agent tokens for this repo is decided by the §5 A/B (see the bottom of this file), not by this skill. Use the recipes; do not cite an unmeasured saving.

Honest scope — the verdict splits by the SHAPE of the task (two firm real-token A/Bs settle it; §5). Whether a structural view saves tokens depends on the question class:

• Scoped code-structure LOOKUP ("where / how is X", "every impl of T"): ast-grep
  • outline are precision / completeness tools, measured NOT to save tokens — the firm A/B (bench/pkg-dogfood/RESULTS-astgrep.md) found going outline/ast-grep-FIRST on a lookup is slightly MORE expensive end-to-end than a scoped Read. Their edge over a competent grep -rn is precision and completeness: they skip the same token inside comments/strings and match shapes a line-regex cannot ($X.map($$$).collect(), a call with a specific arg), and in that A/B that bought a small quality nudge on call-site completeness — not a raw token cut. For a lookup, reach for ast-grep when grep's false positives or its inability to express a structure actually bite, or when you must NOT miss an impl/call-site; do not reach for it to cut tokens.
• Whole-file-SHAPE understanding, or a structural edit / codemod over a LARGE file: generating a compacted-AST skeleton FIRST and working over it IS a measured token-saver — a second firm A/B (bench/ast-compact/RESULTS.md) found the compacted-AST-first arm cheaper at equal quality on the large majority of such tasks, with the win growing with file size / structural breadth. See the recipe in §2.6 and the decision rule below.

Decision rule: scoped lookup answerable by a narrow read → just Read (don't pay the structural-view setup tax; both A/Bs show it slightly hurts on a small, already-narrow task); whole-file shape, or a cross-file structural edit/codemod over a large file → build the compacted-AST skeleton (§2.6) first. The narrow "outline only a very large single file's skeleton to locate a span" lever (§2.1, §4) is the lookup-side floor of this same rule.