# Keep the Why

> A repo-native agent skill that continuously captures — or retrospectively recovers — the
> reasoning behind a codebase: architecture decisions, rejected alternatives, workarounds,
> incident learnings, and operational constraints that the code alone can't explain.

Because "ask Bob" is not documentation. Keep a Changelog records what changed; Keep the Why
preserves why it changed. Complements README, AGENTS.md, docs, CONTRIBUTING.md, tests, Keep a
Changelog, and AGENTS.local.md rather than replacing any of them — see "Where this fits" in
the README.

Version: 0.1.0.

## Authorship & License

Author / Maintainer: Oliver Zehentleitner (https://github.com/oliver-zehentleitner)
License: MIT — free for commercial and private use. No paid license, no subscription, no commercial tier.

## Quick Start

Recommended, with the skills CLI (via `npx`, needs Node.js):

```bash
npx skills add oliver-zehentleitner/keep-the-why
```

Also recommended, with GitHub CLI v2.90.0+:

```bash
gh skill install oliver-zehentleitner/keep-the-why
```

Fallback (manual clone) — 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 the whole repo
into your agent's skills directory:

```bash
git clone 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
```

Compatible with Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, Cursor, Windsurf,
Antigravity, Amp, Cline, Goose, Roo Code, OpenCode, Trae, Factory, JetBrains Junie, Warp, and
other tools supporting the open Agent Skills format. Full paths per agent: see Installation below.

## Core Concept

Four modes, one underlying mechanism (classify evidence as confirmed / inferred / unknown; ask
only what evidence can't resolve):

- Continuous capture — record rationale as it comes up during normal development
- Retrospective recovery — reconstruct rationale from an existing or legacy repository
- Knowledge-transfer interview — recover a departing developer's knowledge before it's lost,
  either via targeted questions (narrow, specific gaps) or free narration (broad, tacit
  knowledge — let them talk, extract decision-forks from what comes up)
- Maintenance — keep existing rationale current, mark superseded entries, split oversized files

Produces, inside the project using the skill:
- `AGENTS.md` — lean entry point, pointers only
- `docs/` — how to use, operate, test, deploy
- `context/` — why the project is the way it is, organized by topic
- `AGENTS.local.md` — personal/local notes, not committed

## Not a Green Field

Related prior art: Architecture Decision Records, the AGENTS.md standard, git-why, Agent
Decision Records, Addy Osmani's `documentation-and-adrs` skill. Keep the Why's distinguishing
combination: continuous capture *and* retrospective recovery *and* code-guided interviews,
organized as topic-indexed living docs rather than a shadow tree or one-file-per-decision, with
no required external service (no database, no MCP server).

## Common Mistakes

- Don't treat this as a replacement for README, docs, CONTRIBUTING.md, tests, or a changelog —
  it covers only the "why" layer; see "Where this fits" in the README.
- Don't invent rationale when evidence doesn't support an answer — mark it "unknown" instead of
  guessing.
- Don't create a new topic file in `context/` when an existing one on the same subject should be
  updated instead.
- Don't default to a scripted interview question list for someone with broad, tacit knowledge
  (e.g. a long-tenured maintainer) — free narration usually surfaces more; close remaining gaps
  with targeted questions afterward.
- Don't apply the full decision/alternative/reason write-up to obvious, self-evident choices —
  match documentation depth to how non-obvious the decision actually is.

## Docs

- Repo: https://github.com/oliver-zehentleitner/keep-the-why
- AGENTS.md (for AI agents working on this repo): https://github.com/oliver-zehentleitner/keep-the-why/blob/main/AGENTS.md
- SKILL.md: https://github.com/oliver-zehentleitner/keep-the-why/blob/main/skills/keep-the-why/SKILL.md
- Docs: https://keepthewhy.com
- Why this project is built this way: https://keepthewhy.com/context/repo-conventions/