five-whys
Root cause analysis using the Five Whys technique. Use when a bug persists despite surface fixes, a failure recurs, or a process keeps breaking. Ensures the fix targets the root, not the symptom.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- five-whys
- description
- Root cause analysis using the Five Whys technique. Use when a bug persists despite surface fixes, a failure recurs, or a process keeps breaking. Ensures the fix targets the root, not the symptom.
03 SKILL.md 正文
Five Whys — Root Cause Analysis
The Rule
DO NOT FIX THE SYMPTOM. FIND THE CAUSE.
A fix that doesn't address the root cause is temporary. The cause returns.
Protocol
Step 1 — Define the problem precisely
One concrete sentence. Not vague.
| Wrong | Correct |
|---|---|
| "The system is slow" | "GET /orders exceeds 3s for 90% of requests in prod since Friday" |
| "Tests fail sometimes" | "test_payment_flow fails in CI roughly 1 in 20 runs with no clear error message" |
Step 2 — Five Whys cascade
For each answer, ask: "Why does that happen?"
Don't stop until you reach something you control — a decision, a process, a line of code, a missing configuration.
Problem: Users see another user's data
Why 1: Cache returns the wrong entry
Why 2: Cache key does not include user_id
Why 3: Developer assumed the endpoint was public
Why 4: No isolation test existed for this endpoint
Why 5: Code review had no data isolation checklist
→ Root cause: review process missing a security checklist
Step 3 — Validate in reverse
Read the chain bottom-up: "No review checklist → cache key missing user_id → data leak." If the chain holds, the root cause is valid.
Step 4 — Fix at the root, not the symptom
Fix at the deepest level that is practical to change.
| Fix level | Example | Durability |
|---|---|---|
| Symptom | Manually flush cache | Hours |
| Proximate cause | Add user_id to cache key | Days |
| Root cause | Add isolation checklist to review | Permanent |
If you can only fix an intermediate level, document the root cause as tracked technical debt with a concrete TODO.
Branching
A root cause can have multiple branches — explore all before choosing where to fix.
Problem: Deploy fails in prod but not in staging
Branch A: different configuration (env vars, secrets)
Branch B: prod data has different volume or format
Branch C: network dependencies only reachable in prod
Test each branch independently. Do not assume.
When to Stop
Stop before the 5th why if you reach a clear, actionable root cause. Stop after the 5th if the chain hasn't converged — there may be multiple independent root causes.
Output
Document the analysis:
**Problem:** [concrete one-liner]
**Root cause:** [deepest level found]
**Fix:** [concrete action with file/component]
**Temporary fix (if needed):** [what you apply now while the real fix is in progress]
**Technical debt:** [what remains unresolved and why]
Integration with A Team
- Run this skill before launching the
systematic-debuggingagent — Five Whys defines the investigation scope - After finding the root cause, use the
tdd-guideagent to write the test that would have caught it - If the root cause implies a process change, document the analysis in
DAILY.md
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.