{"slug": "the-globe-following-your-reasoning-into-other-people-s-repositories", "title": "The Globe: Following Your Reasoning Into Other People's Repositories", "summary": "The open-source project Keep the Why, which stores project reasoning as plain Markdown in a repository's context/ directory, has introduced a feature called the Globe that follows explicit reasoning links across repositories one wave at a time. Users select how many hops to follow, up to ten, and the dashboard pauses before each wave to show which repositories and how many files it will fetch, with no background crawler and nothing persisted between visits. The project's public graph remains small, and the Globe is described as a demonstration of the model rather than a map of a mature ecosystem.", "body_md": "**Keep the Why records why a codebase is the way it is. Decisions can cite decisions in other repositories. The Globe follows those citations outward, one wave at a time, without turning project memory into a centralized service.**\n\nA decision rarely stands alone.\n\n**We retry three times** may exist because **the payment provider counts every attempt against our error budget**.\n\n**We pinned this WebSocket library** may exist because **the upstream fix has not been released yet**.\n\nAnd sometimes the reasoning behind your decision does not live in your repository at all.\n\nIt lives in a sibling package.\n\nAn upstream library.\n\nAnother service maintained by your team.\n\nOr a project maintained by someone you have never met.\n\nThat became increasingly interesting while working on [Keep the Why](https://keepthewhy.com/), the [open-source project on GitHub](https://github.com/oliver-zehentleitner/keep-the-why).\n\nKeep the Why stores project reasoning as plain Markdown in the repository's `context/` directory. Decisions, rejected alternatives, constraints, workarounds and incident learnings stay next to the code they explain.\n\nAn entry can also reference another entry.\n\nAnd that other entry can live in another repository.\n\nOnce that existed, something slightly unexpected happened.\n\nThe project memory stopped looking like a collection of documents.\n\nIt started looking like a graph.\n\nThe Keep the Why [dashboard](https://keepthewhy.com/dashboard/) has visualized these relations for a while.\n\nLoad a project and you can see its entries, their relations, parent and child repositories, and references to rationale elsewhere. The [live graph](https://keepthewhy.com/dashboard/live/#graph) shows this directly on Keep the Why's own project memory.\n\nOriginally, that graph had a natural boundary: the project you opened.\n\nExternal references appeared at the edge.\n\nBut if a decision says:\n\n```\nSee: https://github.com/example/upstream#ktw:some-decision-id\n```\n\nthen the interesting question is obvious:\n\nWhat happens if we follow it?\n\nAnd then follow the references from that repository?\n\nAnd the references from those repositories?\n\nThat is what the **Globe** does.\n\n**The Globe follows explicit reasoning links across repositories. Click the screenshot to open the live dashboard.**\n\nThe public graph is still small. We are just starting to connect projects, so right now the Globe is more a demonstration of the model than a map of a mature ecosystem.\n\nThat is also why the registry exists: to give this network a place to start growing.\n\nThe Globe is not a new database or another memory backend.\n\nIt is the same project reasoning, with fewer artificial boundaries.\n\nThe Globe starts with the project you already loaded.\n\nFrom there you decide how far it should follow external references:\n\nSelect the number of hops you want to follow, then press \"go\" to start loading the next wave.\n\n**Hop 1** loads repositories directly referenced by the current project.\n\n**Hop 2** follows references found inside those repositories.\n\nThe process continues outward, up to ten hops.\n\nEach hop is a separate wave.\n\nThat matters because the next wave cannot be known in advance.\n\nTo know what repository B references, the browser first has to load repository B.\n\nSo before every wave, the Globe pauses and shows what it is about to fetch: which repositories were discovered and how many files that represents.\n\nYou can continue or stop there.\n\nThere is no background crawler walking the internet.\n\nThere is also no reason to load ten hops just because ten are possible.\n\nOften one or two are enough to understand where a decision came from.\n\nAnd **off really means off**.\n\nWith external loading disabled, the dashboard stays inside the project you opened.\n\n`Clear` removes what the Globe loaded and leaves your own project family, friends and navigation path intact.\n\nReload the page and the external graph is gone.\n\nNothing is persisted between visits.\n\nRepositories are not always independent units.\n\nA project may be a suite with several packages, or a parent repository may explicitly declare child projects.\n\nKeep the Why already supports those relationships through `parent` and `children`, defined as part of the [project format](https://keepthewhy.com/specification/).\n\nThe Globe keeps them.\n\nIf an external reference reaches one member of a declared project family, the family arrives together and remains connected according to the repositories' own metadata.\n\nThat is important because otherwise the graph would create a misleading picture.\n\nA package that belongs to a larger project should not suddenly look like an isolated external dependency just because that happened to be the repository containing the cited decision.\n\nYou can also click any loaded project and make it the new centre.\n\nThe route you followed remains visible.\n\nSo if you started in repository A, followed a decision into B, then discovered C through B, you can still see how you got there.\n\nThe graph is not only showing what is connected.\n\nIt is showing how you walked through the reasoning.\n\nThis was the part I cared about most.\n\nI did not want the graph to turn Keep the Why into the kind of infrastructure it was originally designed to avoid.\n\nThere is no central service resolving these links.\n\nThere is no account.\n\nNo graph database.\n\nNo daemon crawling repositories.\n\nNo API storing everybody's project memory.\n\nEach repository that publishes a dashboard export already declares where that export lives in its `.keep-the-why` file.\n\nThe export can simply be a static `state.json` hosted on GitHub Pages or another static host.\n\nWhen the Globe finds another repository, the browser reads its `.keep-the-why` at `HEAD`, finds the `dashboard-state` location, fetches the export and draws what it contains.\n\nThe dashboard server never fetches the other repository.\n\nYour browser does.\n\nThat distinction sounds small, but it keeps the architecture pleasantly boring.\n\nThe repository remains authoritative.\n\nThe published export is only a view of that repository.\n\nAnd the graph exists because the repositories link to each other, not because a central system reconstructed the relationships afterwards.\n\nFollowing repositories also exposed a very practical problem.\n\nKeep the Why entries contain text.\n\nSometimes quite a lot of it.\n\nBut the graph does not need the full explanation of every decision just to know that entry A references entry B.\n\nLoading all prose for every repository in every wave would waste bandwidth quickly.\n\nSo the dashboard export was split.\n\n`state.json` contains the structure:\n\n```\nprojects\ntopics\nentries\nfields\nrelations\nlinks\n```\n\nThe actual entry bodies live beside it in:\n\n```\nstate.body.json\n```\n\nThose bodies are fetched only when you open an entry.\n\nFor a prose-heavy project, that reduces what a graph wave needs to load to roughly a third of the previous size.\n\nIt is a small architectural change with a useful property:\n\nThe farther you explore, the less unnecessary text you move around.\n\nFollowing references works well, but it has a blind spot.\n\nYou can discover what your project cites.\n\nYou can discover what those projects cite.\n\nBut you cannot discover a repository that nothing in your current graph points to.\n\nMore importantly, you cannot discover who cites **you**.\n\nThat information exists somewhere out there, but there is no link you can follow backwards to find it.\n\nThis is where the [Keep the Why Registry](https://keepthewhy.com/registry/) came from.\n\nNot as a replacement for the distributed graph.\n\nAs a discovery mechanism for the one thing the graph itself cannot do.\n\nThe registry is a text file in the Keep the Why repository.\n\nOne canonical repository URL per line.\n\nThat is basically it.\n\nTo add a project, you open a pull request and add its repository URL.\n\nA workflow then reads the repository's `.keep-the-why`, follows its `dashboard-state` declaration, loads the published export and verifies that the export actually identifies the repository being registered.\n\nThe registry therefore stores where to start looking.\n\nIt does not store your project memory.\n\nIt does not copy your entries.\n\nAnd it does not even need to permanently store the location of your export.\n\nIf you move the published dashboard state later, the next registry build follows the repository configuration again and finds the new location.\n\nProject families work here too.\n\nRegister the root project and its declared children arrive through the relationships already stored in those repositories.\n\nIf an export temporarily stops responding, it is not deleted immediately either.\n\nIt remains listed and marked as unavailable for a month before it is dropped.\n\nRepositories disappear for temporary reasons.\n\nInfrastructure should not turn one bad day into permanent metadata.\n\nThis part matters.\n\nKeep the Why works without the registry.\n\nThe dashboard works without it.\n\nThe Globe works without it.\n\nCross-repository references work without it.\n\nNothing requires a project to join a central list.\n\nThe registry only solves discovery.\n\nTick `registry` in the Globe and it becomes another wave you can load.\n\nSuddenly you are not limited to projects already reachable from your own references.\n\nYou can see the first published Keep the Why projects joining the graph and then explore their reasoning exactly the same way.\n\nOnce loaded, there is no special registry graph.\n\nThey are just repositories again.\n\nThat was the design I wanted.\n\nCentralize discovery where central discovery is useful.\n\nDo not centralize the project memory itself.\n\nA graph can become misleading very quickly if it starts guessing.\n\nSo the Globe does not infer relationships from prose.\n\nIt does not connect two repositories because they mention the same library.\n\nIt does not connect entries because they use similar words.\n\nIt does not create a relation because two projects share a topic name.\n\nA connection exists when someone recorded one.\n\nFor example through `See` or `Superseded by`.\n\nIf two projects obviously belong together but no explicit relation exists in their project memory, they appear as separate islands.\n\nI prefer that.\n\nThe graph may know less, but what it shows has provenance.\n\nIt came from the project records themselves.\n\nThe Globe looks nice.\n\nBut the visualization is not really the part I find interesting.\n\nThe useful part is what happens when reasoning crosses repository boundaries without changing ownership.\n\nRepository A remains authoritative for its decisions.\n\nRepository B remains authoritative for its decisions.\n\nNeither needs to copy the other's rationale.\n\nThey can simply point at each other.\n\nGit already distributes the files.\n\nStatic hosting distributes the read-only views.\n\nThe browser follows the references.\n\nThe graph appears as a consequence.\n\nNobody has to maintain one global knowledge graph containing everybody's project history.\n\nAnd nobody owns the web of reasoning that emerges between repositories.\n\nThere is another consequence of following these links.\n\nA decision is not automatically trustworthy forever just because somebody wrote it down.\n\nKeep the Why already records things such as status, evidence and supersession.\n\nThe Globe carries that information across repository boundaries.\n\nSo if a chain of reasoning starts from an unconfirmed entry, that remains visible.\n\nIf something in the chain is still open, that remains visible.\n\nIf a decision gets superseded, that remains visible too.\n\nThis becomes particularly useful when the decision is no longer in your own repository.\n\nImagine your local workaround exists because of an upstream constraint.\n\nLater, the upstream project supersedes that constraint.\n\nYour own code does not magically become wrong.\n\nBut the reasoning chain leading to it has changed.\n\nThat is exactly the kind of thing worth looking at again.\n\nNot because a graph decided your code is stale.\n\nBecause the evidence your decision depended on changed.\n\nWhen I started Keep the Why, the idea was intentionally narrow:\n\nKeep the reasoning that is expensive to reconstruct close to the code.\n\nPlain Markdown.\n\nGit.\n\nA small convention.\n\nAn agent skill that writes and reads it.\n\nThe repository remains the source of truth.\n\nCross-repository links did not change that model.\n\nThey made the consequence of it more visible.\n\nOnce repositories can cite reasoning in other repositories, project memory no longer has to mean isolated project memory.\n\nIt can stay local, independently owned and Git-native while still participating in something larger.\n\nNo shared database is required.\n\nNo global account is required.\n\nNo project has to hand its memory to another service.\n\nThe files were already there.\n\nThe links were already there.\n\nThe Globe just follows them.\n\nStart with Keep the Why itself:\n\nSelect one or two hops, press Go, and watch the graph expand one wave at a time.\n\nThen load the registry and explore the first projects joining the graph.\n\nThe [registry](https://keepthewhy.com/registry/) explains how discovery works and how to add a project.\n\nThe [dashboard documentation](https://keepthewhy.com/dashboard/) covers publishing an export and the rest of the graph features.\n\nThe complete format is documented in the [Keep the Why specification](https://keepthewhy.com/specification/).\n\nIf your project already uses Keep the Why and publishes a dashboard, adding it to the registry is one line in a pull request.\n\nIf it does not use Keep the Why yet, the [installation guide](https://keepthewhy.com/installation/) covers all supported methods. The recommended Skills CLI installation currently starts with:\n\n```\nnpx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why\n```\n\nThen tell your coding agent to initialize Keep the Why in the project.\n\nThe reasoning graph is not something you have to maintain separately.\n\nIt is a byproduct of projects remembering why they became what they are.\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-globe-following-your-reasoning-into-other-people-s-repositories", "canonical_source": "https://dev.to/oliverzehentleitner/the-globe-following-your-reasoning-into-other-peoples-repositories-1cfo", "published_at": "2026-10-02 08:22:03+00:00", "updated_at": "2026-10-02 08:38:46.295910+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["Keep the Why", "GitHub", "Oliver Zehentleitner"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/the-globe-following-your-reasoning-into-other-people-s-repositories", "markdown": "https://wpnews.pro/news/the-globe-following-your-reasoning-into-other-people-s-repositories.md", "text": "https://wpnews.pro/news/the-globe-following-your-reasoning-into-other-people-s-repositories.txt", "jsonld": "https://wpnews.pro/news/the-globe-following-your-reasoning-into-other-people-s-repositories.jsonld"}}