five-whys
Guided dive-deep research mode. 5 Whys is the default engine — one focused question at a time along What-it-is -> Example -> Why-not-alternatives -> Benefits -> Costs, user-steered branching, every st
SKILL.mdsrc/kiro_crew/builtin_skills/five-whys/SKILL.md
GitHub5 Whys — guided dive-deep MODE
This is a mode, not a one-shot answer — once triggered you enter it and stay in it across turns until the user is satisfied or exits. Its purpose is to help someone understand something deeply: a bug, an incident, a system, a concept, or a decision. It works by asking one focused question at a time, keeping every answer short and direct, and branching — so understanding is verified at each step and the exploration reaches the real root.
The engine of the mode: every step is one append to an event log; the tree, the current question, the open branches and the final report are all folded from that one log — never maintained by hand. 5 Whys is the default engine of a small research method built on that log; more capabilities (web search, recap, ...) plug into the same log — see Capabilities below.
The core loop (this is the whole mode)
Each turn does exactly one of these, then stops and waits:
- Answer the current question — short and direct (see disciplines below).
- Propose the next layer: 2-4 candidate branch questions about the answer you just gave. Each is a single, direct "why...?" / "how...?" / "what causes...?" — the obvious next things to dig into.
- Let the user steer. They can (a) pick one of your proposed questions, (b) pick several (each becomes a branch), or (c) type their own question — which becomes a new branch just the same. Never force your menu; the user's own question always wins.
- Append the events for what happened (an
ask, ananswer, afocusmove...) to the log viascripts/five_whys.py(see The mechanical core), then repeat.
So branches form naturally: every answer sprouts a small menu, the user follows one thread deep, and the unpicked questions wait as branches to return to.
The reasoning chain (the spine of every dive)
Peeling a thing apart should follow one basic chain of thought. Let it order the answers you give and the branch questions you propose, so the exploration always moves from grasping the thing to judging it:
- What it is — a plain, concrete definition, ideally via an everyday analogy (a ledger, a git commit, a phone switchboard). Grasp the thing first.
- Example — one concrete, walked-through instance. Abstract only lands once it's touchable.
- Why not the alternatives — contrast with the other plausible designs (not necessarily the naive one — the serious rival approaches too), and what breaks with each. This is where real understanding lives.
- Benefits — what this choice buys you that the alternatives don't.
- Costs — what it costs: complexity, edge cases, failure modes, tax on the reader. Nothing is free; naming the price is the honest finish.
Use it as a default spine, not a rigid script. A node usually advances one
stage along this chain (its answer sits at one stage; the proposed menu offers
the next stage's questions), but the user can jump stages or open a side branch
anytime — their question always wins (see the core loop). Every ask event
carries its stage (what / example / why-not / benefits / costs), so
the folded report reads as a complete chain per thread.
Two disciplines (keep the thinking honest)
- One focused question per step. Atomic, answerable in isolation, no compound or multi-part questions. If it needs "and also...", split it into two branches.
- Short answer, expandable on demand. Default to one or two sentences — one idea per step is what makes it learnable and keeps each link verifiable. If the user wants more on a node, they say "expand / go deeper" and you elaborate, but the default stays short so the tree doesn't turn into a lecture.
Who answers
- Understanding questions -> you answer from your knowledge, and cite concrete
evidence (
file:line, a doc, a log) when the answer is about their code or system so it's grounded, not guessed. - Facts only the user holds -> ask the user (what they observed, what they intended, a decision they made). Two sentences from them, same cap.
- Never fabricate. If you can't answer and can't cite it, say so and ask.
Side discussions
At any point the user can open a side discussion to explore something more freely than the one-question / short-answer rhythm allows — anchored to the current node but off to the side.
- Enter: the user says "side discussion" / "let's discuss this" (optionally
naming a topic). Say you're in a side discussion anchored at node
[x]and pause the main loop — the two disciplines and the question-menu are suspended; talk freely, longer answers and tangents are fine. - Record it: append
discussevents (anchored to node[x]) so the exchange is kept even though it lives off-tree. - Non-destructive by default: a side discussion never silently changes the
tree — no
ask/pruneevents are emitted from it unless the user approves. - Offer to fold findings in: when the discussion yields something worth
keeping (and again when it ends), tell the user they can (a) add a new
branch — emit an
ask(+answer) event, (b) remove a node — emit apruneevent, which is refused if the node is the current focus or an ancestor of it (focuselsewhere first), or (c) keep it as discussion-only. Emit those events only on their explicit say-so. - Exit: the user says "end discussion" / "resume 5 whys". Append a
discusssummary line, apply any approvedask/pruneevents, then resume the main loop exactly where it paused — the lastfocusevent in the log is the cursor.
The event log (single source of truth)
Model the whole session as an append-only event log, one JSON object per line,
at <project-dir>/five-whys/<slug>-<YYYY-MM-DD>.jsonl (fall back to the workspace
dir if there is no project). The log IS the state. You never rewrite it and
never keep a separate hand-maintained tree — the tree, the current question, the
open branches and the report are all projections you fold from the log when
you need them, so they can never drift out of sync.
That path is a convention of this skill: the script never derives it. <log> is
a required positional on every subcommand, and finding an existing log to resume
is your own step — list five-whys/ yourself before starting a new one.
Every line: {"ts": <ISO-8601>, "type": <type>, ...}. The types:
| type | key fields | meaning |
|---|---|---|
ask |
id, parent, stage, q, origin(proposed|user) |
a question node is created; parent records the relationship — this is how the tree exists without being stored (root's parent is null) |
answer |
id, a, source(ai|user|<cite>) |
the answer to node id |
focus |
id |
the cursor: node id is now the current question (latest focus wins) |
done |
id, kind(root|takeaway), note |
this thread bottomed out |
discuss |
anchor, text |
a side-discussion entry, off-tree, anchored to a node |
prune |
id, reason |
remove a node/branch — a new event, never an edit to history |
This table is the built-in core; capabilities extend it with their own types (see Capabilities). Because every projection ignores types it doesn't recognize, adding a type never breaks the fold.
Example:
{"ts":"2026-08-16T20:00:00Z","type":"ask","id":"1","parent":null,"stage":"what","q":"What is X?","origin":"proposed"}
{"ts":"2026-08-16T20:00:01Z","type":"focus","id":"1"}
{"ts":"2026-08-16T20:00:30Z","type":"answer","id":"1","a":"X is ...","source":"ai"}
{"ts":"2026-08-16T20:01:00Z","type":"ask","id":"1.1","parent":"1","stage":"example","q":"An example?","origin":"user"}
{"ts":"2026-08-16T20:03:00Z","type":"discuss","anchor":"1.1","text":"tangent about ..."}
{"ts":"2026-08-16T20:05:00Z","type":"done","id":"1.2.1","kind":"root","note":"real root cause: ..."}
Projections (fold the log, don't store them):
- Tree = group every
askbyparent(minuspruned ids). - Current question = the
idof the lastfocusevent. - Open branches / frontier =
asked ids with noanswerand nodone, excluding the current focus and anypruned ids. - Roots / key takeaways = the
doneevents. - Report = one fold over the log (see close-out).
The mechanical core (scripts/five_whys.py)
All log reads and writes go through this script — never hand-write or
hand-fold JSONL. It owns the deterministic mechanics (append + schema
validation, id allocation, referential integrity, and folding to projections),
so the LLM only supplies judgment. Run it by ABSOLUTE path from the project
directory, not from the skill dir, and always pass <log> as an absolute path:
a relative <log> resolves against the shell's cwd, and a log written inside
the installed skill dir is moved aside the next time the builtin skill syncs.
Below, scripts/five_whys.py stands for <skill-dir>/scripts/five_whys.py:
python3 scripts/five_whys.py ask <log> --parent ID|root --stage S --stdin-json < f.json # f.json={"q":"..."}; prints new id
python3 scripts/five_whys.py answer <log> --id ID --stdin-json < f.json # {"a":"...","source":"..."}
python3 scripts/five_whys.py focus <log> --id ID
python3 scripts/five_whys.py done <log> --id ID [--kind root|takeaway] --stdin-json < f.json # {"note":"..."}
python3 scripts/five_whys.py discuss <log> --anchor ID --stdin-json < f.json # {"text":"..."}
python3 scripts/five_whys.py prune <log> --id ID --stdin-json < f.json # {"reason":"..."}
python3 scripts/five_whys.py event <log> --stdin-json < f.json # f.json = the plugin event object
python3 scripts/five_whys.py view <log> # current path root->focus + open-branch count (show this each turn)
python3 scripts/five_whys.py tree <log>
python3 scripts/five_whys.py frontier <log>
python3 scripts/five_whys.py report <log> --stdin-json < f.json # {"title":"..."}
python3 scripts/five_whys.py validate <log> # schema + integrity gate, exit 0/1
The script allocates ids, so you never invent them; prune cascades to
descendants, and it REFUSES when the target is the current focus or an ancestor
of it — focus another node first, otherwise resume would land on a pruned node.
Unknown (plugin) event types validate fine and are ignored by the core folds.
report prints the finished markdown — close-out is one command.
Free text never rides the shell command line. Write every command's free-text
fields (including source, title, or the whole plugin event) as one JSON object
using the write tool in a fresh, unique temp file (e.g. allocated with mktemp).
Feed it on stdin with --stdin-json as shown above; never use a fixed shared path.
This prevents concurrent-session clobber and shell execution of $(...), backticks
or quotes. Only safe values for --parent, --stage, --id, --kind, --origin
and --anchor stay as ordinary flags.
Capabilities (plugins)
5 Whys is the default engine, but the mode is really a small research method built on the shared event log — new capabilities plug in by reading that log and appending their own typed events. Nothing else couples them; the log is the only contract.
A capability declares four things:
- Invocation — a word the user types (e.g. "search", "recap") or a menu entry you offer.
- Reads — the shared log (never a private store), so it starts with full context.
- Emits — its own append-only event
type(s), marked structural (ask/prune— changes the tree) or annotation (everything else — never changes the tree, only enriches a node). - Discipline — same as the core loop: do one thing, append, stop and wait.
Example capabilities:
- web search: when an answer needs external facts, search, then append
{type:"search", id, query, sources:[...], summary}and feed it into ananswerwhosesourcecites those URLs — a searched answer is never ungrounded. (Annotation.) - recap: fold the log so far into a running summary and append
{type:"recap", scope:(node|subtree|all), text}to re-orient mid-session without losing the thread. The close-out report is just a recap over the whole log. (Annotation.) - add your own (
hypothesis,evidence,define, ...) the same way — pick atype, say whether it's structural or annotation, done.
Procedure
- Anchor the starting point, append its
ask(id:"1",parent:null) and afocuson it. Resume, don't fork: if afive-whys/<slug>*.jsonlfor this topic already exists, continue the newest one (fold it,focuswhere it left off) instead of starting a second log. - Give the first answer / orientation, then propose the first menu of 2-4
branch questions. Append the
answer; then append anaskfor every question in the menu (eachorigin:"proposed") so the whole menu parks in thefrontier, andfocusthe one the user picks — or append +focusa question the user types (origin:"user"). Unpicked proposals wait in the frontier until pursued later orpruned; that is what makes "nothing is lost" true. Stop. - Loop the core loop. Pursue the user's chosen thread depth-first; each
answer produces a fresh menu. When they switch, just
focusthe parked node — the frontier is whatever the fold says is still open, so nothing is lost. - Bottom out a thread with a
doneevent when the answer is a real root / fundamental takeaway (incident: actionable and within the system's control; concept: a first principle the user is satisfied with). - Show only the current path each turn — fold root -> current node, indented —
with the short answer, the proposed menu, and a one-line "other open
branches: N". Do not paste the whole tree; it lives in the log. Offer an
<mcwidget>tree view (folded from the log) if the user wants the big picture. - Close out -> report. When the user exits or every branch is
done, runpython3 scripts/five_whys.py report <log>— it folds the log into a clean markdown report (Starting point; the tree with each node's stage -> question -> answer, so every thread reads as a What -> ... -> Costs chain; roots / key takeaways; side-discussion summaries). Add (for an incident) corrective + preventive actions, write it beside the log, and offer to save it as an artifact. Because the log is complete, this is pure projection — no reconstruction from memory.
Guardrails
- Append-only — never rewrite the log. Correcting or removing something is a
new event (
prune, a freshanswer, a newfocus), never an edit to a past line. History stays intact; that is what makes the fold trustworthy. - Never hand-write or hand-fold JSONL. Every read and write goes through
scripts/five_whys.py— it validates, allocates ids, and folds deterministically, so the tree and report can't drift from the log. - Use the free-text stdin contract in The mechanical core for every command carrying text or plugin JSON.
- Don't dump — drip. Resist answering the whole topic in one turn; the value is the one-step-at-a-time ladder. Short answer + a menu, then wait.
- The user's own question always branches — never redirect it back to your menu.
- "Human error" is never a root cause (incident mode): the next question is why the system allowed it, until the answer is a fixable system property.
- Cause, not blame. The tree explains mechanism, not who to fault.
- Don't leap to the root and back-fill — each level is earned by the one above.
Interaction mechanics (this runtime)
- One answer + one question-menu, then stop and wait — this is what makes it a mode, not a monologue.
- Render the proposed menu as a final
[OPTIONS: ...]line (each option is one branch question, phrased in the user's voice) so they click to go deeper — and remind them they can just type their own question instead, or say "side discussion" to open one (and "end discussion" to come back). - Keep every turn to: current path + the short answer + the menu + open-branch count. The log holds everything; the chat holds the focus.