Recover why code is shaped the way it is before changing it. Use for "why does X work this way", "why was this threshold picked", design rationale, and dead-code questions. Also run it as the research step before reverting a commit, deleting or loosening a guard, check, test, or invariant, or naming a past commit as a root cause. Anchors in git history and PR bodies first, then fans out one investigator per available evidence source and reports every null. Use `how` for runtime behavior.
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# Why
`how` answers what the code does. `why` answers what forces produced it.
Feeds `principle-prove-it`: a constraint you cannot see is a constraint you
will delete. Most "we changed it back a week later" bugs are this.
## Before a reversal or a loosened guard
This is Chesterton's fence: do not take a fence down until you know why it
was put up (G. K. Chesterton, *The Thing*, 1929,
https://www.chesterton.org/taking-a-fence-down/). A failing check and the
change that tripped it are two fences. Recover the reason for both before
removing either.
**Delegate the digging.** Spawn one decision-history investigator
(`subagent_type: general-purpose`, read-only) in the same message as any
other Step 2 investigators. Give it:
- the change you would undo (SHA or PR number);
- literal tokens from the thing it collides with: the failing guard,
check, test name, or error text.
Ask it to return, each row marked read-confirmed or name-matched and with
the ref it was read at:
1. **The change's claim.** `git show <sha>` / `gh pr view <number>`, quoted
Review Claim or summary.
2. **Who put up the other fence.** `git log -S '<token>'` (or `-G`, `-L`,
…
The line at the top of this page pins the label git:20260916.3d1c40e, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
GET https://markdownregistry.com/api/v1/artifacts/art_5ddxykwhemq7zlju
GET https://markdownregistry.com/api/v1/resolve?ref=edbertchan/catstack/why
GET https://markdownregistry.com/api/v1/blob/e73d967206142361522b7383084c7cbca904ac027ad8c7715e1a70a5a079e7c3
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
edbertchan/catstack · corpus/skills/cat-mode/SKILL.md · Edbert's personal working conventions, mined from real session history across his projects. Use when Edbert asks to…
edbertchan/catstack · corpus/skills/principle-assert-invariants-not-last-bug/SKILL.md · Apply after a bug ships past review or a passing grade/check: assert the general class of failure instead of patching…
edbertchan/catstack · corpus/skills/principle-bind-to-named-inventory/SKILL.md · Apply after an audit, scoring review, or a request for a "real classifier" / "less arbitrary weights" when existing…
edbertchan/catstack · corpus/skills/principle-build-the-lever/SKILL.md · Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or…
edbertchan/catstack · corpus/skills/principle-encode-lessons-in-structure/SKILL.md · Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the…
edbertchan/catstack · corpus/skills/principle-experience-first/SKILL.md · Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship…
edbertchan/catstack · corpus/skills/principle-fix-root-causes/SKILL.md · Apply when debugging. Trace each symptom to its root cause and fix it there; reproduce first, ask why until you reach…
edbertchan/catstack · corpus/skills/principle-flag-your-own-corrections/SKILL.md · Apply whenever you are about to admit fault in any wording — a fact, number, claim, or check you already stated turns…
edbertchan/catstack · corpus/skills/principle-generalize-from-rejection/SKILL.md · Apply when a mechanical gate — a lint, validator, blocked-command guard, or CI check — rejects your output for the same…
cursor/plugins · harness/pstack/claude-code/skills/why/SKILL.md · Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed…
cursor/plugins · pstack/skills/why/SKILL.md · Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed…
michael-denyer/pstack-claude · plugins/pstack/skills/why/SKILL.md · Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed…
backnotprop/pstack · skills/why/SKILL.md · Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed…
bastani-inc/atomic · packages/workflows/skills/why/SKILL.md · Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed…
millw14/merrymen · plugins/merrymen/skills/why/SKILL.md · Explain why the user's Merrymen trading agent has or hasn't traded, from its recorded state, blockers and recent…
j-star-films-studios/vibecode-protocol-suite · assets/.agent/skills/code-intelligence/why/SKILL.md · Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed…
creedants/pstack-t3 · t3/overrides/why/SKILL.md · Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed…
