---
name: kwark-decision-record
description: Write a Kwark UX decision record (docs/ux/decisions/NNNN-title.md) using Kwark's template - problem, why it must exist, alternatives, decision, why it is best, every element and its meaning, what would make us remove it, history. Use when a UI or product rule is added or changed, or when asked to record why something is the way it is.
---

# Write a Kwark decision record

Every UI decision in Kwark has a record: one numbered markdown file that says what was decided and why, so nobody has to guess later and nobody re-argues it without new evidence.

## Load first

- https://kwark.space/designSystem/method/decision-records.md
- https://kwark.space/designSystem/contributing.md (the template and the review steps)
- https://kwark.space/designSystem/foundations/principles.md (the principles a decision must name)

In the Kwark repository the records live in `docs/ux/decisions/`, one file per decision, numbered `NNNN-short-title.md`. Take the next free number; read the list first.

## Template

```markdown
# NNNN · Title

- **Status:** Accepted | Draft (rationale to confirm) | Under review | Superseded by NNNN | Removed
- **Date:** YYYY-MM-DD
- **Source:** who said or decided this, and where it is recorded (a note, a commit, a doc)

## Problem
Who has it, in what situation, in their own words where we have them.

## Why this needs to exist
What happens to the person if we do nothing.

## Alternatives we considered
At least two, with why each was not chosen.

## Decision
What we built or chose, in plain words.

## Why this is the best solution
Tied to the principles. Name the principle.

## Every element, and what it means
The screen's parts, including dots, badges, counts and colours (each also in the element register).

## What would make us remove it
The evidence that would tell us this is not helping.

## Open questions and history
Dated one-line notes; what changed and why.
```

## Rules

- **Must** name a real person and situation in the Problem. "A competitor has it" is never a problem.
- **Must** list at least two alternatives with the reason each lost.
- **Must** name the principle the decision serves (for example "the writer first", "their work is never at risk").
- **Must** say what evidence would make us remove it. A decision that cannot be removed is a liability.
- **Never** mark a draft Accepted. Only the founder (or the product owner in your team) accepts. Use "Draft (rationale to confirm)" until then.
- **Never** invent a quote, a user, a metric or research. If the source is a conversation, say so.
- **Always** add a dated line to History when the decision changes, rather than rewriting the past.
