| name | structural-qa |
| description | Use to answer a question about how THIS harness is wired — "what enforces / guards X", "how does Y work", "what depends on Z / what breaks if I change it", "is there a path from A to B", "what's orphaned or load-bearing", "which spec governs FILE". Answer by traversing the cartograph graph (cartograph/extract.py --query / --context), citing the file each result names (Read it to pin the line), NOT by grepping. The harness is wired by lifecycle triggers + settings.json + /cmd pointers, which an import-grep misses but the graph models. Read-only. |
Structural Q&A — ask the cartograph, don't grep
The harness barely imports anything; it is wired by convention — hooks fire on
lifecycle events (settings.json), artifacts cite/invoke/spawn/nudge each other,
ADRs are referenced. A text grep sees none of that wiring and misses the blast radius
of a change. The cartograph already extracted it into a graph, and the oracle
(cartograph/extract.py --query / --context, BET A) answers from that machine-truth.
Use it for any "how is this put together / what touches what" question, then cite the
file each result carries (open it to pin the line → file:line).
Resolve the engine, then ask
Resolve install-agnostically (never assume ~/.claude), then run read-only:
HARNESS="$(dirname "$(cd "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks" && pwd -P)")"
python3 "$HARNESS/cartograph/extract.py" --context <target> # full brief for one node
python3 "$HARNESS/cartograph/extract.py" --query <kind> [target…] # one traversal
Add --json when you want to parse the result; omit it for a human-readable render.
Question → command (the mapping)
| The user asks… | Run |
|---|
| "what is X / how does X work / what enforces X" | --context X (identity, file, BOTH dependency directions, blast radius, provenance, locked/rot/unused flags) |
| "what depends on X / what breaks if I change X" | --query dependents X, then --query blast-radius X for the transitive reach |
| "what does X use / need" | --query dependencies X |
| "is there a path from A to B / how does A reach B" | --query path A B |
| "what's orphaned / unused / dead" | --query orphans (provider defs nothing uses) |
| "which spec governs FILE" / "trace SPEC" | --query governed-by FILE / --query traces SPEC |
<kind> ∈ {blast-radius, dependents, dependencies, path, orphans, node, governed-by, traces}.
Targets resolve three ways
A target is a full node id (hook:guard_trunk_lease, skill:retrospection,
command:meta-retro, cli:stats, adr:0008-feature-flags-config), OR a unique bare
name/label, OR a mapped file path (hooks/guard_trunk_lease.py). If it is ambiguous
the oracle prints the candidate ids — pass a full id. If it can't resolve, it exits
non-zero with a clean message (no traceback); don't paper over that with a grep guess.
Cite from the graph, not memory
Every brief/result names the backing file. Quote that path, and Read it to cite the
exact file:line — never assert wiring from recall. dependents/dependencies also name
the edge type, so you can say how A reaches B, not just that it does (via ∈ cites/
invokes/spawns/nudges/fires_on/references/wires/touches — touches is the state-ledger
read/write edge). --context flags whether the node is in the locked enforcement layer —
surface that when the answer informs an edit.
When NOT to use this (fall back to Grep/Read)
The graph models the loop artifacts and their wiring, not code internals. For a
question about logic INSIDE a file, a string's occurrences, or a subsystem the cartograph
touches only at the edges (mission_control / fleet internals — see ATLAS.md §7), Grep/Read
is the right tool. Don't force a graph answer the graph can't give; say which tool you used.
Worked example
"What enforces the write-lock on the enforcement layer?"
--context guard_enforcement_layer → it fires_on PreToolUse (wired by settings.json),
is flagged locked-layer, and its blast radius shows what a change ripples to. Answer: name
the hook + hooks/guard_enforcement_layer.py:<line>, the event it fires on, and that
settings.json docks it — each from the brief, none from memory.
