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

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

Decisions that cite each other across repositories — no graph database, no central index, no account. Just Markdown and Git.

Julian Neagu

Oct 1

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.

Oliver Zehentleitner

Oct 1

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

Kartik N V J K

Sep 30

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.

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

Written by

Responses4

Search Hashnode

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

Written by

Responses4