oliver-zehentleitner/keep-the-why

Keep the Why is an agent skill that saves the reasoning behind decisions made in a codebase, not just the code itself. A changelog tells you what changed. This project tries to capture why it changed: the architecture choices, the alternatives that got rejected, the workarounds, and the lessons learned from past incidents that code comments usually never mention. It works as a SKILL.md file, a shared format that many AI coding agents can read, including Claude Code, Codex CLI, Gemini CLI, and Cursor. Once installed, it runs in four modes. Continuous capture watches ongoing development and writes down rationale as it comes up in conversation. Retrospective recovery is aimed at an existing or older codebase, reading through git history and issues to reconstruct as much reasoning as it can, while being honest about what it could not figure out. Knowledge transfer interview mode is meant for situations where a maintainer is about to leave a project or change teams: the agent studies the code first, then either asks specific questions about the parts the code could not explain, or simply listens if that person prefers to talk freely. A maintenance mode keeps the saved notes current over time, resolving contradictions and splitting files that get too large. The first time it runs in a project, it asks a short set of setup questions instead of guessing, such as where the notes should be stored and whether it should capture rationale automatically or only when asked. Installation is meant to go through either the skills CLI tool or the GitHub CLI, both of which install just the skill folder rather than the whole repository. A manual clone option exists as a fallback for people who cannot use either tool. The stated goal is to make projects easier to hand off between developers, whether that is a new hire or an AI agent seeing the code for the first time, so nobody has to track down the original author just to understand a decision.