# Decision Record Authoring

Turns a decision that has been made into a record the next reader can judge without having been in the room.

## Deliverable

One Markdown document, `decision-record.md`, in the structure set out under **Output** below. It takes the matrix from **Option Comparison & Trade-off Analysis** and feeds **Post-Decision Review**.

## Required inputs

- **The decision that was made** — in one sentence, in the words of whoever made it.
- **The context that forced it** — what was happening that made a decision necessary.
- **The alternatives that were rejected** — at least one, with who rejected it.

If any of the three is absent, stop and report it. A record written without the rejected alternatives documents an outcome rather than a decision, and the next reader cannot tell whether the option they are about to raise was already considered.

## Optional inputs

- The comparison that preceded it, if one exists — `option-comparison.md` is the expected form
- The people who were consulted, and the position each held
- Constraints that narrowed the field: budget, deadline, regulation, contract, existing systems
- The consequences the decider accepted knowingly
- The date, event or measurement that should trigger a review

Absent optional inputs are recorded as gaps in the record itself, each naming who could fill it. The record is still issued: a decision with an incomplete record is better documented than a decision with none.

## Execution

**1 — Fix the decision in one sentence.** What was decided, who decided it, and on what date. A sentence that describes a direction rather than a choice is not a decision: ask for the choice, and record the direction as context.

**2 — Write the context that forced it.** What was happening, what it was costing, and why the decision could not be deferred. Context is what a later reader needs in order to judge whether the decision still applies. Keep it to what the inputs state.

**3 — Set the status.** `proposed`, `accepted`, `superseded` or `reverted`, with the date it entered that status and who put it there. A record whose status nobody set is `proposed`, whatever the surrounding conversation implies.

**4 — Carry the alternatives across.** Each rejected alternative with what it would have given, why it was not chosen, and who rejected it. Where a comparison exists, take the reasons from it rather than restating them from memory; a reason that contradicts the comparison is a discrepancy and is flagged as one.

**5 — Record the consequences accepted.** What the decision makes harder, slower, more expensive or impossible, and who carries each one. Separate consequences accepted knowingly from consequences discovered since. A record that lists only benefits was written to defend the decision.

**6 — Name the revisit conditions.** The specific fact, event or measurement whose change should reopen this decision, and who is watching for it. A record with no revisit condition becomes permanent by neglect.

**7 — Link the record to what it binds.** The work, documents and other records this decision governs, and any record it supersedes. A superseded record is marked as superseded, never deleted.

## Output

`decision-record.md`, in this order:

- **1. Title and identifier** — the decision in one line, with the date it was made
- **2. Status** — `proposed`, `accepted`, `superseded` or `reverted`, with the date and who set it
- **3. Context** — what forced the decision, and what deferring it would have cost
- **4. Decision** — what was decided, by whom, and on what authority
- **5. Alternatives rejected** — one line each: the alternative, what it offered, why it lost, who rejected it
- **6. Consequences accepted** — what becomes harder, slower or impossible, and who carries it
- **7. Revisit conditions** — the fact, event or measurement whose change reopens this
- **8. Bound work and records** — what this decision governs, and any record it supersedes
- **9. Gaps** — what the record could not establish, and who can supply it

## Validation

The record is ready when all of these hold:

- Section 4 names a decider and an authority, not a group with no name in it
- Section 5 lists at least one rejected alternative with a reason
- Section 2 carries a status and the date it was set
- Section 6 names at least one consequence that is not a benefit
- Section 7 names a condition someone could observe, not a change of circumstances in general
- Every statement in sections 3 to 6 traces to an input, with its source

Fail the run if the record lists no rejected alternative, or if section 6 contains only benefits.

## Failure handling

- **No alternatives supplied** — stop. Report that a record with no rejected alternatives cannot be told apart from an announcement, and name who can list them.
- **The decider is not identified** — issue the record with section 4 marked `DECIDER UNRECORDED` and raise it in section 9. Record the person who reported the decision, and state plainly that they are the reporter and not the decider.
- **No access to the comparison that preceded it** — write the record from what was supplied, mark section 5 `reasons as reported`, and state that they were not checked against a comparison.
- **The stated reasons contradict the comparison** — record both, name both sources, and raise the discrepancy in section 9. Do not quietly prefer the later account.
- **Partial material** — issue the record with every section the inputs support and the rest marked `INCOMPLETE — pending <question>`. An incomplete record written now is worth more than a complete one written from memory later.