root-cause-by-layerlisted

# Root-Cause-by-Layer ## Overview A bug is a **symptom**. The disease almost always lives at a layer boundary, a contract violation, or a conceptual mismatch — rarely on the line that threw the exception. Walk the 5-layer ladder before proposing any fix. **Core principle:** A change that turns the symptom green without a causal story at layers 3–5 is a **suppression, not a cure.** It re-emerges in a different guise within a few iterations. **Violating the letter of the layered analysis is violating the spirit.** "I know the cause already, I'll skip writing it out" is the most common skip — write it down anyway. The discipline is the externalization. ## When to Use Any of these triggers means invoke this skill **before** proposing code: - A test is red or flaky and you want to ship a fix - An exception, type error, assertion failure, or unexpected output - A CI gate is rejecting and you're considering widening the rule - An LLM/tool returned a malformed result and you're considering a retry/regex - You catch yourself typing `try:`, `hasattr(`, `@pytest.mark.skip`, `# TODO clean up`, or a retry loop as the primary fix - Deadline / sunk-cost pressure is telling you "just get it green" Do **not** use for: cosmetic edits, rename refactors, adding new features with no failing signal. This skill is for *diagnosing*, not *building*. ## The Five Layers Apply in order. You do **not** have a root cause until you can answer **both 4 and 5** out loud. 1. **Symptom** — The exact