Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(guidance): task-shape skill + instructions — validated by A/B; teaches graph commands

Shrish Dwivedif4bf84a7673d
diff --git a/README.md b/README.md
index fc20c91a..78fb1e1e 100644
--- a/README.md
+++ b/README.md
@@ -195,6 +195,10 @@ graft build --extensions .ts .py # only include these code extensions
graft ask "<task>" [dir] # query the graph — ranked nodes + exact file:line (no LLM, no key)
graft ask "<task>" --json # machine-readable result
+graft callers <symbol> [dir] # who calls/references/imports/implements/extends a symbol (no LLM, no key)
+graft callees <symbol> [dir] # what a symbol calls/references/imports/implements/extends (no LLM, no key)
+graft impact <symbol> [dir] -d N # BFS over incoming edges — who breaks if this symbol changes (no LLM, no key)
+
graft check [dir] # fail (exit 1) if graft/ has drifted from the code
graft check --json # print the drift report as JSON
diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.ts
index de223390..0bf2a2d3 100644
--- a/src/claude/skill-template.ts
+++ b/src/claude/skill-template.ts
@@ -23,26 +23,44 @@ same understanding costs thousands.
- Ask: \`graft ask "<your task, in plain words>"\` — returns the relevant nodes,
ranked, with file:line pointers. Add \`--source\` to inline the actual code at
each span, so the result IS the code you need — no separate file read.
+ Ask is cheap (<1s) — re-ask with different phrasings for each sub-question,
+ and use structural forms too: \`graft ask "who calls <symbol>"\`.
- Or explore as usual: grep / ls / cat inside \`graft/\`. A grep for any concept,
symbol, or filename hits the node that covers it; \`graft/INDEX.md\` lists them
all.
-**Then STOP at the node. It is the answer, not a lookup toward the answer.**
+**Match the tool to the task shape:**
-- **Explaining / tracing / understanding** (no code change): the node's prose
- IS your deliverable. Cite files and functions straight from its \`covers:\`
- list — \`covers:\` gives you the exact \`file:line\` for every symbol, so you can
- cite precisely **without opening the source at all.** Do NOT open source to
- "verify," "confirm," or "see the real code" — the node was generated from that
- source and the spans are authoritative. Opening it costs thousands of tokens
- and changes nothing in your answer.
+- **Understanding, explaining, locating where a change goes** — the node IS the
+ answer. Cite files and functions straight from its \`covers:\` list — it gives
+ the exact \`file:line\` for every symbol, so you can cite precisely without
+ opening the source. The spans are generated from that source and are
+ authoritative; don't re-open files just to "double-check" them.
- **Editing:** run \`graft ask "<symbol>" --source\` to pull the exact span's
- code inline, and edit straight from that. Only touch the file to apply the
- change at the named \`file:line\` — never read the whole file, never open
- neighbouring files to "get oriented"; the pack already oriented you.
+ code inline, and edit straight from that. Touch the file only to apply the
+ change at the named \`file:line\` — never read the whole file to get oriented;
+ the pack already oriented you.
+- **Exhaustive tasks — "every occurrence / every provider / every caller of
+ this pattern":** ranked results are top-N, not a complete list. Use graft to
+ orient (what is the pattern, where does it live), then ENUMERATE with grep
+ over the source and verify each hit. Ask alone will miss instances; that is
+ expected, not a graft failure.
-If a node genuinely lacks a detail you need, \`graft ask\` for a more specific
-node before falling back to source. Reading whole source files to build
-understanding is the thing graft exists to replace — it already did that work.
+**Precise graph modes** — for structural questions, skip ranking and go
+straight to precomputed edges:
+
+- \`graft callers <symbol>\` / \`graft callees <symbol>\` — who breaks if this
+ changes / what does this call — precomputed edges, exact answers; structural
+ phrasing inside ask ("who calls X") routes here too.
+- \`graft impact <symbol> [-d N]\` — BFS over incoming edges out to depth N: the
+ full blast radius of a change.
+
+If a returned span is truncated ("+N more lines"), open the file at that exact
+range before finalizing.
+
+If a node genuinely lacks a detail you need, ask for a more specific node, and
+if it still lacks it, read the source — at the exact file:line the node points
+to, not the whole file. Reading whole source files to build understanding is
+the thing graft exists to replace.
`;
}
diff --git a/src/hosts/instructions.ts b/src/hosts/instructions.ts
index dcfc03ac..f49da7c3 100644
--- a/src/hosts/instructions.ts
+++ b/src/hosts/instructions.ts
@@ -11,14 +11,24 @@ system and carry exact file:line spans, kept in sync with the code through git.
For ANY task here — understanding how something works, finding where code lives,
or scoping a change — get context from the graph before grepping or opening
-source files:
+source files. Re-ask freely (it's cheap) and reuse literal identifiers you
+already have (symbol, error string, file name) as the query.
- Run \`graft ask "<your question>" --source\` → ranked nodes with the relevant
- code spans inlined. The node usually IS the answer; stop there.
+ code spans inlined. Match the tool to the task shape: for understanding or
+ editing, the top node IS the answer — cite its \`covers:\` file:line spans and
+ edit straight from \`--source\`. For exhaustive tasks ("every occurrence /
+ every caller of this pattern"), ranked results are top-N, not complete — use
+ graft to orient, then enumerate with grep over the source and verify each hit.
+- \`graft callers/callees <symbol>\` and \`graft impact <symbol> [-d N]\` give
+ precomputed, exact edges — who calls/is called by a symbol, and the full
+ blast radius — for structural questions, skip ranking and use these directly.
- Or browse: \`graft/INDEX.md\` lists every node; follow the links.
-Only open source files when a node genuinely lacks a needed detail, and then at
-the exact file:line the node points to — never re-read whole files.
+If a returned span is truncated ("+N more lines"), open the file at that exact
+range before finalizing. Only open source files when a node genuinely lacks a
+needed detail, and then at the exact file:line the node points to — never
+re-read whole files.
After big code changes, refresh the graph with \`graft build\` (deterministic,
no API key, $0).`;
diff --git a/test/claude-skill-template.test.ts b/test/claude-skill-template.test.ts
index 1655ca5f..ca63d087 100644
--- a/test/claude-skill-template.test.ts
+++ b/test/claude-skill-template.test.ts
@@ -10,4 +10,9 @@ test('skill template is a well-formed SKILL.md', () => {
const body = src.split(/\n---\n/)[1] ?? '';
assert.ok(body.trim().length > 0, 'has a non-empty body');
assert.match(body, /graft ask/, 'body tells the agent to use `graft ask`');
+ assert.match(body, /every occurrence/i, 'body teaches the exhaustive-task grep rule');
+ assert.match(body, /graft callers/, 'body teaches the callers command');
+ assert.match(body, /graft callees/, 'body teaches the callees command');
+ assert.match(body, /graft impact/, 'body teaches the impact command');
+ assert.match(body, /truncated/i, 'body tells the agent to follow up on truncated spans');
});
diff --git a/test/hosts-instructions.test.ts b/test/hosts-instructions.test.ts
index 3ae4659b..fac9aee2 100644
--- a/test/hosts-instructions.test.ts
+++ b/test/hosts-instructions.test.ts
@@ -8,6 +8,9 @@ test('canonical body names the three essentials', () => {
assert.match(b, /graft ask "/);
assert.match(b, /graft\/INDEX\.md/);
assert.match(b, /graft build/);
+ assert.match(b, /every occurrence|enumerate with grep/i, 'teaches the exhaustive-task grep rule');
+ assert.match(b, /callers/, 'teaches the callers/callees/impact commands');
+ assert.match(b, /truncated/i, 'tells the agent to follow up on truncated spans');
assert.ok(!/\bhook|statusline\b/i.test(b), 'no host-specific machinery in the shared body');
});