principle-fix-root-causes
Apply when choosing where to fix a bug. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate.
- License 许可
- MIT
- 所属仓库
- ravnhq/ravn-core
- 最近更新
- 2026-11-13
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- principle-fix-root-causes
- license
- See LICENSE.txt
- metadata
- { "proof": "subjective" }
- description
- Apply when choosing where to fix a bug. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate.
- disable-model-invocation
- true
02 资源文件 2
- 参考文档agents/openai.yaml136 B
- 许可证LICENSE.txt1.1 KB
03 SKILL.md 正文
Fix Root Causes
Adapted from pstack principle-fix-root-causes, MIT License, Copyright (c) 2026 Lauren Tan. See LICENSE.txt.
The symptom is where a wrong state became visible. The root cause is the first place the system did something it should not do, or failed to handle a state it should handle. Fix that.
- Reproduce first.
- Ask "why" at each step until the answer is a wrong decision in the code, not a consequence of an earlier one. When stuck, instrument: read the actual error and the actual state.
- Ask whether the state that triggered the symptom is legitimate. If the system may be in that state, the code that broke on it is the root cause, and handling the state there is the fix. If the state should never exist, a check where it broke hides the bug: find what produced the state. Guards, retries, swallowed errors, clamped values, and discarded state are the usual ways to hide a bug.
- When something fails only after a restart, suspect persisted state first: config files, caches, lock files, serialized state.
- Check for the pattern, not just the instance. Find every place with the same fault and fix them all.
- A workaround that needs a paragraph-long comment means the code is wrong: fix the code.
- If the deciding fact took a deep dig to find, propose the cheap, always-on signal that would have shown it at first look.
04 同仓库更多 Skills
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
why
Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Queries every available evidence MCP in parallel and returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
typescript-best-practices
TypeScript type-safety rules: discriminated unions, branded types, no `as`, exhaustive switches, schema-derived types. Use when writing, editing, or reviewing TypeScript.
show-me-your-work
Keep a reviewable decision trail for unattended or multi-phase work: a TSV log with one row per decision (what, why, evidence, result).
ship
Take a change from idea to a ready PR with passing CI, running research, grilling, design, verification, and the pr skill in sequence.
session-pickup
Resume unfinished work from a handoff note or prior coding-agent session. Use before reading a supplied handoff, even when its next action is only an inspection or report. Also use to pick up, continue where you left off, or take over from a transcript, agent URL, or pushed branch. Use pause-safely to write a handoff.