Keep the Why

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

Keep the Why is a repo-native agent skill that captures the reasoning behind a codebase 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, capturing architecture decisions, rejected alternatives, workarounds, incident learnings, and operational constraints that the code alone can't explain.

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. The same context makes changes safer across the board, 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.

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

How it works

Keep the Why is a SKILL.md-based agent skill — 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 (leaving, retiring, changing teams), the agent analyzes the codebase first, then either asks targeted questions about exactly what the code couldn't explain, or — for someone whose knowledge is broad and tacit after many years on one system — just listens while they narrate freely and extracts the rationale from that instead.
4. Maintenance — existing rationale docs get kept current: contradictions resolved, superseded entries marked, oversized files split.

First activation in a project runs a short one-time setup instead of guessing at defaults — where the why-knowledge should live, how to start, proactive or explicit-only capture, how much confirmation is needed before something gets written, and whether to periodically check for skill updates or context/ staleness. See docs/setup.md.

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.

Where the captured knowledge actually lives, and how it relates to everything else a project already has, is one coherent picture — see "Where this fits" below.

Install

main is active development, not guaranteed release-ready — pin to latest instead of tracking it directly (moved automatically by CI to the newest release; use an exact tag instead for full reproducibility).

Recommended — skills CLI (via npx, needs Node.js — npx ships with it, nothing extra to install):

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

Prompts you to select one of 70+ supported agents (Claude Code, Codex, OpenCode, and more) and choose whether to install the skill at project or personal scope, then symlinks or copies the skill package in. Also listed on skills.sh. Start a new session afterward so the skill is picked up, then tell your agent something like "initialize Keep the Why in this project" — a Skill activates when something in the conversation matches it, not automatically on session start, so asking directly runs the one-time setup wizard right away instead of waiting for it to come up organically. This is only needed once: setup writes a pointer to context/ into AGENTS.md itself, which most AGENTS.md-aware tools already read at the start of every session — later sessions pick the project back up without needing to be told again.

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

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

Prompts for which agent and scope (project or personal) to install for. This installs just the skill package (skills/keep-the-why/), not the whole repo — no docs/, mkdocs config, or CI files end up in your project.

Fallback — manual clone, if neither of the above is available. The skill lives under skills/keep-the-why/ in this repo, not at the root, so clone to a scratch location and copy just that folder rather than cloning straight into your agent's skills directory (cloning the whole repo there would nest an embedded git repository inside yours, and pull in unrelated project files):

git clone --branch latest https://github.com/oliver-zehentleitner/keep-the-why.git /tmp/keep-the-why
cp -r /tmp/keep-the-why/skills/keep-the-why <target-directory>/keep-the-why
rm -rf /tmp/keep-the-why

Where <target-directory> is your agent's skills directory — the folder name must stay keep-the-why:

Codex CLI, Antigravity, Amp, OpenCode, Warp, and more read the shared .agents/skills/keep-the-why path at project scope (Codex scans it from your current directory up to the repository root) and ~/.agents/skills/keep-the-why personally — check whether yours does before falling back to a vendor path. Cline uses its own .cline/skills/keep-the-why (project) / ~/.cline/skills/keep-the-why (personal) instead.

Also compatible with Windsurf, Goose, Roo Code, Trae, Factory, JetBrains Junie, and other tools supporting the open Agent Skills format — the directory convention varies, check your tool's own docs.

Full install detail for every method, including tools without a skill runtime at all: docs/installation.md or https://keepthewhy.com/installation/.

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.

What if nothing gets changed at all?

You: This retry wrapper looks over-engineered — a plain retry loop
     would do the same thing. Let's simplify it.

Working through why it could be simplified surfaces a real constraint (the gateway's rate limiter needs that backoff behavior) — the change gets abandoned before it happens. No commit, no diff, no PR ever results, so normally nothing would capture that reasoning at all. Keep the Why records it anyway, so the next person with the same instinct doesn't rediscover it the hard way — see examples/abandoned-change.md for the full walkthrough.

See examples/ for continuous, retrospective, and interview-mode walkthroughs.

The problem

Important project knowledge gets created in conversation — wi