Research · skill report
stardust, described the same way as everything else here.
Codger got a benchmark because there were comparable projects to measure it against. This one gets a description instead: the pipeline, the audit trail that makes its output checkable, and the places where it is judgement rather than measurement. Same skeleton, one honest substitution.
← Back to the skill pageGoal
A generated graph beside the repo is dead the day it's made.
Tools that extract a codebase into a knowledge graph usually render it to their own output folder: an HTML viewer, a JSON file, a separate query engine. It looks impressive once, then the code moves and the artifact is wrong, and nobody edits it because editing a generated file is pointless. Astro already is that renderer, though: notes are stars, wiki-links are edges, and a vault is open Markdown on your own disk. So this drops the output layer entirely and writes the graph as vault content. The payoff is a graph you can navigate, correct and link the moment it exists.
Kept from that lineage: the extraction pipeline, the audit trail, clustering, hub detection, incremental update. Dropped: the output folder, the HTML viewer, the standalone graph file, the separate query engine. Astro's own MCP server is the query engine.
Method
Six stages, in this order.
Extraction and inference are deliberately separate passes. Reading the source can only produce evidence-backed edges; anything concluded happens later, over the node set, and is tagged as such.
01 · Scope
Walk the path, respect .gitignore, exclude node_modules, build output, .git, binaries and anything over roughly 200 KB. Report the file count before extracting anything.
02 · Extract
Read the files and emit nodes, with EXTRACTED edges only. This pass invents nothing: an edge exists here because an import, a call or a citation exists in the source.
03 · Infer
A second pass over the node set, not the files: shared state, parallel naming, two names for one concept, lifecycle ordering. Emits INFERRED and AMBIGUOUS only, and stays conservative unless asked to go deep.
04 · Cluster
Find groups by edge density rather than by folder, and name each for what it does. Mark hubs, the top few percent by degree, with their connection count.
05 · Write
Notes into one folder under the vault, so an import is one thing the user can delete in one gesture. Then the two reports. Astro's watcher picks it all up live.
06 · Verify
Run the audit over its own output before declaring done: dangling links, notes with no edges either way, near-duplicate titles, edges whose evidence no longer exists.
The honest part
No tag, no edge. That rule is the whole result.
An extracted graph is worth something only if you can tell what was read from what was guessed. Each link carries its provenance in the note itself, as a comment beside the link, so the distinction survives the run that made it: EXTRACTED names the evidence, INFERRED names the reasoning in a clause, AMBIGUOUS marks plausible and unconfirmed. INFERRED is never promoted to EXTRACTED without re-reading the source.
Two notes land beside every import. A graph report in plain language: clusters, hubs, the cross-cluster edges that reading the files in order would never have surfaced, and what to read first. And a graph audit, the one that has to be uncomfortable to be useful: tag counts, every ambiguous edge with its reasoning, files skipped and why. A cap at N files or a dropped directory is named there. Silent truncation reads as complete coverage, which is the failure this whole design exists to avoid.
Constraints
An import is not a silent side effect.
Hundreds of notes landing in a vault someone opened for something else is a real harm, so before the first write it states the vault, the path and the estimated note count and waits. It never guesses a vault path and never creates one. If the vault's existing notes are plainly about a different subject than the corpus, it stops. A note you have since edited by hand is never overwritten by an update: if its source changed it gets a review callout appended instead. And no key, token, .env content or gitignored file is ever written into a note.
Limits
Where this is judgement, not measurement.
- There is no benchmark. The comparison that would matter, graph-walking against plain search on the same questions, needs a task suite and a corpus nobody has built yet. This page describes behaviour; it does not claim a measured result.
- The inference pass is model judgement by construction. That is exactly why INFERRED and AMBIGUOUS are separate tags and why every ambiguous edge is listed in full in the audit note: the reader checks the reasoning rather than trusting the graph.
- Node granularity is a judgement call. One note per idea rather than per file is what keeps the sky readable, but the line between an idea and a line in its parent's note is drawn by the extractor, not by a rule.
- Cluster names are written, not computed. Density finds the group; naming it for what it does is prose, and a bad name makes a real cluster look arbitrary.
- Incremental updates compare source modification times. A file whose meaning changed without its mtime changing, or a rename that preserves content, is not caught by that.
- A large corpus costs real time and real tokens to import. The dry run exists so that cost is a decision rather than a surprise.
Code
The skill is the specification.
There is no binary and no runtime to inspect. The skill is one Markdown file, and everything on this page is in it, in the order it executes.
Next
What would turn this into a result.
One corpus, one set of questions with known answers, two runs: an agent walking the graph against the same agent grepping the folder. Score answer correctness, citation accuracy, and the tokens each route costs, because an answer that is right and four times more expensive is not obviously a win. That suite doesn't exist yet, and until it does this stays a description.
The research tracks →