# Record Decision

> Record a **decision** — the "because" that cites one or more design briefs (each of which frames a problem brief). Three-hop traceability: why do we do this? → this design → because of this problem. Use this when the user says things like "record the decision", "capture what we decided", "let's log this decision", "add a decision", or after a design brief has been accepted and the user wants to capture the downstream commitment. Decisions are written by humans (with agent help); briefs are written by agents. Keep that boundary firm. A decision cannot be `accepted` while any of its `derived_from` design briefs is not accepted — this skill invokes `vault_check_transition` to enforce that before writing.

- Skill: `iopsystems/record-decision` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iopsystems/record-decision`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iopsystems/record-decision/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: iopsystems (https://skillmd.com/u/iopsystems)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/iopsystems/record-decision

---


# Record decision

You are recording a **decision** in the knowledge-iop vault. A
decision cites the design briefs that informed it via `derived_from:`.
Briefs are the *what*; decisions are the *because*.

## Before writing — verify the chain is ready

1. Ask the user which design briefs this decision is derived from.
   At least one; usually one, occasionally more.
2. For each design-brief id, call `vault_search` (or `vault_edges`)
   to confirm it exists and get its status.
3. If any is not `accepted`, stop and tell the user:
   "decisions cannot be accepted while any `derived_from` design
   brief is not accepted." Offer options:
   - Accept the design brief first (via `vault_check_transition`
     pre-flight + a status-change commit).
   - Record this decision as `status: draft` for now and promote to
     `accepted` once the briefs land.
4. For each design brief, also surface its `frames:` problem brief
   so the user can confirm the full chain: problem → design →
   decision.

## Frontmatter shape

```yaml
---
id:            <YYYY-MM-DD>-<short-slug>
type:          decision
status:        accepted                   # or draft if waiting on briefs
author:        <person>
created:       <YYYY-MM-DD>
derived_from:  [<design-brief-id>, ...]   # REQUIRED, at least one
arc:           <arc-id | omit>
scopes:        [<scope-id>, ...]
relates_to:    [<id>, ...]
---
```

`derived_from:` is required. Without it, this isn't a decision —
it's an opinion. If the user truly can't name a design brief, push
back once; if they insist, the right thing is usually a session note
or discussion, not a decision.

## Filename

Write to `decisions/<id>.md`. The decisions directory is append-only
in spirit — do not edit prior decisions.

## Body

A decision is short by design. Usually under a page. Cover:

1. **What we decided.** One clear sentence.
2. **Why — grounded in the briefs.** Name the design brief, then in
   one paragraph explain why its approach is the one being adopted.
   Cite the framed problem for context.
3. **Scope of commitment.** What does this decision commit us to,
   for whom, for how long? If the commitment is revisitable,
   under what condition.
4. **What we decided against.** If the design brief considered
   alternatives, one line per rejected alternative and why.
5. **Consequences to watch.** What should change because of this
   decision. What will go wrong if it goes wrong.

If the decision is long, it's probably actually a design brief.
Decisions cite; they don't elaborate.

## Pre-flight the transition

Before committing with `status: accepted`, invoke
`vault_check_transition` with the decision's id and
`new_status: accepted` to catch:

- derived-from briefs not yet accepted
- any other cascading violations

If blockers come back, address them first. If you write the file
before transitioning, use `status: draft` and commit; promote later.

## Drafting workflow

1. Verify the chain (above). Do not proceed past a blocker.
2. Draft the decision. Short.
3. Propose frontmatter + body as a diff.
4. Write on approval.
5. Commit: `git add decisions/<id>.md && git commit -m "Decide:
   <one-line>"`.

## Reversing a decision

Decisions can be `reversed` (not deleted). If the user asks to undo
a previous decision:

1. Do not edit the original. It stays in history.
2. Write a new decision that `supersedes: <old-id>` with
   `status: accepted`, explaining what changed.
3. Update the original's frontmatter: `status: reversed`,
   `superseded_by: <new-id>`. Commit that edit separately.

The trail shows both the original and the reversal — which is the
point of an append-only decision log.

## Boundary: agents vs humans

Per SCHEMA.md: "Agents write briefs. Humans (with agent help) write
decisions. Keep that boundary firm."

When this skill runs:
- You draft the decision based on the conversation and briefs.
- The user is the one committing. Present the diff; they approve.
- If the user asks the agent to pick the decision, push back once:
  "decisions are a commitment; you should be the one making it.
  I can draft it for your review."

## Do not

- Do not write a decision without `derived_from`. Refuse politely.
- Do not edit a prior decision. Supersede + reverse instead.
- Do not expand a decision into design-brief territory. Cite the
  brief; let the reader click through.