| name | understand-codebase |
| description | Understand an unfamiliar codebase or plan a change safely, using Spine's deterministic knowledge-graph MCP tools. Reach for this before answering structural questions about a repo you don't know, before editing code, or when debugging — it hands you engineering decisions (what a change breaks, what's untested, where a ticket or bug lands), each grounded to file:line. Triggers: "how does this repo work", "what breaks if I change X", "where do I fix this / where does this land", "what's untested here", "explain this symbol", "map this codebase", "which docs cover this". Tools: map_repo, blast_radius, explain_symbol, investigate, localize, regression_gaps, docs_for (all read-only, no credentials, from the Spine plugin). |
Understand a codebase with Spine
Spine reads a repository's Product Knowledge Graph — a deterministic, no-LLM index of its
modules, types, functions, call sites, and blast radius, with every fact grounded to file:line.
These MCP tools turn that graph into decisions, not just lookups: what a change breaks, what's
untested, where work lands. They're read-only, need no credentials, and take a local
repo_path (default: the current repository).
Use them before grepping or guessing about an unfamiliar repo — they're faster and more accurate,
and they cite their sources.
Which tool for which question
| You want to… | Call |
|---|
| get oriented in a repo you don't know | map_repo — languages, components, call-hotspots, test-coverage gaps, prioritized recommendations |
| know what changing a symbol will affect | blast_radius(symbol=…) — direct callers + the cross-layer set a change ripples into, each file:line |
| understand one symbol | explain_symbol(symbol=…) — kind, location, who calls it, what it calls, what it contains |
| find where a feature/ticket lands | investigate(title=…, problem=…) — the real symbols to start from |
| pin a bug from a stack trace | localize(trace=…) — resolve each frame to the repo symbol; the likely fault site |
| see what a change could break silently | regression_gaps(symbol=… or trace=…) — blast-radius symbols with no covering test |
| root-cause a bug (hypotheses + fix approach) | root_cause(bug=…) — fault site, ranked hypotheses with evidence, regression surface, fix approach; deterministic (add use_llm=true for richer hypotheses) |
| find which docs describe code (or how documented it is) | docs_for(symbol=…) — the doc pages that mention a symbol; call with no symbol for a doc-coverage summary + top drift. Ingests .md/.rst/.txt/PDF |
Read a repo's committed knowledge base with read_memory_bank when one exists (built by
orchestrator understand).
repo_path defaults to the current repository, and also accepts a git URL (e.g.
https://github.com/org/repo) — Spine shallow-clones it, extracts, and cleans up.
How to work
- Orient first. For an unfamiliar repo, call
map_repo before answering structural questions
or planning a change — one call beats many greps.
- Check the blast radius before editing.
blast_radius(symbol=…) shows who depends on what
you're about to touch; regression_gaps shows what has no test, so you know what could break
silently.
- For a bug, go trace → fault → coverage.
localize(trace=…) finds the fault site; then
regression_gaps(trace=…) shows the coverage around it.
- Cite
file:line. Every tool returns provenance and a markdown field you can show the user
directly — ground your answer in it rather than paraphrasing.
Good to know
- Deterministic: same commit in → same answer out (a commit-keyed cache makes re-runs cheap).
- Structured + readable: each tool returns typed fields (symbols, counts,
file:line, gaps)
and a markdown rendering.
- Understanding vs. changing: these tools only read. To actually change the code — spec →
grounded codegen → tests → branch/PR — use Spine's gated
sdlc_feature, which requires an
explicit confirm for any external write. Keep the two separate.
