82 lines
4.3 KiB
Markdown
82 lines
4.3 KiB
Markdown
# Decisions
|
|
|
|
How to keep a project's architecture decision records (ADR) and design decision records (DDR) in one log, so a decision made once is followed in every later task. Read this file only when you add, accept, reject, or supersede a decision. To follow decisions, the index is enough ([SKILL.md](../SKILL.md)).
|
|
|
|
Contents: Layout · When to record · Writing a record · Changing a decision · Precedence
|
|
|
|
## Layout
|
|
|
|
`docs/decisions/` at the monorepo root holds one file per decision and one index. Create both with the first decision.
|
|
|
|
```
|
|
docs/decisions/
|
|
README.md # the index
|
|
0001-zod-instead-of-valibot.md
|
|
0002-island-components-over-native-elements.md
|
|
```
|
|
|
|
The index lists only live decisions, one line each. The line is the rule itself, one imperative sentence with its scope, so a task follows it without opening the record. Open a record only to change it, or when a case isn't clear from its line.
|
|
|
|
```markdown
|
|
# Decisions
|
|
|
|
## Design (DDR)
|
|
- 0002 Build UI with island components; never use native interactive elements (`button`, `input`, `select`, `textarea`, `a`) in features or apps.
|
|
|
|
## Architecture (ADR)
|
|
- 0001 Validate with Zod instead of valibot in every project.
|
|
|
|
## Proposed
|
|
- 0003 architecture: Load the reviews part only on interaction, on every product page.
|
|
```
|
|
|
|
- The area is where the rule applies: design for UI, island, tokens, copy, and UX; architecture for everything else.
|
|
- Keep a line under about 30 words. A rule that needs more is two decisions, or its detail belongs in the record.
|
|
- Rejected and superseded decisions leave the index. Their files stay, with their status, as history.
|
|
|
|
## When to record
|
|
|
|
- The user states a lasting rule for the project: "always", "never", "use X instead of Y", "from now on". Write it as `Accepted`, because the user decides, and say so in one line: "Recorded as decision 0004."
|
|
- You make a choice that is hard to undo, adds a dependency, deviates from this skill, or sets a pattern beyond the current task. Write it as `Proposed` and list it in the PR's plan. It binds nothing until the user accepts it.
|
|
|
|
Don't record a one-off instruction for the current task, a rule this skill already states, or detail that one file shows. When you can't tell whether an instruction is lasting, follow it for the task and ask in your final message whether to record it.
|
|
|
|
Before you propose a decision, search `docs/decisions/` for its topic, so you don't propose again what the user rejected or superseded.
|
|
|
|
## Writing a record
|
|
|
|
Number: the highest number in the folder plus 1, four digits. File name: `NNNN-<kebab-title>.md`. Keep a record under about 25 lines.
|
|
|
|
```markdown
|
|
# 0002 Island components over native elements
|
|
|
|
Status: Accepted · Area: design · Date: 2026-10-04 · Decided by: user
|
|
|
|
## Context
|
|
Why the decision came up, in one to three sentences.
|
|
|
|
## Decision
|
|
The rule in the imperative, with its scope and exceptions.
|
|
|
|
## Alternatives
|
|
- The option, and why it lost. "Not discussed" when the user gave none.
|
|
|
|
## Consequences
|
|
What becomes easier or harder, and which existing code doesn't follow it yet.
|
|
```
|
|
|
|
- `Decided by` is `user` or `agent`. Add `Supersedes: NNNN` to the status line when it applies.
|
|
- Add the record's line to its area in the index, or to Proposed.
|
|
- Existing code that breaks a new decision is debt. List it under Consequences, and fix it only when the user asks or a task touches that code.
|
|
|
|
## Changing a decision
|
|
|
|
- Accept: set `Status: Accepted`, and move the line from Proposed to its area.
|
|
- Reject: set `Status: Rejected`, add the reason in one line under Decision, and remove the line from the index.
|
|
- Supersede: never rewrite the body of an accepted record. Write a new record with `Supersedes: NNNN`, set the old one to `Status: Superseded by MMMM`, and replace the old index line with the new one. A typo fix or clearer wording that keeps the rule is fine in place.
|
|
- When the user asks for something an accepted decision forbids, name the decision and ask: supersede it, or make a one-time exception. Record only a supersede.
|
|
|
|
## Precedence
|
|
|
|
An accepted decision overrides this skill's rules and your own judgment. A proposed decision overrides nothing. When a decision would break a rule that blocks a merge ([SKILL.md](../SKILL.md#7-review-stance)), such as tokens readable by JavaScript, state the risk once before you record it, and write the risk under Consequences.
|