Metadata-Version: 2.4
Name: ktw
Version: 0.1.0
Summary: Name reservation for Keep the Why, the agent skill and repo-native convention that preserves the reasoning behind a codebase. Not a Python library - install the skill via your agent's skill tooling; the pip-installable linter is keep-the-why-lint.
Home-page: https://keepthewhy.com
Author: Oliver Zehentleitner
License: MIT
Project-URL: Homepage, https://keepthewhy.com
Project-URL: Documentation, https://keepthewhy.com/installation/
Project-URL: Linter (keep-the-why-lint), https://pypi.org/project/keep-the-why-lint/
Project-URL: Linting docs, https://keepthewhy.com/linting/
Project-URL: Repository, https://github.com/oliver-zehentleitner/keep-the-why
Project-URL: Source (skill), https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why
Project-URL: Changelog, https://github.com/oliver-zehentleitner/keep-the-why/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/oliver-zehentleitner/keep-the-why/issues
Project-URL: Security, https://github.com/oliver-zehentleitner/keep-the-why/blob/main/SECURITY.md
Project-URL: Evals, https://keepthewhy.com/evals/
Project-URL: llms.txt, https://keepthewhy.com/llms.txt
Project-URL: Author, https://about.me/oliver-zehentleitner/
Project-URL: Telegram, https://t.me/unicorndevs
Project-URL: X, https://x.com/keep_the_why
Project-URL: Bluesky, https://bsky.app/profile/keep-the-why.bsky.social
Project-URL: Mastodon, https://mastodon.social/@keep_the_why
Keywords: keep-the-why,documentation,decision-records,adr,architecture-decision-records,rationale,context-engineering,agent-skills,ai-agents,claude-code,codex,opencode,markdown,knowledge-transfer,legacy-code
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10.0
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

[![PyPI](https://img.shields.io/pypi/v/keep-the-why.svg?label=pypi)](https://pypi.org/project/keep-the-why/)
[![GitHub Release](https://img.shields.io/github/release/oliver-zehentleitner/keep-the-why.svg?label=github)](https://github.com/oliver-zehentleitner/keep-the-why/releases)
[![License](https://img.shields.io/github/license/oliver-zehentleitner/keep-the-why.svg?color=blue)](https://github.com/oliver-zehentleitner/keep-the-why/blob/latest/LICENSE)
[![Security: SkillsLLM](https://skillsllm.com/security-check/badge.svg?owner=oliver-zehentleitner&repo=keep-the-why)](https://skillsllm.com/security-check/IPmNycVdbOyq)
[![Validate Skill](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/validate-skill.yml/badge.svg)](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/validate-skill.yml)
[![keep-the-why-lint (package)](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/lint-package.yml/badge.svg)](https://github.com/oliver-zehentleitner/keep-the-why/actions/workflows/lint-package.yml)
[![Read the Docs](https://img.shields.io/badge/read-%20docs-yellow)](https://keepthewhy.com/)
[![Telegram](https://img.shields.io/badge/community-telegram-41ab8c)](https://t.me/unicorndevs)
[![X](https://img.shields.io/badge/x-%40keep__the__why-000000?logo=x)](https://x.com/keep_the_why)
[![Bluesky](https://img.shields.io/badge/bluesky-%40keep--the--why-0285FF?logo=bluesky&logoColor=white)](https://bsky.app/profile/keep-the-why.bsky.social)
[![Mastodon](https://img.shields.io/badge/mastodon-%40keep__the__why-6364FF?logo=mastodon&logoColor=white)](https://mastodon.social/@keep_the_why)
[![Keep the Why](https://keepthewhy.com/assets/badge.svg)](https://keepthewhy.com)

<a href="https://keepthewhy.com"><img src="https://keepthewhy.com/assets/logo.png" alt="Keep the Why — because &quot;ask Bob&quot; is not documentation."></a>

# 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](https://pypi.org/project/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](#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](https://en.wikipedia.org/wiki/Wikipedia:Chesterton%27s_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](https://keepthewhy.com/agent-matrix/) for what's actually been run against what, and how.

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

Documentation: [Installation](https://keepthewhy.com/installation/) · [Setup](https://keepthewhy.com/setup/) · [Repository structure](https://keepthewhy.com/repository-structure/) · [Linting](https://keepthewhy.com/linting/) · [Evals](https://keepthewhy.com/evals/) · [Philosophy](https://keepthewhy.com/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](https://keepthewhy.com/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](https://github.com/oliver-zehentleitner/keep-the-why/releases).

**Recommended — [skills CLI](https://skills.sh/)** (via `npx`, needs [Node.js](https://nodejs.org/en/download)):

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

**Also — [GitHub CLI](https://cli.github.com/)** (`gh` v2.90.0+):

```bash
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](https://keepthewhy.com/installation/).

## The linter — this one *is* `pip install`

The structural half of the `context/` format is CI-checkable. **[keep-the-why-lint](https://pypi.org/project/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.

```bash
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](https://keepthewhy.com/linting/) and [CI linting setup](https://keepthewhy.com/ci-linting/). Python 3.10–3.14, no dependencies beyond the standard library.

## Example

```text
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:

```text
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/`](https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why/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](https://keepthewhy.com/why/) — Oliver Zehentleitner on noticing this pattern while working with agents day to day, [blog](https://blog.technopathy.club), [GitHub](https://github.com/oliver-zehentleitner). For why it's built the way it is — no database, no daemon, no dashboard, deliberately — see [Philosophy](https://keepthewhy.com/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](https://github.com/oliver-zehentleitner/keep-the-why/issues/new/choose) — that's exactly what it's for.

## Contributing

See [CONTRIBUTING.md](https://github.com/oliver-zehentleitner/keep-the-why/blob/latest/CONTRIBUTING.md), the [Changelog](https://github.com/oliver-zehentleitner/keep-the-why/blob/main/CHANGELOG.md), and the [Security policy](https://github.com/oliver-zehentleitner/keep-the-why/blob/main/SECURITY.md).

## Contributors
[![Contributors](https://contributors-img.web.app/image?repo=oliver-zehentleitner/keep-the-why)](https://github.com/oliver-zehentleitner/keep-the-why/graphs/contributors)

We ♥️ open source!

## License

[MIT](https://github.com/oliver-zehentleitner/keep-the-why/blob/latest/LICENSE)
