keep-the-why

The three packages — keep-the-why on npm, keep-the-why-lint and keep-the-why-dashboard on PyPI — go out through trusted publishing only: each registry trusts this repository's release workflow, no token exists that could publish from anywhere else.

Keep the Why

Keep a Changelog records what changed. Keep the Why preserves why it changed.

Keep the Why is the why layer of repo-native project memory: your repository already holds what the project is, how it works and what changed; this is the agent skill, and the file convention it maintains, that preserve the one thing it was missing — the reasoning behind a codebase — architecture decisions, rejected alternatives, workarounds, incident learnings, operational constraints that the code alone can't explain — in the repo. That memory is plain Markdown in context/, committed with the code, so Git already provides the storage, the history and the distribution: it travels with every clone, branch and fork, and a pull request shows the reasoning diff beside the code diff. It captures that reasoning as a byproduct of working with your agent, so every later session can use it. Your agent, and every other agent that works in the repository, understands not just the code but everything around it: why it is the way it is, what was tried and rejected, which constraints the source doesn't show. So does the next person. Onboarding gets faster, legacy projects become tractable again. It works continuously as you develop, where the reasoning comes for free.

It pays off most where re-debated decisions, forgotten workarounds and departed knowledge cost the most: maintainers and teams running coding agents on long-lived codebases. Starting on an existing repository works too, within limits — history, issues and code give back only part of the why, a maintainer has to fill in the rest, and that takes real effort. It is never too late to begin, though.

The payoff, made concrete: a new hire, or an AI agent that's never touched the codebase before, doesn't have to track down whoever wrote the original code — and doesn't just repeat what was already tried and rejected. That part is measured: twenty fresh agent 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). Every wrong turn the agent doesn't take is work nobody has to do and undo — it saves time, money in tokens, and nerves. The same context makes changes safer across the board — no more guessing whether an odd piece of code is a Chesterton's Fence worth keeping or just cruft nobody got around to removing — turning a legacy project back into something tractable instead of a black box only one person ever understood. "Ask Bob" stops being the fallback.

Documentation is normally extra work that happens after the code is done — reload the reasoning from memory, write it down again, file it somewhere else: a wiki, an ADR, a PR description nobody reopens. That's exactly why it so often doesn't happen. When an agent is already how you work — deciding, weighing trade-offs, explaining itself in the same conversation that produces the change — the reasoning shows up for free, as a byproduct of that conversation, not separate effort. Keep the Why's actual job is narrower than it sounds: don't let that reasoning get thrown away.

Tested with: Claude Code, opencode, Pi, Hermes, and more — see the full eval suite and the agent × model matrix for what's actually been run against what, and how.

Installable with one command on Claude Code, Codex, GitHub Copilot, Cursor, OpenClaw, Hermes Agent, Cline, OpenCode, Pi, Antigravity and 60+ more agents.

Website: https://keepthewhy.com · [llms.txt](https://keepthe