graphtrail

Use when answering structural code questions in an indexed repo - who calls this, what does this call, what breaks if I change it, what changed between two versions. Reach for it BEFORE grep whenever

SKILL.md

GitHub

graphtrail

GraphTrail keeps a SQLite code graph (symbols, imports, call edges) per repo, synced incrementally and queryable through 9 MCP tools. The point of this skill: for structural questions, the graph answers in one call what grep answers in five speculative ones, and the graph knows about relationships grep cannot see (cross-file call resolution through imports, transitive impact, before/after structure).

When to use which tool

  • "Who calls X?" -> callers. "What does X call?" -> callees. Exact answers from resolved call edges, including cross-file calls resolved through imports. grep finds the string X(; the graph finds the actual callers of THIS X.
  • "What breaks if I change X?" -> impact with --depth for transitive reach. This is the blast-radius question; hop counts tell you how direct the dependency is.
  • "Where is symbol X?" -> search (qualified-name aware, path-filterable). Faster and more precise than grep for symbol lookup; use grep when you want arbitrary text, comments, or strings.
  • "What is around this file?" -> file_neighbors (imports in, imports out, co-change candidates) and context for an orientation brief before editing unfamiliar code.
  • "What changed structurally?" -> diff with two DB snapshots (--before/--after). Reports added/removed/changed symbols (body-hash exact: a body edit with unchanged signature is detected) and call-edge changes, with line-insensitive edge counts alongside raw ones. Brigade attaches these deltas to verify and run receipts automatically, and records context_eval.brief_hit_rate when a pre-run code-graph brief is compared to the post-run delta (did the brief name the files that actually changed?).
  • "Which repos are indexed?" -> repos; per-repo numbers -> stats.

Freshness

The graph re-syncs on a 15-minute timer, at session start (hook), and on demand: query tools accept refresh: true to run an incremental sync before answering. Sync is incremental and cheap; a no-op pass is sub-second. Use refresh: true when you just wrote code and are about to ask about it.

When NOT to use it

  • Text questions: strings, comments, TODO hunts, log messages. That is grep/ripgrep.
  • Pattern-shaped syntax questions ("find every foo(_, None) call shape"): that is ast-grep, which matches tree structure by example. The three lanes are exact-graph (graphtrail), tree-pattern (ast-grep), and text (grep). Pick by question shape.
  • Repos with no .graphtrail/ index: check repos first; index one with graphtrail sync <root> if it should be covered.

Honest limits

  • Call edges include the call line, so raw added/removed edge counts churn on pure line shifts; the diff's line-insensitive counts exist for exactly this. Read both.
  • Dynamic dispatch, reflection, and metaprogrammed calls are not in the graph. An empty callers result means no STATIC callers.
  • The graph is derived state, rebuildable by rescan. When in doubt about staleness, refresh: true or graphtrail sync.

Brigade loop (when the repo is Brigade-wired)

GraphTrail is half of the measured context loop. After work flows through Brigade:

  1. Verify/run receipts carry code_graph_delta (fail-open if GraphTrail is missing).
  2. brigade receipts export miseledger --new-only --import archives those receipts.
  3. The next brigade run can attach a MiseLedger evidence brief; when a code-graph brief was present, context_eval.brief_hit_rate measures coverage.
  4. brigade operator checkup reports graph ok / ledger ok / last brief hit rate in one glance.

Use brigade-work for the full verify → capture → export discipline; this skill is the structural-query half.