Discussion on "The reasoning behind a codebase, as a web you can walk"

Oliver Zehentleitner · 2026-09-29T19:14:55.362Z

Open this before you read on: keepthewhy.com/dashboard/live/#graph Give it a few seconds to settle. Then come back. It looks like a knowledge graph. It isn't. There is no graph database behind it. Nob

I like the idea of letting the links create the graph instead of maintaining a graph itself. Git already has most of the pieces, you’re just making the reasoning easier to follow.

A global graph with registered repositories ^^: https://keepthewhy.com/dashboard/live/#globe

Storing the "why" as Markdown plus a UUID in Git is a clever move, it keeps the decision next to the code and survives the people who made it. The live citation graph is the part I'd worry about maintaining, a decision web is only trustworthy if it decays when the code does. Have you found a way to flag stale reasoning nodes when the underlying code changes out from under them?

Yes, and this is exactly where I think the agent itself has to remain the brain. Keep the Why does not try to infer semantic staleness on its own. A code diff is not enough for that anyway. A decision can survive a complete rewrite, while a tiny configuration change can invalidate it.

KTW gives the agent lifecycle signals instead: Revisit when, evidence, verification, needs-review, supersession, and the surrounding rationale. When the agent works on the project again, it has to reason over those signals and the current codebase. If something no longer fits, it can flag the entry, revise it, or supersede it.

The graph helps with visibility. If one rationale entry becomes questionable, it can show the later entries linked to it and where they live. But it does not claim that they are automatically invalid.

I think that separation is important: Keep the Why stores and connects the reasoning. The agent interprets it.

Search Hashnode

The reasoning behind a codebase, as a web you can walk

Responses4