decision-tree
A governed artifact in the stable bundle. Replacing this file on
your machine makes your next attestation come back Drifted, naming this path.
| Description | Put a consequential set of choices to the human as an interactive HTML decision tree with a closed click-to-resume loop, not a chat wall of options. Fires on "decision tree this", "put the options to me properly", "give me the choices as an artifact", "walk me through the tradeoffs and let me pick", "log this decision / record the decision and rationale", "what did we decide about X" (queries the decision log) — AND self-triggers: BEFORE presenting 3+ substantive options with real tradeoffs on a consequential call, build the tree instead of a text wall. COMMENT FIELD ON EVERY NODE, non-negotiable. NOT for quick tactical multi-question rounds (a built-in multiple-choice prompt is right there), NOT for yes/no confirmations, NOT for formal ADRs, NOT for goal statements. |
|---|---|
| Arguments | none |
| Tools it may use | [Read, Write, Bash, Grep] |
| Installs at | skills/decision-tree/SKILL.md |
| Mode | 0644 — never executable |
| Size | 10182 bytes |
| SHA-256 | 01012113b57f26876f708090dfeb7fcaa1ac0cca28b4eb6f9f4a86ba87b18875fetch the raw bytes |
The complete file, verbatim
This is the entire SKILL.md, including its YAML frontmatter:
byte-identical to what installs, not rendered and not reformatted. Hash exactly what is below
and you get the digest above. The table is only a reading aid; this block is the artifact.
---
name: decision-tree
description: Put a consequential set of choices to the human as an interactive HTML decision tree with a closed click-to-resume loop, not a chat wall of options. Fires on "decision tree this", "put the options to me properly", "give me the choices as an artifact", "walk me through the tradeoffs and let me pick", "log this decision / record the decision and rationale", "what did we decide about X" (queries the decision log) — AND self-triggers: BEFORE presenting 3+ substantive options with real tradeoffs on a consequential call, build the tree instead of a text wall. COMMENT FIELD ON EVERY NODE, non-negotiable. NOT for quick tactical multi-question rounds (a built-in multiple-choice prompt is right there), NOT for yes/no confirmations, NOT for formal ADRs, NOT for goal statements.
allowed-tools: [Read, Write, Bash, Grep]
---
# /decision-tree — choices as artifacts, decisions as records
A mistwire skill, ported for general use.
Two failures this replaces, both common in agent sessions:
1. **The option wall.** The agent has done real analysis, so it presents six
options with tradeoffs as a thousand words of prose. The human reads the
first two, skims, and picks the one that was easiest to hold in working
memory — which is not the same as the best one. Analysis that cannot be
compared side-by-side has not been delivered.
2. **The unrecorded decision.** A choice gets made in chat, the session ends,
and three weeks later nobody can reconstruct *why*. The rationale was the
expensive part and it evaporated.
The fix for both is the same: make the choice an artifact, and make submitting
it write a record.
## When it fires — the boundary, precisely
| Situation | Route |
|---|---|
| 3+ substantive options, real tradeoffs, consequential | **THIS — build the tree** |
| Rapid row-by-row verdicts, tactical, low-stakes | A built-in multiple-choice prompt |
| Single confirmation / yes-no | Just ask in chat |
| Formal architecture record *after* deciding | An ADR (MADR template) |
| Crafting a goal or DONE condition | A goal-framing skill (`goal-forge` ships alongside this one) |
| "What did we decide about X?" | **THIS — query the decision log** |
Litmus: *would the human want to sleep on it, qualify their answer, or see the
tradeoffs side-by-side?* → build the tree. *Is it tap-tap-tap?* → use the quick
prompt; do not make someone open an artifact to answer three easy questions.
The self-trigger is the important half. You will rarely be asked for a decision
tree by name. You will frequently be about to write an option wall. Catch
yourself at that moment.
## Build — seven hard requirements, no cherry-picking
1. **Visual bar.** Self-contained single file, **no CDN**. It has to render on a
phone in an airport with bad wifi, from a file that was emailed or dropped
into a chat. Dark tokens from your design system, real layout, no ASCII-art
diagrams standing in for a chart.
2. **Per-option tradeoffs, explicit.** Each option gets an essence line plus
distinct plus / minus / caution rows. Badge your recommendation as a
recommendation. Badge deferred or later-phase options as deferred so they
read as parked rather than rejected.
3. **Click to select**, one choice per node, live progress indicator, Submit
gated until every node has a selection.
4. **A comment field on EVERY node — non-negotiable, and actually RENDERED.**
This is the requirement with a scar behind it. In the first version the
capture path was fully wired — the submit handler read the comment, the log
schema had a field for it — but the textarea was never rendered in the DOM.
Every comment the human thought they were leaving was silently lost, and
nobody noticed until someone went looking for a rationale that was never
recorded. **Verify the textarea exists in the rendered DOM before you ship
the artifact.** A capture path that is wired but invisible is worse than one
that is absent, because it manufactures false confidence that rationale is
being kept.
The comment field is also the highest-value part of the whole artifact. The
selection is one token; the comment is the thinking. "Option B, but only
because we are cost-constrained this quarter" is a decision you can revisit
intelligently. "Option B" is not.
5. **A closed resume loop.** Submit POSTs to a small local capture server that
also serves the page. Bind that server to the **loopback interface only** —
it accepts decisions and writes them to disk, and there is no reason for it
to be reachable off-machine.
*Precondition:* this assumes you can run a short-lived local HTTP server on
the human's machine and open a browser at it. If you cannot, use requirement
6 instead — do not skip the loop and go back to chat.
6. **Graceful degrade, out loud.** If there is no server — the artifact is being
opened straight off the filesystem — fall back to writing the submission to
a known local directory plus copying a compact delimited token to the
clipboard for the human to paste back. **The page must SAY it is in degraded
mode.** A fallback that looks identical to the working path is how a
submission gets made, lost, and assumed delivered.
7. **Audit trail.** Submissions append to a line-delimited JSON decision log.
Consumed entries get marked consumed; they are **never deleted**. Append-only
is what makes "what did we decide about X, and what did we say at the time"
answerable a year later.
## The wait — never poll in model turns
Once the artifact is in front of the human, you are waiting on a human-speed
event. **Do not burn model turns polling for it.**
Block on the submission with a child process that watches the submission
directory and exits when a file appears, run as a background task, with a
timeout. Its completion re-invokes the session with the human's choice and
comments attached. Zero busy-wait turns.
*Precondition:* this assumes your agent runtime can (a) run a background task
that outlives the current turn and (b) re-enter the session when that task
completes. If yours cannot, the correct fallback is to end the turn cleanly and
let the human return with the submission — **not** a sleep-and-check loop.
This is worth stating flatly because busy-wait polling is not a small tax. In our
own session transcripts, `sleep N && check` loops were consistently among the
largest single sources of wasted turns: each one cost tokens, latency, and
context window, and none of them made the human click any faster. Treat that as
an observation from one team's logs rather than a published benchmark —
instrument your own sessions if you want a number for yours.
## On resume
When the submission arrives:
1. Read it.
2. **Restate the choice and every node comment, verbatim, in one block.** One
block, not scattered through the response. The human is re-entering context
they left an hour or a day ago; give them the whole decision back at once.
3. Then act on it.
4. **Bank the outcome** to durable cross-session memory — via your memory or
governance MCP server if you have one, a durable record file if you do not —
keyed so it is findable (`decision_<slug>_<date>`), storing what was decided,
why, and its blast radius in whatever compact, greppable format your memory
layer uses.
Step 4 is what keeps "what did we decide about X" answerable long after the
session ends. Skipping it turns an expensive, well-run decision back into chat
scrollback.
## Self-check before shipping the tree
Run these as checks, not as claims. Give each one a verdict — PASS, FAIL, or
NOT-RUN. A gate you did not run is **NOT-RUN**: never a silent skip, and never
quietly promoted to a pass.
1. **Trigger vocabulary** — do the explicit-ask phrasings, the self-trigger case,
and the query case ("what did we decide about X") all appear, and are the
negative routes named so the skill does not fire on tactical questions?
2. **Scoped tools** — write for the artifact, shell for the capture server and
the blocking watcher, read and search for decision-log queries. Nothing
broader.
3. **Reason to exist** — can you name the specific failure this instance
prevents? The option wall and the evaporated rationale are the two this was
built for; if yours prevents neither, say what it does prevent.
4. **Grounded** — does every requirement trace to a convention you actually
follow or an incident you can point at? Requirement 4 traces to the invisible
comment field described above. A requirement that traces to nothing should be
cut, not shipped.
5. **Honest reporting** — degraded mode announces itself on the page; resume
restates comments verbatim; a capture server that failed to bind reports
NOT-RUN rather than implying the loop closed.
6. **Fire-validation** — validate against at least three cold prompts *plus* one
in-context self-trigger case (an actual options-presentation moment, where no
trigger words are spoken). Cold prompts alone will not catch a skill that
never self-fires. Until you have run that, this gate is NOT-RUN — record the
results somewhere durable when you do.
7. **Visual bar** — open the finished artifact at phone width and read it before
you send it. "The deliverable *is* the artifact" is an argument for why this
gate is usually easy, not evidence that it passed.
8. **Cognitive-load fit** — are tradeoffs side-by-side rather than serial prose,
one choice per node, the comment captured at the point of decision rather than
recalled later, and does the resume restate everything in a single block?
9. **Kindness to the human and the system** — does it kill the option wall and
the "paste this back to me" fishing expedition? Is the audit trail
append-only, the capture surface local-only, and the degrade path incapable
of stranding a decision the human already made? **Verdict: record MET or
NOT-MET like every other gate.** A gate that carries no verdict is decoration,
and this is the one most easily waved through because it sounds subjective.