code-graph

Files (5)

• SKILL.md
• discover-files.mjs · scripts/
• repo-survey.mjs · scripts/
• test-discover-files.mjs · scripts/
• test-repo-survey.mjs · scripts/

SKILL.md (first lines)

# Symbol retrieval, dependency leads and patch impact

Whenever you use graph, include a brief final-answer assessment of whether it
helped your reasoning and why, including a concrete limitation when it did not.
Do not equate static leads with correctness or measured test coverage.

Use graph for discovery and static relationships. An empty result is not proof
of absence. Inspect source before editing; investigate relevant unresolved edges.
Test leads are not test coverage. Audit/impact `unresolved_calls` separates calls
originating in changed symbols from repository totals and gives exact call-site
`read`/`grep` followups. These are unresolved/ambiguous leads, not dependencies.
Check returned/truncated counts; this initial view covers changed symbols only,
not every unresolved edge in the transitive impact scope. A gap-free result does
not exclude dynamic callers.

The `graph` tool retrieves exact definitions from a verified source snapshot and
answers relationship questions from the same index. For concept-to-code discovery,
try `search_symbols` before broad grep/file reads, then retrieve the selected
implementation with `symbol_source`. Use `grep` when results are absent or low
confidence. Read surrounding file context before editing. The opt-in patch audit
uses the graph at the end of a native `write`/`edit` run.

For an unfamiliar repository area, start with a bounded overview rather than a
chain of broad directory and symbol queries:

```
graph {action:"overview", aspects:["modules","entry_points","boundaries"], limit:8}
```

Each section reports exact `total`, `returned`, and `truncated` counts. Ask for a
specific section or a larger limit only when the clipped rows hide a needed lead.

## Scoped file discovery fallback

For an external/unindexed repository or a low-confidence graph result, choose
explicit relative roots (`src`, `docs`, a named module) and filename terms from
the task. Do not print `rg --files <absolute-root>`: repeated root prefixes can
consume the response before useful paths arrive. Run from that root and return
relative paths. A clipped inventory is not evidence of absence; do not hide it
with `head`, discard the tail, or repeat the same whole-tree request.

The read-only helper [scripts/discover-files.mjs](scripts/discover-files.mjs)
requires explicit scope, reports scanned/matched/returned counts and emits complete
JSON pages within a byte budget. Paths are not summaries. The recorded spell
`code-graph-discover-files` accepts shell-quoted `runner_arg`, `root_arg`, `scope_arg`
and `match_arg`; `scope_arg` is one relative root and `match_arg` a path regex.
Its postcondition requires a complete page, but replay currently refuses mandatory
session workspaces (`workspace_execution_context_unsupported`). The spell is not
replay-verified or preferred: use the verified direct CLI below without relaxing
the workspace binding; prefer the spell only after actual postconditions pass:

```
node <absolute-skill-dir>/scripts/discover-files.mjs --root <repo> --scope src --scope docs --match 'executor|server|security|session' --max-bytes 8192
```

If `complete:false`, keep the exact page and continue with its `next_offset`
and `snapshot` using `--offset N --snapshot SHA`; a changed inventory refuses.
Alternatively narrow an unrelated scope, never pretend omitted candidates were
examined. Scope/term selection and reading the returned source remain inference.
Read independent known source ranges together with `read_many`, keeping exact
bytes, errors and continuation addresses. No index or filter replaces necessary
source inspection. Private proof: `node <skill>/scripts/test-discover-files.mjs
<absolute-evidence-scratch>`; it checks pagination, Unicode/space paths, ignored
files, exact candidate sets, changed-snapshot refusal and visible failures.

## Retained public-repository surveys

After a collector has saved full metadata, pinned commit/tree JSON and README/source
files in session evidence scratch, do not print its complete results/excerpts or
recursive file inventory. Use [scripts/repo-survey.mjs](scripts/repo-survey.mjs):

```
node <absolute-skill-dir>/scripts/repo-survey.mjs --cache <absolute-cache> --max-bytes 8192
```

The metadata-only view retains every candidate, explicit counts/failures and relative
evidence paths. Inspect selected original files; omitted excerpts are still cached.
Continue an incomplete page with `--offset <next_offset> --snapshot <snapshot>`;
changed cache evidence refuses. Do not refetch the network just to repair display.
`repo-survey-cached-view` records this verified read-only sequence; required worktrees
use the direct CLI, not unsupported replay. Source CLI works without a node restart.
Private proof: `node <skill>/scripts/test-repo-survey.mjs <absolute-evidence-scratch>`.
See [the cache contract](../../docs/REPO-SURVEY.md); metadata is not a quality benchmark.

## Retrieve implementation source

```
graph {action:"search_symbols", name:"session routing", limit:8}
```

When seeking a component or function implementation rather than a state binding,
pass `prefer_implementations:true`. This opt-in ranking lowers partial local
variables while leaving them visible. It is useful for multiword concept search;
leave it off when variables are the subject of the task.

Results are ranked by explainable BM25-like lexical evidence plus a small
graph-centrality boost. camelCase and snake_case identifiers are tokenized.
`score`, `score_breakdown`, `confidence`, `reason`, `matched_terms`,
`unmatched_terms`, and `unmatched_definition_terms` expose why a result ranked.
`high` means every concept word appears in the definition name or signature;
`medium` means some do; `low` may be path evidence alone. A `partial` verdict
means the top definition misses words even if its path contains them. This is
lexical retrieval, not semantic proof. Retrieve a useful candidate with
`symbol_source`, then confirm missing words with a bounded `grep`/`read` before editing.

When a named component from a task is absent, try one exact-name lookup and a
bounded source search. Record the absence as a finding and inspect the nearest
verified component. Repeating broader concept queries without new evidence
does not make an absent symbol appear. There is no elapsed-time cutoff for
discovery; stop a search when its evidence is sufficient to choose the next step.

```
graph {action:"symbol_source", path:"lua/core/agent.lua", name:"choose_worker", line:123, kind:"fn"}
```

Copy the selector fields from one search result. The source is the exact syntax
definition from the graph's verified snapshot. Large definitions are paged;
continue with the returned `next_byte_offset` and `source_version`. A selector cannot read arbitrary
files. Source retrieval replaces the first broad read, but inspect imports and

From Magaav/wasm-agent, MIT.

More from Magaav/wasm-agent