autojanet/skills/writing-adr/SKILL.md

name	description
writing-adr	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)

# 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