跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

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

技能说明


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:

  1. 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.
  2. Retrospective recovery — given an existing or legacy repository, reconstruct what the code cannot explain from git history, issues, existing docs, and the code itself.
  3. 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.
  4. 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.

  1. Never invent, never assume — ask. If rationale can't be confirmed or reasonably inferred, mark it unknown or 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.

  2. 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 — a contradicted verification 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; the source-reference setting governing when Source is actively sought: references/setup.md.

  3. 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" in references/repository-structure.md).

  4. 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, not context/. Significance and decision-worthiness are different questions: rule 10 tests the former, this rule tests the latter.

  5. Track Status separately from Evidence. Status values: active, superseded, open, needs-review. open means the question is unresolved (distinct from Evidence: unknown, which means a settled claim's rationale can't be traced). A retrospective finding with no traceable rationale becomes an entry wi

阅读完整来源 ↗