From Comments to Graph: How Spiderbrain Reads Your Documentation

Documentation has an age problem. The moment you write it, the code starts diverging from it. After six months, the Markdown files in your docs/ folder describe a system that half-exists. After a year, they're actively misleading.

The root cause is not that engineers are lazy about updating docs, it's that documentation and code are stored separately and have no structural connection. Updating code does not trigger updating docs. There is no graph edge between them.

Spiderbrain's documentation layer changes this by making docs first-class nodes in the code graph.

Documentation nodes in the graph

A Spiderbrain brain can ingest:

• Markdown files (README, docs/, architecture notes)
• JSDoc / Python docstrings (inline documentation on functions and classes)
• OpenAPI specs (API documentation as structured schema)

Each ingested documentation artifact becomes a node in the graph. Edges are created between documentation nodes and the code nodes they describe, based on:

• Explicit references (a doc mentions a filename or function name)
• Import path matching (a doc file in auth/README.md is associated with nodes in auth/)
• Keyword overlap (via the semantic layer)

Why the graph edge matters

Without a graph edge between docs and code, documentation is a static artifact. You search it separately from code. It goes stale silently.

With a graph edge:

• A blast radius computation for auth/session.js can include the docs that reference it
• When a code node changes significantly, its documentation edges are flagged for review
• AI context selection for an auth-related task includes the auth documentation automatically, not because you remembered to add it, but because the graph connects them

Documentation drift detection

One of the most practically useful outputs of the documentation graph is drift detection: documentation edges that point to code nodes that no longer exist, or code nodes that have changed significantly since their documentation was written.

Spiderbrain computes this by comparing the commit fingerprint of a code node against the last commit that touched its documentation edges. Nodes where code has advanced many commits past documentation are surfaced as drift candidates.

This is not a perfect staleness detector, code changes vary in significance. But it is a systematic one. It finds documentation that has definitely not been reviewed since the code changed, without requiring manual audits.

The doc-splitter pattern

For large documentation files (architecture overviews, long READMEs), Spiderbrain uses a section-aware splitter. Each H2/H3 section becomes its own documentation node with its own graph edges, rather than treating the whole file as one node.

This makes large documents navigable by section rather than by file. A query for "how does the auth session expire?" can retrieve specifically the session expiry section of the auth documentation, not the entire auth README.

Making documentation useful again

The goal of the documentation graph is not to automate documentation writing. It is to make existing documentation structurally connected to the codebase, so that it is surfaced when relevant, flagged when stale, and included in AI context when it would help.

Documentation that is woven into the graph is documentation that gets used. Documentation that lives in a separate Markdown silo gets searched when someone remembers it exists, and ignored the rest of the time.

The graph edge is the difference between documentation as an artifact and documentation as a living layer of your code intelligence system.