# ADR Writing Walkthrough — Learn by Doing

## Step 1: Identify a Decision Worth Documenting

**Task:** Think of a recent technical decision (yours or your team's): framework choice, database, API style, deployment model. Write one sentence: "We decided X because Y."

**Question:** Would a developer joining in 6 months benefit from knowing this? What would they assume incorrectly without it?

**Checkpoint:** You have a concrete decision and a reason someone would care.

---

## Step 2: Draft the Context Section

**Task:** For that decision, write the **Context** section. Include: (1) the problem or opportunity, (2) the options considered, (3) the constraints (time, team, tech stack).

**Question:** What did you leave out? Is there a constraint that might change and invalidate the decision?

**Checkpoint:** Context is 2–4 paragraphs; a reader can see why the decision mattered.

---

## Step 3: Write the Decision and Consequences

**Task:** Add **Decision** (one clear paragraph) and **Consequences** (at least one positive and one negative).

**Question:** Why is it valuable to document negative consequences? What happens if you only list positives?

**Checkpoint:** Decision is unambiguous; consequences are honest and useful for future readers.

---

## Step 4: Choose Status and Add Metadata

<!-- hint:buttons type="single" prompt="What status applies to your ADR?" options="A: Proposed,B: Accepted,C: Superseded" -->
<!-- hint:card type="tip" title="Use 'proposed' for open decisions; 'accepted' once the team has committed" -->

**Task:** Add a **Title** and **Status** (proposed or accepted). If the decision is already made, use accepted. Add a date.

**Question:** When would you use "proposed" vs "accepted"? What does "superseded" mean for an older ADR?

**Checkpoint:** The ADR has a clear status and can be filed in `docs/adr/`.

---

## Step 5: Link to Code (Optional but Valuable)

<!-- hint:code language="markdown" highlight="1,2" -->

**Task:** If the decision is implemented, add a line like "Implemented in `[path/to/file]`" or "See PR #123." If not yet implemented, note "To be implemented."

**Question:** Why does linking to code help? What if the code has drifted from the decision?

**Checkpoint:** Future readers can trace from ADR to implementation.

---

## Step 6: When *Not* to Write an ADR

**Task:** Consider these: (a) "We use 2 spaces for indentation." (b) "We chose React over Vue." (c) "We restarted the server to fix the bug." Which would you document as an ADR, and which would you skip?

**Question:** What's the cost of over-documenting? When does the overhead outweigh the benefit?

**Checkpoint:** You can articulate the threshold: significant, costly-to-reverse, or confusing-without-context decisions merit an ADR.