Keep The Why
A repo-native convention and agent skill that preserves the reasoning behind code changes to improve agent performance and onboarding.
oliver-zehentleitner · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add oliver-zehentleitner/keep-the-whyAbout this skill
name: keep-the-why description: Extract and preserve the reasoning code cannot explain - decisions, rejected alternatives, workarounds, incidents, constraints - plus project setup and maintainer interviews. Not for what changed (see Keep a Changelog) - only why. license: MIT metadata: version: "0.12.0" repository: "https://github.com/oliver-zehentleitner/keep-the-why" author: "Oliver Zehentleitner"
Keep the Why
The core job: preserve and recover the reasoning that code alone cannot explain. Because "ask Bob" is not documentation — Keep a Changelog records what changed, this preserves why it changed.
When to use this skill
Four modes, all part of the same job:
- Continuous capture — record rationale as it surfaces during normal development: decisions, rejected alternatives, workarounds, incidents, constraints, and changes that didn't happen (starting to modify something, then stopping once a reason not to became clear — that reasoning would otherwise leave no trace). See
references/continuous-capture.md. - Retrospective recovery — given an existing or legacy repository, reconstruct what the code cannot explain from git history, issues, existing docs, and the code itself.
- Knowledge-transfer interview — when a maintainer's knowledge is about to become unavailable, analyze the repository first, then either ask targeted questions or let them narrate freely. See
references/interview-playbook.md. - Maintenance — keep existing rationale current: resolve contradictions, mark superseded entries, merge duplicates, split files that have grown too large.
Edge cases
Don't create a context/ entry for:
- Routine implementation detail with no rejected alternative behind it.
- Generic formatting or style changes.
- Anything already fully explained by the code itself.
- A correction — restoring something to what it should already have been (rule 4) — as opposed to a genuine fork between contending options.
Not every change is a decision worth a context/ entry — see rule 10's proportionality gate.
Composition with other skills
Keep the Why is a cross-cutting persistence skill, not a development methodology. When another skill governs how the work gets done (planning, debugging, TDD, code review), that workflow runs first; this skill only preserves the rationale it produces. A design doc or implementation plan is evidence to draw from, not something to duplicate (rule 3; "Which file does this belong in?" in references/repository-structure.md).
Re-check whether this skill applies at the natural end of another skill's workflow step (a design settled, a root cause confirmed, an alternative rejected) — that's when capture-worthy content has just been produced. This re-check isn't guaranteed to happen on its own — another framework can hold attention through its own workflow; asking directly ("check whether keep-the-why applies here") is a reasonable fallback, not a sign something's broken.
Core rules
Rules 1 and 2 matter most — a skill that hallucinates rationale or acts on a misunderstood instruction is worse than no documentation.
-
Never invent, never assume — ask. If rationale can't be confirmed or reasonably inferred, mark it
unknownor ask a focused question. This applies everywhere: entry content, config fields, ambiguous instructions, removals ("no reference found" means unknown, not safe to delete — ask before removing a Chesterton's Fence candidate; don't manufacture a justification either way). A genuinely missing config field with a documented default may be silently backfilled; a present but unrecognized or contradictory value is not the same — name the valid options and ask. Don't act on an unresolved ambiguity. -
Classify Evidence for every entry. Three levels: confirmed (stated by a maintainer or backed by authoritative evidence), inferred (reasonably derived), unknown (can't be established). Evidence is a separate axis from Status (rule 5): a superseded decision can still have been confirmed when it was current. Add Source and Verification (
corroborated|uncorroborated|contradicted) where there's something concrete to trace — acontradictedverification must explain what contradicts it. When two sources disagree, record both and flag the conflict as open rather than picking a winner. Full field definitions:references/repository-structure.md; thesource-referencesetting governing when Source is actively sought:references/setup.md. -
Adapt to what exists. Preserve the project's terminology and conventions. Update existing topic files instead of creating near-duplicates. Organize by topic (
auth.md,sync.md), not by source file or commit. Existing, working decision records (an ADR folder, design notes) keep their own format: this skill's fields go on the entries it writes from now on, not retrofitted onto records that already work ("Retrofitting" inreferences/repository-structure.md). -
Record both halves of every decision: what was chosen, and what wasn't. Actively look for rejected alternatives and why they lost — in code, history, and what the person said; if none surfaces, record that ("alternatives: unknown") and still write the entry; a follow-up question about alternatives goes on top, not instead. Only record alternatives that were genuinely in contention, not manufactured after the fact. A correction (fixing a stale value, a regressed bug) involved no real fork and belongs in
CHANGELOG.md, notcontext/. Significance and decision-worthiness are different questions: rule 10 tests the former, this rule tests the latter. -
Track Status separately from Evidence. Status values:
active,superseded,open,needs-review.openmeans the question is unresolved (distinct fromEvidence: unknown, which means a settled claim's rationale can't be traced). A retrospective finding with no traceable rationale becomes an entry wi