Adr Writing

ADR writing

A decision nobody can read was not recorded. This skill governs the shape of every file under docs/adr/ and of docs/ARCHITECTURE.md: how the file is named and retired, how the sections run, when to draw instead of explain, and what must hold before the document lands. When a change needs an ADR and what an agent owes the ADRs in force is .claude/rules/adr.md, loaded in every session; this skill does not repeat it.

Every sentence must pass one test: would someone meeting this codebase for the first time understand it without asking a question? If not, the fix belongs in the writing, not in the reader.

What an ADR is for

An ADR records an architecture-level decision: what was chosen, which alternatives were dropped and why, and what shape the code must now take. The reader is an agent or a person who will build against this decision months from now, not the author and not today's reviewer.

• Enough context, and no more. A line survives only if that reader would act differently for having read it.
• Never narrate your thinking. Deliberation, reversals, what an earlier draft said, what you worried about — none of it belongs. State the fact, the option, or the decision.
• The document never talks about itself. No "covered in the last section", no "this document does not decide X". Say the thing or delete it.
• Link outward instead of retelling. When the context lives in another ADR, a source file, a Jira issue, or an upstream document, cite it and reproduce only the sentence the reader must act on.
• Name the scope boundary once. What is out of scope gets one line — never the reasoning for deferring it, never a sketch of the deferred design.

After reading, does the reader know what was chosen, what was rejected, and what shape the code must take? If any of the three is missing it is a memo, not a decision record.

ADR file conventions

This is the definition of how an ADR file is named, titled, and retired. The one other copy is .github/instructions/adr.instructions.md, which restates the points Copilot needs because it cannot load a skill; keep the two in step.

• Filename — NNNN-title.md, for example 0001-explicit-project-prop-contract.md. The next number is the highest NNNN in docs/adr/ plus one. Numbers are never reused, so when the sequence has a gap the deleted number stays retired; git log -- docs/adr shows it.
• Title — # NNNN — <English noun phrase> (T1–T6). A Jira key goes in the sources section, never in the title. A supersede pointer goes on its own line, never in the title.
• No status field. An ADR on main is a decision in force — landing it there, merged and human-approved, is the record. A draft under review is proposed by virtue of sitting in an unmerged PR, and nothing marks it in the file. The one marker a file ever carries is reversal.
• Reversing a decision — do not edit the existing ADR's reasoning. Either keep the file and add a top line > superseded by NNNN naming what replaced it, or delete it outright. Both are allowed, and deleting is usually right once the decision and the code it described are both gone, because a retired file is then a trap a reader has to disprove. Git history holds what it said. Convert inbound references in surviving documents and source comments to plain ADR NNNN mentions.
• Partial replacement — if the new ADR replaces only part of the old, keep the old file, say so in the new ADR, and add a scoped pointer line rather than the blanket supersede marker.
• Mention form — documents and PR bodies write ADR NNNN. Source comments written before this convention say ADR-NNNN; they are corrected when the file is next edited, never swept.
• Language — the title is English; the body is Korean, with English technical terms and identifiers written as they appear in the code. An ADR that landed before this convention keeps its body language; a document is revised only when its content changes, never translated for its own sake. Section headings follow the body language, as references/document-shape.md fixes.

Phase 0 — Gather what the document must agree with

Read these before writing, so the draft does not contradict what already landed.

• The ADRs this decision touches, including the ones it supersedes or narrows, and their rows in docs/ARCHITECTURE.md.
• The source files the decision names, so identifiers in the text match the code — component names, hook names, atom names, ESLint rule ids.
• The Jira issue the work belongs to, so the sources section can cite it.
• Sibling ADRs written in the same increment, so terminology stays shared.

Phase 1 — Draft against the rule catalogues

Two reference files hold the rules, and both cite by id — "T1 violation", "fixed S4", "D2 missing".

Write the sections in the order D3 fixes: title, Summary, Context, diagrams, Decision, alternatives with the reason each was rejected, Consequences, sources, glossary.

Phase 2 — Reread as a first-time reader

Work the reread list at the end of references/writing-rules.md, then these three checks, which only a document can fail:

• A sibling document draws the same components with a different decomposition (D2), or the increment has no overview document (D4).
• A section from the D3 skeleton is missing, or a heading is in the wrong language for the body.
• A Decision item stacks several decisions that should be ### N. subsections.

Phase 3 — Adversarial review before landing

Self-review does not catch narration: the author cannot see their own. Before landing, dispatch one reviewer agent with the document path and this instruction, and fix everything it returns. Ask for defects, not a verdict:

• Padding. Every line a reader building from this would not act on — narrated thinking, restatements, deferral rationale, the document describing itself — with its line number.
• Gaps. What an agent implementing against this would still have to ask: a chosen shape with no type, no prop contract, no invariant, no file it lives in.

Verify the findings before acting — a reviewer that is wrong about the code is common. Check the file it cites.

Phase 4 — Land

• Read the document once on GitHub's rendering of the branch. A broken mermaid diagram shows there as a syntax error; no CI check catches it.
• Add or update the ADR's row in docs/ARCHITECTURE.md in the same change.
• Verify every cross-reference resolves to a file that exists, and when an ADR was retired, grep for its filename so no link points at it.