Keep the Why

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

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. 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'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 (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, whether to actively ask for a related issue or ticket, whether to periodically check for skill updates or context/ staleness, and whether to set up something stronger for activation reliability. See references/setup.md.

Current state on activation reliability: a Skill loads when the conversation matches its description — nothing guarantees it loads every session, and there's no cross-tool "autostart" mechanism in the open Agent Skills spec (even Claude Code's own team tracks this as an open gap). The setup wizard now asks about this and has the current agent check what its own platform actually offers, but there's no standardized, tested solution across tools yet — right now it's solved individually, per developer and per project. See this tracking issue for where things stand and to contribute an idea.

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, tested with Claude Code. Current case count, results, an honest failure analysis, the stated caveats, and how to reproduce or run the suite against other agents: Evals. Ongoing work — what's currently being improved, what's working, how to help: tracking issue.

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.

Also installable as a Claude Code plugin — .claude-plugin/plugin.json at the repo root (separate from the root plugin.json, which serves GitHub's Copilot CLI plugin marketplace format).

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