Key Decision (KD) Skill
Take one decision and analyze it to the bottom. Frame the real question, enumerate the
candidate options, weigh each honestly, and recommend an answer with its cost stated.
The work has two outputs, and they live in different places:
| Output | Where | Committed? |
|---|
| The analysis: options, criteria, measurements, recommendation | .agents/drafts/kd/{YYYY-MM-DD}-{slug}.md | No. .gitignore holds /.agents/drafts/. |
| The decided entry | one entry in docs/design/decisions.md | Yes, and only after the user decides. |
Skill Invocation
/kd <the decision>
Examples:
/kd which isolation primitive should back the box on Linux/kd should the egress gateway do static or semantic outbound control/kd how is temporal history stored
Process
- Check whether
decisions.md already owns this question. Search it by topic, not by
wording. If an entry answers it, this run re-answers that entry. See
Re-answering an entry.
- Frame the question. State what must be decided and why it is hard. A question with an
obvious answer is not a key decision. Say so and stop.
- Find the real options. Three to six, each one a thing someone would actually build.
Include the status quo. Reject a straw man rather than listing it.
- Weigh them. Name the criteria that decide it, and say which option wins each. Where a
claim needs evidence, measure it or read the source. Do not assert.
- Write the draft to
.agents/drafts/kd/{YYYY-MM-DD}-{slug}.md, in the
draft shape. Status is Proposed.
- Report in chat: the one-line recommendation, its cost, and the draft's path. Then stop
and wait.
- Append the entry only when the user says it is decided. Set the draft's status to
Decided, write the entry in the entry shape, and report the anchor.
An agent never decides on the user's behalf. A recommendation is not a decision, and the
user's silence is not approval.
The draft
The draft is where the argument lives, so it can be as long as the analysis needs.
# {The question}
**Status:** Proposed | Decided {YYYY-MM-DD}
**Owns or re-answers:** {new | decisions.md#{anchor}}
## Why this is hard
## Options
## Criteria, and which option wins each
## Evidence
## Recommendation, and its cost
The entry
An entry states the decision, not the argument. Read three neighbouring entries in
decisions.md before you write one, and match their shape.
<a id="{slug}"></a>
### {The answer, stated as a claim. Never a question.}
{Two to six sentences. What is now true, in the present tense, and what it lands in: the type,
the module, or the mechanism. The obvious alternative, and why it lost, in one sentence. What the
decision costs the reader: a limitation, a residual risk, or a thing they must not do.}
- Put it in the section that owns the area:
Premises, The box, Policy,
Containment, Interpreters, Egress, Credentials, or Telemetry.
- The slug is the claim, in kebab-case. It is a permanent identifier, so pick it once.
Code cites an entry by this anchor, as
docs/design/decisions.md#{slug}.
- Name a test that pins the claim, when one exists. Verify the name with
git grep -n 'fn {name}' first. An invented test name is worse than none.
Re-answering an entry
Rewrite the entry to state what is now true. Do not append a second entry beside it. A
reader who must assemble one decision from a stale entry plus its correction reads the design
wrong.
- Keep the
<a id="…"> anchor unchanged, even when the title changes. Code links to it.
- Rewrite the title, the answer, and every cost the change makes false. A title that names
a deleted mechanism is the first thing a reader trusts and the first thing that misleads.
- Open a new entry only for a new question.
Rules
- One entry, one decision. Two decisions are two entries.
- The entry never links the draft.
.agents/drafts/ is gitignored, so the link is dead for
every other reader and every clone. State the answer and its cost well enough that no reader
needs the draft.
- State the answer, not the argument. The argument stays in the draft.
- Never cite a
file.rs:LINE. Name the symbol, the type, or the test. A line number rots on
the next edit above it.
- Never restate a fact the code owns. The code owns behaviour. The entry owns why.
- No status line, no date, no "Updated" banner, and no "Proposed" in the entry. An entry in
decisions.md is decided by being there. The page is a historical record, and the code is the
authority where the two disagree.
- Write in ASD-STE100 Simplified Technical English, with no em-dashes and no en-dashes.