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.
• CODE-GRAPH READS AUTO-FILL A BRANCH OVERLAY from the local repo manifest whenever the checkout is on a branch. search and file_symbols name which graph answered in the result header's bracket ([repo@branch]); traverse renders no tell at all, so a pasted header is never its proof. Pass branch explicitly on every search/file_symbols/query/traverse read that yields a citation, and say so where the citation lands. Read and ast walk the filesystem and take no branch, so they are exempt.
• A BATCHED file_symbols limit IS A TOTAL spent in request order, not a per-file cap: the last file can render its summary and zero symbols and read as "not indexed". Re-run that file alone before concluding the index is thin.
• AN AST NAME CENSUS IS AN IDENTIFIER CENSUS: by_kind {identifier: N} is the tell. It matches no comment node, so an ast zero on a name means not-in-code, never not-in-tree. Comment text is grep's, with a same-run known-positive.
• 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.
• A DRY RUN IS A READ ON A DIFFERENT PATH, never evidence of what the real call does: a preview can resolve zero targets (it reads without tombstones) while the same call without dry_run deletes them. The reachability or effect of a write is proven only by the real call and a read-back, on a scratch target; a "would do nothing" preview is not a "cannot do it" finding.
• A SEARCH IMMEDIATELY AFTER A COLLECT CAN RETURN ZERO while the index is still being fed, and a zero-result answer echoes the query, so a reader that greps the answer for its own term passes on the miss. Read the staleness line, bound the wait, key the reader on a rendered node or a rank, and prove the reader can fail.