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:

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

1. 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.
2. 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.
3. 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.
4. 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.
5. Write the draft to .agents/drafts/kd/{YYYY-MM-DD}-{slug}.md, in the draft shape. Status is Proposed.
6. Report in chat: the one-line recommendation, its cost, and the draft's path. Then stop and wait.
7. 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.