---
name: writing-adr
description: Use when a technical decision needs to be recorded — choosing between viable approaches, establishing a convention, reversing a prior decision, or capturing any "why did we do it this way?" decision for homelab or work contexts.
---

# Writing ADRs

## Overview

ADRs capture the WHY behind decisions so future-Zoe and future-AI sessions don't re-litigate them. Not a design spec. Not an implementation plan. Just the decision record — short, factual, permanent.

## When to Write an ADR

Write one when:
- Choosing between two viable technical approaches (CNI, storage backend, auth method, DB operator)
- Establishing a convention followed everywhere (naming, secret paths, namespace strategy)
- Making a non-obvious decision that will be questioned later
- Reversing a previous decision

Don't write one for:
- Implementation details (how, not why)
- Temporary decisions
- Only one viable option existed
- Routine work following established patterns

## ADR Format (MADR-lite)

```markdown
# ADR-NNNN: [Decision Title]

**Date:** YYYY-MM-DD
**Status:** Accepted | Superseded by ADR-XXXX | Deprecated
**Deciders:** [who was involved]
**Context:** [1-3 sentences — what problem/situation required a decision]

## Decision

[1-2 sentences — what was decided]

## Alternatives Considered

| Option | Pros | Cons | Why rejected |
|--------|------|------|--------------|
| [Option A — chosen] | ... | ... | N/A — chosen |
| [Option B] | ... | ... | [reason] |
| [Option C] | ... | ... | [reason] |

## Consequences

**Good:** [what gets better]
**Bad / trade-offs:** [what gets worse or is accepted]
**Risks:** [what could go wrong]

## Links

- Related ADRs: ADR-XXXX
- Relevant docs: [BookStack or external links]
```

## Workflow

1. Identify the decision — often surfaces from a brainstorming/design session
2. Ask: "What were the real alternatives?" — list at least 2 options even if the choice felt obvious
3. Fill in the template — half a page ideal, full page max
4. Check BookStack for an existing ADR chapter in the relevant book; create one if missing
5. Find the next ADR number (check existing pages, start at ADR-0001 if none)
6. Save to BookStack using `bookstack_pages_create`
7. If this supersedes an existing ADR, update the old ADR's Status field

## BookStack Storage

**Homelab ADRs:**
- Book: Ansiblestack (ID 79) at https://wiki.ctz.fyi
- Chapter: "ADRs" (create if missing)

**Work/project ADRs:**
- Chapter "ADRs" inside the relevant project book
- Create a new book if the project doesn't have one yet

**Page name format:** `ADR-NNNN: [Decision Title]`

**API:** Use `bookstack_pages_create` with `chapter_id` (preferred) or `book_id`

## Numbering

- Sequential per context (homelab and each work project have independent sequences)
- Check BookStack for existing ADRs to determine the next number
- Start at ADR-0001 if none exist for this context

## Tone

Direct and factual. Future readers need context, not impressive prose.

- "We chose X because Y" — not "After careful consideration of all available options..."
- Include what was NOT chosen and why — that's the most valuable part
- Short beats comprehensive every time