keep-the-why

What it does

Keeps the rationale behind codebase decisions, rejected alternatives, incidents, operational constraints, and historical context that the code alone cannot explain. It targets non-trivial changes involving design decisions, workarounds, incident fixes, changed assumptions, or onboarding/handovers, and aims to identify what the code cannot explain. It records rationale alongside the code and asks targeted questions rather than generic ones, maintaining concise, topic-based, version-controlled documentation readable by humans and AI agents.

How it works

The skill prescribes four modes of operation within the same job:

• Continuous capture: notice and record rationale found in ongoing conversations, including cases where a modification starts but is stopped after discovering why it shouldn’t be touched.
• Retrospective recovery: given a repository, reconstruct decisions using code, git history, issues, and docs to surface rationale the code cannot explain.
• Knowledge-transfer interview: analyze the repository to extract rationale or prompt targeted questions to capture tacit knowledge from long-tenured maintainers.
• Maintenance: keep existing rationale current by resolving contradictions, marking superseded entries, merging duplicates, and splitting large files.

It classifies each entry with Evidence (confirmed, inferred, unknown), adds Source and Verification fields when tracing claims, and records Status (active, superseded, open, needs-review). It avoids inventing rationale; if not confirmable, it marks unknown or asks for clarification. It preserves terminology and updates topic files rather than creating duplicates.

When to use it

Use when rationale is produced by a design decision, a rejected alternative, a workaround, an incident, an operational constraint, a changed assumption, or related context during a non-trivial change, documentation of legacy code, onboarding, handover, or knowledge-transfer interviews. It also applies when the user expresses frustration with this skill itself.

What it can touch

The skill references and records information about design decisions and rationale; it adheres to project and personal workflows, and uses topic-based files to store reasoning content. It relies on maintaining evidence, sources, and verifications and does not overwrite code or commit changes on its own without explicit user instruction.

Caveats

It never invents rationale; it requires confirmation and corroboration when sources conflict. It records Status and Evidence separately and flags conflicts as open rather than resolving them itself. It emphasizes proportionality and avoids over-claiming for obvious or self-evident decisions. It adheres to license terms (MIT) and keeps existing terminology and documentation conventions intact.