new-adr

name	new-adr
description	Create a new Architecture Decision Record (ADR) for signal-go. Use this skill whenever the user mentions writing an ADR, filing an ADR, "should this have an ADR", adding a new decision record, or when any CLAUDE.md rule triggers an ADR (new Go dep, store format change, security trade-off, new protocol, new package). Also invoke proactively when the user is about to make a change that the CLAUDE.md "When to ask first" list covers.
user-invocable	true

Create a new ADR

ADRs are how signal-go records decisions that future contributors could reasonably second-guess. They're cheap to write and expensive to skip — a missed ADR means the same argument gets re-litigated in code review six months later.

Step 1 — Find the next number

Read the last row of docs/adr/README.md to find the highest existing ADR number, then add 1. The number must be zero-padded to 4 digits (e.g. 0038).

tail -5 docs/adr/README.md

If the user is superseding an existing ADR, note which one — you'll link back to it in the Consequences section.

Step 2 — Draft the title

A good ADR title is short (≤ 60 chars), uses a noun phrase, and says what the decision is, not just the problem. "SQLite-backed store (modernc.org/sqlite)" is better than "Database for key storage".

Confirm the title with the user before creating the file.

Step 3 — Create the file

Path: docs/adr/NNNN-kebab-case-title.md

Use this exact template:

# ADR NNNN — [Title]

- Status: Proposed
- Date: YYYY-MM-DD

## Context

[Why is this decision being made? What forces are at play? What
constraints exist? Keep this factual — describe the situation, not
the solution.]

## Decision

[What are we doing? Be concrete. If there were alternatives considered,
briefly describe them and why this option won.]

## Consequences

**Pro** — [benefit]

**Pro** — [benefit]

**Con** — [drawback or trade-off]

[If this supersedes an ADR, add:]
Supersedes [ADR NNNN](./NNNN-title.md).

Fill in today's date for the Date field. Status starts as "Proposed"; change it to "Accepted" when the PR merges.

Step 4 — Update docs/adr/README.md

Add a row to the table:

| NNNN | [Title]                   | Proposed |

Keep the table sorted by ADR number (ascending). The status in the table should match the file.

Step 5 — Link from the relevant code

The CLAUDE.md "What goes where" table specifies which code/docs to link from. Common cases:

Change	Link target
New Go dep	go.mod comment or ADR 0002 table
New internal/ package	package doc.go
Public pkg/signal change	function/type doc comment
Wire format change	internal/store/ file header
Security/crypto change	docs/security.md or docs/security/threat-model.md

Add a reference like // Design: ADR NNNN or a link in the relevant doc.

Step 6 — Help draft the content

Offer to help the user write the Context and Decision sections if they haven't already. Good context sections:

• Name the concrete problem, not the abstract category
• Call out relevant existing ADRs that this interacts with
• Include a short note on why the obvious alternative was rejected (even if it's just "we considered X but Y")

Good decision sections:

• Say what not just why
• Name specific packages, files, or protocols where relevant
• If there were multiple options, number them and say which won

CLAUDE.md triggers requiring an ADR

These changes always need an ADR per CLAUDE.md:

• Adding any runtime Go dependency → must also update ADR 0002 table
• Changing the on-disk store wire format → ADR 0012 + bump format version
• New network endpoint or capability flag
• Any security check loosened (validation order, constant-time, error path)
• Backwards-compatibility break in pkg/signal after the first tagged release
• New cryptographic primitive or protocol

$ARGUMENTS