Exercise 04: write an ADR

Goal. Write an architecture decision record that would pass review. Needs. a text editor. 30 minutes.

1. Read three

Read ADR-0008 (short, one decision, consequences that name a cost), ADR-0006 (a numbered decision with proof and gates) and ADR-0012 (a decision that extends an earlier one and says so). Note the shape: Context (what was true and what hurt), Decision (what is now true, in the present tense), Consequences (what got better, what it costs, what it forbids).

2. Pick a decision

Something you actually believe the project should decide. Two starters if you need them:

• The wiki’s posters carry a verified commit; should every Mermaid diagram too?
• /api/random is no-store; should a seeded Hukam be cacheable for a day?

3. Write it

Create docs/adr/0013-<slug>.md with the frontmatter the other records use (title, description, sidebar.order), the H1 ADR-0013: …, a **Status:** proposed (YYYY-MM-DD) line, and the three headings. Keep it under a page. Then run:

make docs-check

Expected: 0 error(s) — the gate checks the frontmatter and every link you added. Open the Decisions page on a local build (make docs-dev) and find your record on the timeline with its status.

4. Decide what to do with it

If you meant it, open a pull request; the record’s status becomes accepted with the merge date. If it was practice, delete the file — but keep the habit.

Self-check