# Decision records

> Every decision a person can see or feel gets one numbered record that says the problem, the options, why this one, and what would make us remove it.

Source: https://kwark.space/designSystem/method/decision-records

## Why Kwark writes them

Kwark is built by one founder and many agents, across Claude, Codex, Antigravity and others, often in parallel and often starting cold. A choice that lives only in a chat is lost the moment the chat ends, and the next agent will undo it in good faith. The record is how a decision survives the person who made it.

It also does a second job: writing "what would make us remove it" forces the decision to be testable. A feature that cannot be removed is a liability.

## When to write one

- Anything a person sees or feels: a screen, a control, a word, a default, a colour, a dot.
- Anything expensive to reverse: data shape, permissions, naming, anything public.
- A rule the founder states in conversation ("no glow anywhere", "3 dots means nothing").

A change without its record is not finished. That is written into `docs/ux/README.md` and into the repository's `CLAUDE.md`.

## The template

Copy `docs/ux/decisions/_template.md`. Every heading is required; "n/a" is allowed only where the decision is a rule with no screen.

```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

## 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.

## 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.
```

### What each part is for

| Part | Write | Avoid |
|---|---|---|
| Title | The decision as a plain sentence: "Issue the call sheet: numbered, frozen revisions" | A feature name: "Call sheet v2" |
| Source | The founder's words in quotes, a commit, an audit file | "Team decision" |
| Problem | The person, the situation, what they experienced | The solution in disguise |
| Alternatives | Two or more real options and why each lost | A straw man |
| Every element | Each dot, badge, count and colour with its meaning; also add them to `docs/ux/element-register.md` | "Standard UI" |
| Remove it | Observable evidence | "If users don't like it" |
| History | Dated lines, commit hashes, what a supervisor found and what was not fixed, with the reason | Rewriting earlier lines |

## How records are numbered

- **Always** take the next free four-digit number after the highest in the folder, and name the file `NNNN-short-slug.md`.
- **Never** renumber or reuse a number. Commits, code comments and other records cite them. The folder already holds two records numbered 0019, 0029, 0041 and 0043, written by parallel sessions; they stay as they are, and you cite them by number and title.
- **Always** add the record to `docs/ux/decisions/README.md`.
- A record that replaces another sets the old one to "Superseded by NNNN" and links forward. Nothing is deleted.

## Status

| Status | Means |
|---|---|
| Accepted | The founder agreed it. Build to it. |
| Draft | Built or proposed; the founder has not confirmed the rationale or the review ladder has not run. Say so in the status line. |
| Under review | Being tested against the mission (for example the writing rhythm, Decision 0008). |
| Superseded by NNNN | Replaced; read the newer one. |
| Removed | The feature is gone; the record stays so nobody brings it back by accident. |

## Four real records, summarised

### 0016 · Phone: content first, a one-line header, one FAB

**Problem.** On a phone the Outline showed a two-line header, account and comments icons, then three rows of controls before any writing; the writer's work got about 20% of the screen. **Founder's words:** "80% of the page is non-writing stuff … no breadcrumb, just a back button … comment, account and edit under one FAB at the bottom". **Rejected:** a two-line title (the story name is already known), a breadcrumb on phone (no room, and back is all a phone needs), account and comments in the header (occasional actions, not navigation). **Decision:** one 44px line (back, one-word title, labelled Menu); Comments, Quick note and Account in one floating button at the bottom corner; a screen's tools collapse so content starts by y≈120. **Remove it if** writers cannot find Comments or Account in testing. **History worth reading:** the fix round got Outline content from y≈392 to y≈222 at 375 wide and says plainly that the y≈120 goal is not met yet.

### 0020 · Issue the call sheet: numbered, frozen revisions

**Problem.** A second AD edits the sheet all night, prints it, and the crew holds a paper that no longer matches the screen; nobody can say which version went out. **Rejected:** locking the sheet when issued (stops the person fixing a call time at midnight), storing only an `issuedAt` stamp (says when, not what), jsPDF export (Latin-only; Indian names break). **Decision:** "Issue Rev N" freezes a numbered copy; the working draft stays editable and says "Matches Rev N" or "Changed since Rev N"; issued copies print, save as PDF and download as CSV. **What makes it a good record:** a full review-ladder section listing what was fixed, what was not fixed and why (two devices issuing in the same minute can still both write Rev N), and the warning that the app change must not ship before its rules.

### 0042 · Sharing by film role, in one panel, safe by default

**Problem.** An owner met three tabs, 56 permission buttons and a default of edit everything; Kwark sends no email, so nobody invited was ever told. **Founder's words:** "the sharing module UX and UI both are very very bad". **Rejected:** plain levels like a document editor (a producer thinks "the DOP", not "edit on Look Book: colour"; kept underneath as the fine-tune), restyling the grid. **Decision:** one panel; roles Reader, Actor, Co-writer, Director, Producer, Camera, Crew and Custom; new people are Readers; the request link is off until turned on; Copy invite message instead of pretending to send mail. **Remove it if** owners still choose Module by module for most people.

### 0044 · Unified breadcrumb and phase and module dropdowns

**Problem.** Write and Prepare to shoot drew breadcrumbs two different ways, one with centred menu rows. **Rejected:** a local CSS patch (leaves two systems), one mega-switcher (hides where you are). **Decision:** one `Breadcrumb` component styled only by `--k-crumb-*` tokens, one trail builder, `Home ▸ Project ▸ Phase ▾ ▸ Module ▾`, and named exceptions (the screenplay editor, the shot listing workbench, phones, Home). **Enforced by** `tests/breadcrumb.test.cjs` and `tests/design-system.test.cjs`: a record whose rule is checked by a test cannot drift.

## The element register

The dot rule from `docs/ux/how-we-decide.md`: every small thing on screen that carries meaning (a dot, a badge, a count, a colour, an edge, an icon with no label) has a row in `docs/ux/element-register.md` saying what it means, when it appears, what the person is meant to do about it, and why it earns its place. A dot with no reason is removed.

## Rules

- **Must** write or update a record for every change a person can see or feel, in the same change.
- **Must** quote the founder's own words in Source and Problem when the decision came from him.
- **Must** list at least two alternatives with the reason each lost.
- **Must** say what evidence would make us remove it.
- **Always** append dated history lines; never rewrite old ones.
- **Always** write what a supervisor found that was not fixed, and why.
- **Never** mark a record Accepted that the founder has not agreed.
- **Never** cite a principle without naming it.

**Do:** "What would make us remove it: owners still choosing Module by module for most people."

**Don't:** "What would make us remove it: negative feedback."

## AI readiness test

**Task:** You moved the "Keep a restore point" command from Edit to File. Write what the record needs.

**Give the agent:** This page, Decision 0015, the template.

**Constraint:** Do not create a new number if an existing record covers it.

**A reliable answer:**
- Adds a dated history line to 0015 rather than a new record
- Says what the writer experienced before and after
- Names the principle (one home per command)
- Updates any element or shortcut it touched
