November 2025 · 4 min read

A graph is not understanding

It is tempting to think that once you have parsed a codebase into a graph of calls and references, you have understood it. You have not. You have built a very accurate map of the streets and learned nothing about which roads people actually drive.

Every edge is not equal

A call from a hot path to the function that gates a payment is not the same kind of edge as a call into a logging helper, even though the graph draws them identically. Understanding is knowing which edges carry weight — which changes ripple, which boundaries are load-bearing, which two files always break together for reasons the imports never reveal.

  • Structure tells you what connects to what. It does not tell you what matters.
  • Two systems with identical graphs can have completely different risk surfaces.
  • The edges that hurt you are often the ones the static structure cannot see.
An index answers where. Understanding answers so what. The second question is the whole job.

So the graph is a starting point, not a finish line. We layer history, ownership, and change-coupling on top of it, because a relationship that the source never declares is still a relationship. Understanding is the graph plus the judgment about which parts of it you should be afraid of.

FAQ

Common questions

Understanding is knowing which edges carry weight. The graph tells you what connects to what; understanding tells you which changes ripple, which boundaries are load-bearing, and which files always break together for reasons the imports never show. That judgment is the actual work.

We layer history, ownership, and change-coupling on top of the parsed graph. Two files that always change together are related even when neither imports the other. That relationship lives in the commit history, not the source, so a structure-only index will never surface it.

Because the graph draws a call into a payment gate and a call into a logging helper the same way. Identical structure can sit over completely different consequences. The risk surface comes from what the edges mean, and meaning is exactly what the structure leaves out.