FAQ
Is this affiliated with Keep a Changelog? No. The name is a deliberate homage to keepachangelog.com — same naming pattern, same spirit of "a lightweight open convention, not a platform" — but there's no official relationship and no shared code or governance.
Does this replace the README, docs, CONTRIBUTING.md, tests, or a changelog? No — see the README's "Where this fits" table (on the README page). Keep the Why only covers the "why" layer. Each of the others answers a different question and none of them is optional just because you have the others.
Is there a Keep the Why CLI, or an init command?
No. The skill is text — SKILL.md and its reference files — read by your coding agent; there is nothing to compile, start or keep running. Installing is one command (npx skills add …, see Installation), and "initialize" is a sentence you say to the agent once per project. The only executables in the project are optional and separate: keep-the-why-lint, a structural checker for context/ (locally and in CI), and keep-the-why-dashboard, a read-only viewer. Nothing runs in the background, nothing phones home.
Does it work in a mono repo, or across several repositories?
Yes. A .keep-the-why marks a project, and the project is the tree under the nearest one walking up from where the agent works — the way Git finds .git. One file at the root of a mono repo gives the whole tree one context/; one file per sub-project gives each its own, isolated from the root's, with its own id and a root field naming its path. Several repositories are several projects, and they can form a family: one parent — a suite's meta repository, the root of a mono repo — whose .keep-the-why lists its children with a one-line scope each, and children that name the parent. That list is the routing: an entry about a sibling's subject goes to the sibling, a family-wide one to the parent, and the agent writes there when that project is checked out next to this one, under that project's own confirmation setting. Knowledge lives once and is cited from everywhere else with a See line. The layouts are in the repository structure reference, the fields in the specification (§3.3).
What is a family, and when do I need one?
When several projects form one product and some of the why applies to all of them — a release order, a shared constraint, a decision every package follows. Then that knowledge belongs in one place, the parent, and the children cite it instead of repeating it. The parent's .keep-the-why lists its children with one scope line each, every child names its parent, and the agent routes an entry by those scope lines (Setup, "Family"). A single repository needs no family; neither do two projects that merely refer to each other — that is a citation, see the next question. In the dashboard, the family scope shows the whole tree as one.
Can projects outside a family refer to each other?
Yes. Any entry can cite an entry in any other repository with a See line — the other repository's canonical, the entry's Id, the date — and a replaced decision can name its successor there with Superseded by. Nothing is routed or shared between the two; it is a citation, the way a paper cites another. Typical cases: a library you depend on, the upstream project you forked, a concept document your decisions build on. The dashboard calls such repositories friends: it loads them with the graph (from a checkout on the machine, else from their published export), draws the entries that connect the two, and lets you walk there, one hop at a time. A friend that is part of a family comes as the whole family.
What is a thought?
A chain of linked entries: each one cites the one before (See) or replaced it (Superseded by), across repositories wherever they cite each other. Nobody writes a thought; it follows from the citations already recorded. A link says two entries are related — often that one follows from the other, not always — so a thought shows how decisions connect, not a proven argument. One in this repository runs: public mode reads published exports → the page asks other hosts only for what a person opens → a See into another repository is resolved when it is shown → friends. A chain made only of Superseded by is an evolution — one decision, replaced step by step. The dashboard lists the thoughts beside the graph, shows one whole, and points out where a chain starts from an entry whose Evidence is only inferred or unknown, or passes a step that is in question — with the entries linked after it, which are the ones to check. The thoughts across Keep the Why and its friends →
Does the context/ folder have to be visible in the repository?
Yes, and that is the point: repo-native means available where the work happens, the way README.md and docs/ are — nobody hides those either. The folder is committed, so a reviewer sees the why in the same pull request as the code, a collaborator gets it with the clone, and any agent finds it without an account or a service. Where it lives is your choice at setup — context/ by default, or an existing decision folder such as docs/decisions/ — and .keep-the-why records it.
What does Git do for context/ — permissions, distribution, review, forks, blame?
Everything it does for the code, because context/ is files in the repository. Who may write the why is who may write the code: branch protection, required reviews, CODEOWNERS on context/ if you want a named owner — no second access list, and the skill never commits on its own. git clone ships the whole why to every checkout, CI runner and agent, offline, at the commit it is working on. A reason enters the record in the same pull request as the change it explains; the linter checks the shape, review checks the truth. A fork carries the why with it and keeps writing its own — citations still point at the published repository (canonical, taken from upstream in a fork checkout), so a contributor's branch brings the reasoning back with the code, and the dashboard marks a fork checkout as fork of that repository. Two branches that add entries merge like code; the index's fixed 0–9, A–Z heading skeleton keeps parallel additions apart. And git blame on an entry says who recorded it, git log when its Status changed, git log -S <Id> where it is cited — the audit trail the dashboard's Authors and Timeline views read. One thing blame does not show: who decided — it shows who committed, which may be the agent's account under a person's instruction. Landing page: Git does the rest · Dashboard
How does the agent find the right entry without reading everything?
Through context/index.md: one line per topic file under a fixed heading skeleton. The agent reads the index first and opens only the topic file the task touches — the whole of context/ is never loaded at once. The index skeleton (all thirty-six ## 0–## 9, ## A–## Z headings, always present) is also what keeps two branches from colliding when both add a topic — the mechanism is called deterministic write areas, explained in One Index, Many Writers.
Does it have similarity search, like a vector memory?
No. Retrieval is the index and the topic name: context/index.md names every topic file in one line, the agent reads that page and opens the topic the task touches, and inside a topic file the entries are headings a reader — human or agent — scans. Nothing is embedded, nothing is ranked by similarity; git grep works because it is text. That is a choice, not a gap: entries are synthesized from the conversation rather than stored verbatim, written to be read in full, so a topic file is a few screens and "have we been here before" is answered by the topic's name. The limit is easy to name: a project whose context/ grows to hundreds of topic files needs more than one line per file, and the index would be the thing to fix. Nothing prevents a search tool from indexing context/ — it is Markdown — but the skill does not need one and does not ship one.
My coding agent keeps suggesting something we already tried and rejected. How do I stop that?
Write the rejection down where the next session will look before it changes the code, with the reason and what went wrong. A fresh session has no memory of the last one, and the code only shows what was kept, not what was ruled out. That is what context/ is for: an entry records the decision, the rejected alternative and why it lost, and the agent reads the matching topic before touching that part of the code. Measured once, on the core claim: twenty fresh sessions, the same codebase, the same request to simplify a retry wrapper. Without a recorded reason, seven of ten offered the already-rejected simplification again; with one context/ entry, all ten found it and none did (the experiment, transcripts and grades). It is guidance the agent reads, not a lock: nothing blocks a commit that repeats a rejected approach (see below).
My CLAUDE.md / AGENTS.md keeps growing. Where should project decisions go instead?
Keep the instruction file for instructions: how to build, test and work in this repository. The reasons behind the code don't belong there. An instruction file is read in full at the start of every session, so every decision added to it is loaded every time, whether the task touches it or not, and a long file is hard to keep current. In Keep the Why the decisions live in context/, one Markdown file per topic, and context/index.md lists every topic in one line. The agent reads the index and opens only the topic the task touches. AGENTS.md stays a lean entry point that points there (repository structure).
Do I need a vector database or an MCP memory server for project memory?
Not for the reasoning behind the code. Session and vector memory tools remember what happened in conversations and recall it by similarity. Keep the Why records why the code is the way it is, as plain Markdown in the repository, found by its index. They are different layers and can run side by side; one memory server, ai-memory, documents how to run it next to a Keep the Why context/.
| Session or vector memory (memory service, MCP memory server) | One large instruction file (CLAUDE.md, AGENTS.md, rules files) |
Keep the Why | |
|---|---|---|---|
| What it holds | what happened in sessions; facts recalled about the user and the work | instructions: how to work in this repository | why the code is the way it is: decisions, rejected alternatives, workarounds, constraints |
| Where it lives | the tool's store, usually per user or per machine | the repository | the repository, in context/ |
| Infrastructure | a server or service, often an embedding model | none | none: Markdown, plus an optional linter and viewer |
| Shared with the team and reviewed | through the tool, if it supports that | in the pull request, as a diff | in the pull request, as a diff beside the code it explains |
| How the agent finds the relevant part | similarity search | reads the whole file every session | reads a one-line-per-topic index, then opens the topic the task touches |
How is this different from an ADR (Architecture Decision Record)? ADRs are typically human-authored, written at a discrete decision point, one file per decision, and treated as frozen once accepted. Side by side:
| ADR | Keep the Why | |
|---|---|---|
| Written by | a person, deliberately | the agent, as a byproduct of the session |
| When | at a decision point, after the fact | while the reasoning is spoken, including changes that never happened |
| Unit | one file per decision | one topic file, many entries |
| Once accepted | frozen; a new ADR supersedes it | living: updated in place, marked superseded |
| Scope | the few large decisions a year | those, plus the many small ones: workarounds, constraints, rejected alternatives |
| Reader | people | people and agents, through the index |
ADRs stay the right tool for the few large, discrete decisions; a project with an ADR folder keeps it, and Keep the Why fills the layer below it. Their biggest weakness in practice was never the format — it's that writing one depends entirely on someone remembering to do it, under exactly the deadline pressure that makes people skip it first. Keep the Why is continuous and agent-authored from the conversation itself, so capturing the rationale isn't a separate disciplined act anymore — it's a byproduct of the conversation the agent is already having with you. Organized by topic rather than by decision, and entries are living — updated and marked superseded rather than replaced by a new file. See Methodology for the full reasoning.
How is this different from other tools or skills that capture agent rationale? Several solve adjacent parts of this problem well. Rather than a name-by-name comparison that's incomplete the moment it's written and stale soon after, see the README's "Related work" section and Philosophy for how Keep the Why draws its own boundaries: continuous capture, retrospective recovery, and knowledge-transfer interviews, plus ongoing maintenance of what's already there — organized as topic-indexed living docs rather than a shadow tree or one-file-per-decision, with no required external service. A dated comparison with names — Claude Code auto memory, MemoryCustodian, AgentsRoom, as of September 2026 — is on the blog, where a snapshot can stay a snapshot: Keep the Why vs. Claude Code Auto Memory vs. MemoryCustodian vs. AgentsRoom.
Does this require a database, MCP server, or network access? No. Everything is plain Markdown files committed to the repository.
Could this run as a CI/CD check instead of during development?
No — by the time code is pushed and CI runs, the reasoning that mattered (what was tried, what was rejected, why a workaround exists) has usually already happened and isn't recoverable from the diff alone. CI can check that a context/ entry exists or is well-formed, but it can't invent rationale that was never captured. That's why this runs live, in the conversation with the coder or agent actually making the decision — continuous capture as it happens, or a retrospective/interview session that reconstructs from git history and people — not as a pipeline step reacting to already-finished work. See Philosophy, "No daemon."
Does it block a commit that repeats a rejected approach?
No, and nothing in it hooks into Git. The linter checks the form of what was written — required fields, valid values, a consistent index — never the content of a decision. Prevention happens earlier, where it works: the skill reads context/ inside the agent session, before the change is made, so the agent finds the entry, says so, and declines or asks — measured on one such change, 7 of 10 fresh sessions proposed the rejected simplification without the entry and 0 of 10 with it (the experiment). A hook that refused the commit afterwards would also freeze decisions: entries are living, and Status: superseded exists precisely so a decision can be revisited with a reason.
Does it guarantee nothing gets lost?
No — see "What this is not" in the README and in SKILL.md. Quality depends on what actually gets captured. This reduces the problem, it doesn't eliminate it.
Does the quality of the entries depend on the model?
Yes. The quality of the entries depends on the model running the skill: the format and the linter keep the structure, the model decides what it recognizes as a reason and how well it writes it down. Whether a reason is noticed, whether a rejected alternative is recorded, whether an unknown reason is marked unknown instead of guessed — that is the model's work; a more capable model does it more reliably. Which agents and models have been measured, and how: the agent & model matrix.
Do I have to tell the agent to write things down?
No. You install it with one command, say "set up Keep the Why here" once per project and answer the setup — "defaults" is a complete answer. After that there is nothing to remember: with the default capture-mode: proactive the agent notices rationale as it surfaces in normal work — a decision, a rejected alternative, a workaround, a change that was started and abandoned — and records it on its own; with the default capture-confirmation: confirm-when-unsure it writes when the reasoning is clear and asks a short question only when it is genuinely unsure. The defaults also write the project's start path, so every later session in that directory loads the skill by itself. Asking for a capture explicitly always works too, and explicit-only exists for whoever wants nothing but that — it is an option, not how the skill normally runs. The whole of it, step by step: Keep the Why is not another workflow.
Does the skill always interrupt me to ask before writing anything?
Configurable, project-wide, via capture-confirmation in .keep-the-why: automatic (never asks permission, just writes once evidence and proportionality already support it), confirm-always (asks before every write), or confirm-when-unsure (the default, and what the skill already did before this setting existed — writes directly when things are clear, asks only when genuinely unclear). None of these change whether the skill asks a substantive question about the facts themselves, which stays independent of this setting even in automatic mode. See Setup, "The confirmation model."
Does it link entries to a Jira/GitHub issue or post-mortem?
It can, via source-reference in .keep-the-why (project-wide, default never): always asks whether a related issue, ticket, PR, or post-mortem exists for every new entry; filtered: <criteria> asks only when your own free-text criteria match (e.g. only for incident-related topic files). Either way, asking isn't the same as requiring one — "no reference exists" is a complete answer, never invented to fill the field. This is separate from rule 2's Source field itself, which could already hold a reference, just wasn't actively asked for before this setting existed. See Setup, "The confirmation model."
Does this guarantee the skill activates automatically every session?
Yes — set up the way the wizard proposes, it is loaded in every session; that is the measured result on Claude Code and my own daily experience. What no skill can do is load itself: a skill package is instructions, and neither the open Agent Skills spec nor any agent tool gives a skill a way to load itself at session start. Loading is the agent's job. Keep the Why hands it over explicitly instead of pretending otherwise: the project init wizard asks how the project wants the skill loaded and has the current agent set up what its own platform offers — a project-scoped hook where there is one (Claude Code's SessionStart), and a "Keep the Why" section in the project's entry-point file that any agent reading it follows. Keep the Why deliberately doesn't hardcode one vendor's mechanism into its own instructions, because that would present something tool-specific as universal. With a start path in place the skill is in the session before the first request: Claude Code loads it in every measured session (hook 10/10 on sessions that had gone 0/10 without one, entry-point section 3/3 against 0/3 without it), Codex CLI, opencode and Cline by the section (3/3 each), Hermes Agent by a live run — references/autostart.md lists per tool what is verified how, and context/compatibility.md has the reasoning. A tool that isn't listed hasn't been measured, not failed; a pull request with a verified example is welcome any time. Asking directly ("initialize/check keep-the-why") works on every tool regardless.
Can a project stay on one version of the skill, even if a developer has a different one installed globally?
Yes. Check the skill's folder from a release into the repository and pin it in .keep-the-why (pinned-version and pinned-path). Whichever copy of the skill loads first, the one installed for the user or the project's own, reads the pin before anything else. If its version is a different one, it follows the pinned copy for the whole session. If the pinned copy is missing or does not match, it stops and asks instead of silently running another version. How to set it up and update it: Installation — Pinning a project to one skill version.
What if my project already has a documentation structure I like? Keep the Why is meant to adapt to what exists, not replace a working structure with a fixed template. See Repository structure, "Retrofitting an existing project."
Does it work on GitLab, Codeberg, Bitbucket or a self-hosted forge?
The format and the skill need nothing from the host: context/ is Markdown in the repository and travels with Git wherever the repository lives. What touches the host is optional: the linter in CI, the dashboard published on the project's site, and the registry. Two hosts are tested end to end:
- GitHub: this project and the other GitHub repositories in the registry.
- GitLab: keep-the-why-demo, with the linter in GitLab CI, the dashboard on GitLab Pages and a listing in the registry.
The setup for both, including the GitLab settings that are yours to make (account verification for CI, Pages visibility), is in CI, dashboard and registry setup. The dashboard also knows the link forms of Codeberg, Gitea, Forgejo and Bitbucket, but those haven't been tested end to end. If something doesn't work on your host, please open an issue. A report from a host we haven't tried yet is very welcome.
Is this specific to Claude Code?
No. The skill format (SKILL.md with YAML frontmatter) is an open standard supported by Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Antigravity, Amp, Cline, Goose, Roo Code, OpenCode, Trae, Factory, JetBrains Junie, Warp, and others — see Installation for the current directory-path table. The structure it produces (a section in AGENTS.md, context/, the .keep-the-why file; personal preferences outside the project in ~/.keep-the-why/) is plain Markdown and tool-agnostic by design, so it isn't locked to any of them even as the list of supported tools changes.
Does this work with DeepWiki?
Yes, in the sense that matters — DeepWiki doesn't need to "support" Keep the Why explicitly, because it already ingests and cites a repo's existing Markdown (confirmed by checking a real DeepWiki page: it cited a repo's README with line-number references). A populated context/ gives DeepWiki's analysis real rationale to cite instead of inferring everything from code. It won't necessarily preserve the Evidence/Status distinctions (confirmed/inferred/unknown, active/superseded/open/needs-review) in its own generated wiki, though, since that's a Keep the Why-specific convention it doesn't know about — see Installation.
Does this work with Obsidian?
Yes, and there is nothing to configure on either side. context/ is plain Markdown with standard relative links, so open the repository (or just context/) as a vault and Obsidian reads, searches, and edits the same files the agent writes — add .obsidian/ to .gitignore so the vault's workspace state stays out of the repository. The two don't compete: Obsidian is the interface, Keep the Why is the convention and the skill that fills it, and the repository stays the single copy — an edit made in Obsidian is an ordinary commit like any other. Two things to keep straight. The skill doesn't run in the background next to Obsidian; it runs inside the agent session, as the CI/CD entry above explains. And the graph view is less useful here than it looks: its nodes are files, and Keep the Why keeps entries as sections inside topic files rather than one note per decision, so the graph shows index.md and a dozen topic files, not how decisions relate. Search, backlinks, and side-by-side editing are where Obsidian earns its place. If you write links from inside Obsidian, turn off "Use [[Wikilinks]]" under Files & Links — wikilinks aren't standard Markdown, don't render on GitHub, and aren't what the agents reading the files expect.
Is there a UI for people who don't work in the terminal — product managers, designers?
The files are the UI. context/ is Markdown in the repository, so anyone who can open the repository reads it rendered in the browser on GitHub or GitLab — the same file the agent writes, with the same history, nothing to log into; this project's own context/ is published on this site the same way. There is a viewer, keep-the-why-dashboard, optional and read-only: the graph of topics, an entry with its Git history, the queues of what still waits for a person. What there is not, on purpose, is a place where reasoning is entered or held outside the repository — a UI that became that place would be the parallel system the project exists to avoid (Philosophy).