knowledge-mcp: Skill for Claude Code

INSTRUMENT-HAZARDS — what the tools do to your measurements

Graph-read blind spots

• THE CODE GRAPH IS A SNAPSHOT — line numbers rot immediately. Use search/file_symbols/traverse as locators; the file:line you write comes from having OPENED the file. Wrong ranges cluster in NAVIGATIONAL citations.
• PLAN TREES CARRY NO METADATA: plan_tree omits metadata.command and truncates descriptions — it is an INDEX. Fetch criteria via query(ids:[...], fields:["metadata.command","description","name"]); a criteria review through a tree dump passes vacuously.
• GRAPH NODE BODIES HIDE UNDER PROJECTION: thought/finding nodes body in content — mode:"examine" renders no body and a description projection returns "". Read them UNPROJECTED (bare query(id:...)) before asserting anything about their contents. Plan/phase/step/criterion nodes body in description.
• AST ENCLOSING FIELDS ARE GRAPH-HYDRATED: file_path/lines are filesystem-true; enclosing_node_id/signature inherit index staleness. Establish containment structurally (contains_pattern) or by opening the file.
• A PER-METADATA-KEY PROJECTION omits the key entirely when a node lacks it — "empty" and "never asked" are indistinguishable in the output; an arm that ignores the projection returns rows shaped as if you asked for nothing.
• PREMISES NEED THE DEFINING ARTIFACT: a comment in file A about a fact defined in file B verifies nothing — go to the artifact that DEFINES it.

Shell semantics are not inferable (each shipped; caught only by execution)

• cmd && echo BAD || echo OK always exits 0. A piped status belongs to the LAST element.
• Under a go.work, root go test ./... is module-scoped — it can test a gen-only module and exit 0 having tested nothing. cd into the module.
• -run '^Name$' matching nothing exits 0 — anchor a grep of the runner's ^--- PASS: Name line (trailing space; never $-anchor the PASS line).
• go test result lines end with a duration — $ after a test name never matches; anchor with \( or a trailing space.
• zsh coerces an empty capture in an integer comparison (test "" -eq 0 → 0): guard every capture with test -n, or push the assertion into a script.
• zsh does not word-split unquoted expansions — a set -- $var loop can run garbage whose exit 1 mimics your expected red.
• zsh makes status a READ-ONLY alias of $? — status=$? is refused and later reads see the live $?. Syntax-check stored commands under both shells (zsh -n, bash -n).
• A linter/compiler not told a build tag never checks those files.
• TRUNCATED PIPES MANUFACTURE ABSENCE: a grep | head -N cutting before the disproving lines yields a confident false negative — absence claims require the untruncated run.