principle-fix-root-causes
Use for any debugging or bug fix. Repair the earliest point where the system decided wrongly, rather than where the bad state showed up. A guard is a real fix only for a state the system is permitted to reach.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- principle-fix-root-causes
- description
- Use for any debugging or bug fix. Repair the earliest point where the system decided wrongly, rather than where the bad state showed up. A guard is a real fix only for a state the system is permitted to reach.
- disable-model-invocation
- true
03 SKILL.md 正文
Fix root causes
Locate the earliest wrong decision the system made and repair it there, rather than at the spot where the damage became visible. Adding a guard counts as a fix only if the state it catches is a legitimate one for the system to be in.
When it applies
All debugging and bug-fix work. If several fixes resting on one assumption have already failed, combine this with principle-attack-the-premise.
What to do
- Reproduce the failure before changing anything.
- Keep asking why until you reach a decision in code that was itself wrong, as opposed to one that followed correctly from an earlier mistake.
- When you are stuck, instrument. Read the real error and the real state. Do not guess.
- Classify the triggering state. If it is legitimate, the code that failed on it is at fault, and handling it in that code is the right fix. If the state should never occur, testing for it where it showed up only conceals the bug, so follow it back to whatever created it. Be suspicious of guards, retries, swallowed exceptions, clamped values, and discarded state.
- When a failure shows up just after restarts, look at persisted state before anything else: serialized sessions, caches, lock files, and configuration on disk.
- Fix the pattern: search for all other sites that share the fault and repair each one.
- A workaround that needs a long comment to justify itself signals broken code, so change the code instead.
- If finding the deciding fact took deep digging, propose a cheap always-on signal (a log line, a metric, an assertion) that would have shown it immediately.
A security example. An agent's file tool crashes on a path containing ../. Adding if ".." in path: return at the crash site looks like a fix, but a path that escapes the workspace should never have reached the tool. The root cause is the boundary that accepted it without resolving and checking it against the workspace root. Fix it there, then search for every other tool that takes a path from model output, because each one has the same traversal hole.
The failure it prevents
Symptom patches hide evidence and let the fault resurface elsewhere. Unnamed workarounds pile up. A single-instance fix leaves sibling defects in place, and for security bugs those siblings are the next finding.
Done when
You traced the failure to a decision the code got wrong, repaired it at that spot, and repaired its siblings as well.
The comment-auditor agent flags justification comments as evidence of this failure. The how and why skills help trace a symptom back to its origin.
Related: principle-attack-the-premise, principle-prove-it-works, principle-boundary-discipline.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.