{"slug": "the-reasoning-behind-a-codebase-as-a-web-you-can-walk", "title": "The reasoning behind a codebase, as a web you can walk", "summary": "A developer built Keep the Why, a system that renders a knowledge-graph-like view of software design rationale by reading ordinary Markdown entries already stored in Git repositories, with no graph database, central index, or account required. Entries carry stable IDs and cite each other across repositories via plain-text \"See:\" references, letting the reasoning of multiple projects appear as one connected structure without moving any content into a central store. The project distinguishes nested \"families\" of related repositories from \"friends\" that merely cite one another, so each decision has a single owning repository rather than duplicated copies.", "body_md": "**Decisions that cite each other across repositories — no graph database, no central index, no account. Just Markdown and Git.**\n\nOpen this before you read on:\n\n**keepthewhy.com/dashboard/live/#graph**\n\nGive it a few seconds to settle.\n\nThen come back.\n\nIt looks like a knowledge graph.\n\nIt isn't.\n\nThere is no graph database behind it. Nobody maintains nodes and edges. There is no central service collecting project knowledge.\n\nWhat you are looking at is reasoning that was already sitting in Git repositories as Markdown.\n\nThe graph is just what appears when those reasons start citing each other.\n\nThe project in the centre is Keep the Why itself.\n\nIts hubs are topics from `context/`. Around them are individual entries: decisions, rejected alternatives, workarounds, incident learnings and constraints — things the code can tell you happened, but usually cannot tell you **why**.\n\nEach entry is an ordinary Markdown section in the repository.\n\nFor example:\n\n```\n## Keep dashboard exports read-only\n\n**Id:** <uuid>\n**Type:** decision\n**Status:** active\n**Evidence:** confirmed\n**See:** https://github.com/owner/repo — <entry-id> — as of 2026-09-29\n\n**Reason:**\n...\n\n**Rejected alternative:**\n...\n```\n\nThe colour of an entry shows how well its reason is supported. Its shape tells you whether it is still active, superseded, or needs another look.\n\nGit provides the history: who first recorded it, who touched it later, when its status changed.\n\nThe dashboard adds none of that information.\n\nIt reads what is already there.\n\nThat distinction matters to me: delete the dashboard and the project has lost nothing.\n\nThe more interesting part is further out.\n\nYou will see other projects around Keep the Why.\n\nOne is [repo-native project memory](https://oliver-zehentleitner.github.io/repo-native-project-memory/), the thesis Keep the Why belongs to.\n\nAnother is the [UNICORN Binance Suite](https://github.com/oliver-zehentleitner/unicorn-binance-suite), a family of related repositories.\n\nNobody added those projects to a graph configuration.\n\nThey appear because an entry in one repository cites an entry in another.\n\nThat citation is still just text:\n\n```\n**See:** https://github.com/owner/repo — <entry-id> — as of 2026-09-29\n```\n\nThe entry ID is stable. A heading can be reworded, a topic file can be split, and the reference still identifies the same piece of reasoning.\n\nOnce those references existed, something unexpected became possible:\n\nthe reasoning of several repositories could be viewed as one connected structure without moving any of it into a central store.\n\nI ended up with three different kinds of connection.\n\nThey sound informal, but the distinction turned out to be useful.\n\nA family is a group of projects that belong together.\n\nA backend, frontend, shared library and infrastructure repository may all be parts of one product.\n\nThe family describes that structure and, importantly, gives the agent routing information.\n\nIf a decision belongs to the shared library, it gets recorded there.\n\nIf it applies to the whole product, it belongs higher in the family.\n\nThe other repositories cite it instead of copying it.\n\nThat sounds like a small rule, but it avoids one of the ugliest problems in multi-repository documentation:\n\nfive slightly different copies of the same decision.\n\nThe reasoning has one owner.\n\nEverything else can point to it.\n\nFamilies can nest, so the same idea still works for a suite containing a cluster containing another project.\n\nNot every relationship means two repositories belong to the same system.\n\nAny Keep the Why entry can cite an entry in any other repository.\n\nThose repositories are **friends**.\n\nNothing is routed between them.\n\nNothing is merged.\n\nThey simply know about each other because their reasoning crossed paths.\n\nA friend may be one repository or an entire family.\n\nThe dashboard follows those references and shows the relevant entries on both sides.\n\nThat is why the graph around Keep the Why contains projects that were never configured as part of Keep the Why itself.\n\nThey are there because the data says they are related.\n\nThis is the part I find most interesting.\n\nAn entry can cite an earlier entry with `See`, or say that another entry superseded it.\n\nOnce several of those links line up, they form a chain:\n\n```\nincident\n   ↓\nconstraint discovered\n   ↓\narchitecture decision\n   ↓\nlater workaround\n   ↓\nreplacement\n```\n\nKeep the Why calls such a chain a **thought**.\n\nNobody writes a thought.\n\nThere is no `thoughts.md`.\n\nThe individual decisions were recorded when they happened. Their references are enough for the chain to emerge later.\n\nAnd importantly, a `See` link does not claim formal causality.\n\nIt says these pieces of rationale are related — often that one followed from the other, but not necessarily.\n\nSo a thought is not a proof.\n\nIt is a trail through the project's recorded reasoning.\n\n[Open **Thoughts** in the dashboard](https://keepthewhy.com/dashboard/live/#thoughts) and you can read one from beginning to end, with every entry in full, even when the chain crosses repository boundaries.\n\nThere is an important limitation here.\n\nThere is no global Keep the Why index.\n\nNo service knows every repository that has ever cited yours.\n\nFrom one project, the dashboard can see what that project points to.\n\nIts friends form the first neighbourhood.\n\nClick one and you can walk there, making it the new centre. The path you walked remains visible, so you can move back through the reasoning the same way you came.\n\nThoughts can go further.\n\nIf a chain continues into another repository, the dashboard says so. Ask it to continue and it loads exactly the repositories needed to follow that chain, hop by hop.\n\nWhat it does **not** do is crawl every project reachable from every project.\n\nThat is intentional.\n\nEach repository remains responsible for publishing its own state.\n\nThere is no central graph to submit your project's reasoning to.\n\nThe web exists because projects link to one another, not because a platform owns the web.\n\nThat also means there are things it cannot know.\n\nIf some repository elsewhere cites the newest entry in your chain, but you have never loaded that repository, there is no magic global backlink index that can tell you.\n\nI prefer that limitation to needing one.\n\nAt first I built the dashboard mostly because I wanted a quick way to understand what was already in `context/`.\n\nThen the references made new questions possible.\n\nOne is:\n\n**Which chains of reasoning started from something nobody ever confirmed?**\n\nEvery entry carries an evidence level.\n\nIf the first step of a thought is only `inferred` or `unknown`, every later decision may still be perfectly reasonable — but the chain started from an unconfirmed reason.\n\nThe Thoughts view can now surface those origins.\n\nAnother question is:\n\n**What later reasoning is connected to something we no longer trust?**\n\nSuppose an old assumption becomes `needs-review`.\n\nThe interesting part is not only that one entry.\n\nWhat came after it?\n\nWhich later decisions link back to it?\n\nDo those relationships cross into another repository?\n\nThe dashboard can show the later entries linked after that point and the projects they live in.\n\nIt still does not claim those decisions are wrong.\n\nA link records a relationship, not a theorem.\n\nBut it tells a human where to look.\n\nThere are other shapes hiding in the same data:\n\nplaces where many thoughts start;\n\nentries several thoughts pass through;\n\nchains that evolved over months;\n\ndecisions that were superseded but are still being cited.\n\nNone required another documentation process.\n\nThey became visible because the original reasoning was recorded once, with identity and relationships.\n\nThis distinction is important.\n\nKeep the Why does not ask developers to maintain a graph.\n\nThe actual workflow is much more boring.\n\nYou work with a coding agent.\n\nDuring that work a real reason surfaces:\n\nan architectural decision,\n\nan alternative that lost,\n\na workaround whose purpose is not visible from the code,\n\na production constraint,\n\nan attempted change that gets abandoned.\n\nThe agent records it in `context/`.\n\nGit versions it with the code.\n\nA later session reads it before repeating the same discussion.\n\nThat is the product.\n\nThe dashboard is only a lens over the traces this process leaves behind.\n\nAnd that is probably why I like the graph now more than I expected to.\n\nI originally considered the dashboard almost secondary.\n\nThe value was in the agent using the reasoning.\n\nIt still is.\n\nBut the dashboard makes something visible in twenty seconds that is harder to explain in twenty paragraphs:\n\na project is not just a collection of files.\n\nIt is the result of a long sequence of decisions.\n\nAnd once those decisions keep their reasons and can refer to one another, you can actually see that sequence.\n\nEverything behind the page remains plain Markdown in `context/`, versioned by Git beside the code.\n\nThe dashboard only reads it.\n\n```\npip install keep-the-why-dashboard\nktw-dashboard\n```\n\nOr export the whole view as a static page and publish it with the project's documentation.\n\nNo Keep the Why account.\n\nNo graph database.\n\nNo central memory service.\n\nNo new source of truth.\n\nJust the reasoning the repository already carried — connected strongly enough that you can finally walk through it.\n\n**Keep a Changelog records what changed.**\n\n**Keep the Why preserves why it changed.**\n\nAnd now you can see how those reasons connect.\n\n[Keep the Why](https://keepthewhy.com/) · [Live dashboard](https://keepthewhy.com/dashboard/live/#graph) · [Thoughts](https://keepthewhy.com/dashboard/live/#thoughts) · [Dashboard explained](https://keepthewhy.com/dashboard/#family-friends-thoughts) · [GitHub](https://github.com/oliver-zehentleitner/keep-the-why)\n\nI hope you found this informative and useful.\n\nFollow me on [GitHub](https://github.com/oliver-zehentleitner), [Bluesky](https://bsky.app/profile/o-zehentleitner.bsky.social), [Mastodon](https://burningboard.net/@oliverzehentleitner), [X](https://x.com/unicorn_oz), and [LinkedIn](https://www.linkedin.com/in/oliver-zehentleitner/), or join [Telegram](https://t.me/unicorndevs) for updates on my latest publications. Constructive feedback is always appreciated.\n\nThank you for reading, and happy coding! ¯\\_(ツ)_/¯", "url": "https://wpnews.pro/news/the-reasoning-behind-a-codebase-as-a-web-you-can-walk", "canonical_source": "https://dev.to/oliverzehentleitner/the-reasoning-behind-a-codebase-as-a-web-you-can-walk-a7j", "published_at": "2026-09-30 06:10:54+00:00", "updated_at": "2026-09-30 06:16:37.342832+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Keep the Why", "Git", "UNICORN Binance Suite", "repo-native project memory", "Oliver Zehentleitner"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/the-reasoning-behind-a-codebase-as-a-web-you-can-walk", "markdown": "https://wpnews.pro/news/the-reasoning-behind-a-codebase-as-a-web-you-can-walk.md", "text": "https://wpnews.pro/news/the-reasoning-behind-a-codebase-as-a-web-you-can-walk.txt", "jsonld": "https://wpnews.pro/news/the-reasoning-behind-a-codebase-as-a-web-you-can-walk.jsonld"}}