Keep the Why

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

Looking for the linter? The CI linter for Keep the Why projects is published under a different name: keep-the-why-lint — pip install keep-the-why-lint, command ktw-lint.

This package (keep-the-why) is a name reservation. Keep the Why itself is an agent skill and a Markdown convention, not a Python library — there's nothing to import. It ships as a SKILL.md package and installs through your agent's skill tooling (see Install below), so this distribution intentionally contains no runtime code. It exists so the name on PyPI points at the real project instead of at nothing.

Keep the Why is a repo-native convention and agent skill for preserving the reasoning behind a codebase — architecture decisions, rejected alternatives, workarounds, incident learnings, operational constraints that the code alone can't explain. It captures that reasoning as a byproduct of working with your agent — so it stops re-suggesting rejected approaches, gives better answers, speeds up onboarding, and makes legacy projects tractable again. It works continuously as you develop, or retrospectively on an existing repo.

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. No more guessing whether an odd piece of code is a Chesterton's Fence worth keeping or just cruft nobody got around to removing. "Ask Bob" stops being the fallback.

Tested with: Claude Code, opencode, Pi, and more, with different models — see the agent & model matrix for what's actually been run against what, and how.

Website: https://keepthewhy.com · llms.txt for AI agents/assistants looking up this project

Documentation: Installation · Setup · Repository structure · Linting · Evals · Philosophy

How it works

Keep the Why's agent skill is SKILL.md-based — an open, cross-agent format (Claude Code, Codex CLI, Gemini CLI, Cursor, and others). It operates in four modes:

1. Continuous capture — during normal development, the agent notices rationale worth keeping and records it alongside the code as it happens.
2. Retrospective recovery — pointed at an existing or legacy repository, the agent reconstructs what it can from git history, issues, and code, and is explicit about what it couldn't.
3. Knowledge-transfer interview — before a maintainer's knowledge becomes unavailable, the agent analyzes the codebase first, then asks targeted questions about exactly what the code couldn't explain — or just listens while they narrate freely and extracts the rationale from that.
4. Maintenance — existing rationale docs get kept current: contradictions resolved, superseded entries marked, oversized files split.

The captured knowledge lives in context/ as versioned Markdown, organized by topic. Every entry carries a Status (active | superseded | open | needs-review) and an Evidence level (confirmed | inferred | unknown) — so the next reader knows how far to trust it — plus the rejected alternative and the reason the chosen path won. Because it's just Markdown in the repo, a context/ update ships in the same commit or PR as the code change it explains — reviewed the same way, versioned the same way, no separate system to trust or keep in sync.

The skill's behavior is exercised by a suite of eval cases, executed for real — a fixture project per case, a fresh agent session, LLM-judged verdicts: Evals.

Install

Not with pip — the skill installs into your agent, not into a Python environment. main is active development; pin to latest (moved automatically by CI to the newest release) or an exact tag.

Recommended — skills CLI (via npx, needs Node.js):

npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why

Also — GitHub CLI (gh v2.90.0+):

gh skill install oliver-zehentleitner/keep-the-why keep-the-why@latest

Both prompt for which agent (Claude Code, Codex, OpenCode, and 70+ more) and which scope (project or personal). Start a new session afterward, then tell your agent something like "initialize Keep the Why in this project" — a short one-time setup creates a .keep-the-why file at the project root, and later sessions pick the project back up on their own.

Every other install method — asm, Claude Code plugin, manual clone, per-agent directory paths, tools without a skill runtime at all: Installation.

The linter — this one is pip install

The structural half of the context/ format is CI-checkable. keep-the-why-lint validates required fields, value sets, index consistency, and .keep-the-why integrity — schema-version-aware, so unmigrated projects don't fail on structure their version never defined. Content (whether the rationale is true) stays a human judgment; the linter doesn't pretend otherwise.

pip install keep-the-why-lint
ktw-lint .

One line in GitHub Actions (uses: oliver-zehentleitner/keep-the-why@lint-latest), a job in GitLab CI, or a pre-commit hook — see Linting and CI linting setup. Python 3.10–3.14, no dependencies beyond the standard library.

Example

You: We're changing the retry mechanism because the previous
     implementation caused duplicate orders. Make sure future
     maintainers understand this.

Keep the Why updates the relevant topic file in context/ (or creates one if none exists), records the reason, and marks the old approach as superseded — without you having to ask for documentation separately.

Weeks later, a new maintainer — human or agent — can just ask:

You: Why does the retry mechanism track state instead of just retrying?

and get the real answer instead of reverse-engineering it from the diff. See examples/ for continuous, retrospective, and interview-mode walkthroughs — including the case where a change gets abandoned and nothing would otherwise have recorded why.

The problem

Important project knowledge gets created in conversation — with a teammate, or with an AI coding agent — and then evaporates once the conversation ends. The code shows what was built. It rarely shows why. Missing reasoning costs you in four concrete ways:

• Re-debate — the same architecture question gets re-litigated because nobody remembers it was already settled.
• Silent regression — someone "cleans up" a workaround that looks unnecessary, not knowing it's the fix for a bug that then comes back.
• Onboarding stall — new contributors (human or AI) don't touch code they don't understand, so progress slows out of caution.
• Repeated agent mistakes — a fresh AI session, with no memory of the last one, proposes or re-implements something already tried and rejected, because nothing on disk records that it was.

What this is not

• Not a Python library. Nothing to import — this distribution is a name reservation; the skill and the linter are the real artifacts.
• Not a guarantee, and not magic. It lowers the friction of keeping rationale honest enough to make that practical to sustain; it doesn't replace the discipline.
• Not a replacement for tests. Tests tell you what broke; this tells you why it was built that way.
• Not session memory, and not an activity log of what an agent did — it's the reasoning behind the project, not a transcript.
• Not project management or an orchestration framework. It has one job: preserve the why.

Why I built this

See Why I built this — Oliver Zehentleitner on noticing this pattern while working with agents day to day, blog, GitHub. For why it's built the way it is — no database, no daemon, no dashboard, deliberately — see Philosophy.

Feedback

Something not working as described, docs that confused you, or the skill's actual behavior not matching what it claims? Open an issue — that's exactly what it's for.

Contributing

See CONTRIBUTING.md, the Changelog, and the Security policy.

Contributors

We ♥️ open source!

License

MIT