adr-create

Purpose

Create a new ADR in docs/site/adr/ that follows the conventions documented in docs/site/adr/README.md and is consistent with the ADRs already in the repo.

Usage

User invokes this skill with a short topic for the ADR. Optional args:

• --status accepted|proposed|superseded|deprecated (default: Accepted)
• --consulted "@user1, @user2" (omit if engineering-only decision)
• --supersedes 0007 (omit if not superseding)

Steps

1. Determine the next ADR number. Run the bundled helper — .claude/skills/adr-create/next-number.sh — which reads docs/site/adr/NNNN-*.md, finds the highest number, increments by 1, and zero-pads to 4 digits (prints 0001 when the dir is empty/missing). Use its output verbatim instead of re-inferring the number by hand.
2. Derive a kebab-case slug from the user's topic. Drop articles. Examples:
   • "Severity tier weights" → severity-tier-weights
   • "Use Pydantic Settings for config" → use-pydantic-settings-for-config
3. Create the file at docs/site/adr/NNNN-<slug>.md using the template below. Today's date in ISO format (YYYY-MM-DD). Deciders defaults to the current GitHub handle, resolved via gh api /user --jq .login (prepend @). Do NOT use git config user.name — that returns a display name (e.g. "Ada Lovelace") which produces an invalid @mention. If gh api fails (no auth, offline), fall back to asking the user for their GitHub handle.
4. Update the index at docs/site/adr/README.md:
   • Add a row to the "Index" table at the end — three columns: | [NNNN](NNNN-slug.md) | Title | Status |.
   • If the new ADR amends an earlier one, also append (amended by NNNN — <one-line scope>) to the amended ADR's Status cell, and add an inline > **Amendment (YYYY-MM-DD, ADR-NNNN):** blockquote at the amended section of the older ADR (the documented convention — see 0028→0024, 0031→0013, 0033→0027).
5. Stage but do not commit. The user runs git add + the commit themselves per working-agreement #1 (one functionality per commit, manual commit step).
6. Print next steps:
   • "Open docs/site/adr/NNNN-<slug>.md and fill in Context / Decision / Consequences / Alternatives."
   • "Branch suggestion: docs/adr-NNNN-<slug>" (branch names follow CONTRIBUTING's docs/<desc> prefix — the docs/site/ move changed file paths, not branch naming)
   • "PR title suggestion: docs: add ADR NNNN — <human title>"

Template

# ADR NNNN — <Human-readable title>

- **Status:** Proposed
- **Date:** YYYY-MM-DD
- **Deciders:** @<github-handle>
- **Consulted:** <optional, e.g. @product-owner, @security-team>
- **Amends:** <optional, e.g. ADR-0024 — partial override; pair with an inline amendment blockquote there>
- **Supersedes:** <optional, e.g. ADR-0007>
- **Superseded by:** <optional, e.g. ADR-0042>

## Context

<What problem are we deciding about? What forces are at play (constraints, requirements, prior decisions)? Keep to 1–3 paragraphs.>

## Decision

**<One-sentence statement of the decision, in bold.>**

<Then the details: how it works, what's in scope, what's out of scope.>

## Consequences

**Positive**
- <bullet>
- <bullet>

**Negative**
- <bullet>
- <bullet>

## Alternatives considered

- **<Alternative 1>** — rejected. <Why.>
- **<Alternative 2>** — rejected. <Why.>

## Related

- <Link to related ADRs, issues, PRs, or code paths.>

Rules

• Status field is required. Default to Accepted unless --status says otherwise. Valid values: Proposed, Accepted, Deprecated, Superseded by ADR-NNNN.
• Always render Status in title-case in the file, regardless of the CLI arg casing. The --status arg is lowercase (accepted/proposed/superseded/deprecated); map it to the title-case form before writing (accepted → Accepted, superseded → Superseded by ADR-NNNN). Deprecated needs no superseding ADR — use it when a decision is withdrawn without a replacement.
• Date is today's date in ISO format.
• Consulted, Supersedes, Superseded by are optional — include the label even if empty so future editors see the slot.
• Body sections in this exact order: Context → Decision → Consequences (with Positive/Negative subheadings) → Alternatives considered → Related.
• Slug must match the convention in docs/site/adr/README.md: lowercase, kebab-case, no leading article.
• Filename matches title: NNNN-<slug>.md where the slug is also derivable from the H1 title.
• README index is the source of truth for which ADRs exist. Always update it.
• Do not commit. Stage only. The user commits manually so they can review the diff.

Anti-patterns to avoid

• Don't reuse a number. If docs/site/adr/0005-*.md exists, the next one is 0006, never 0005a or 0005-v2.
• Don't auto-fill Decision/Context with boilerplate. Leave them as the template placeholders so the user must write the actual content.
• Don't invent a "Pending"/reservation section in the README — the index lists written ADRs only; a planned-but-unwritten decision lives as an issue, not an index row.

Test scenarios

Worked examples so the skill behaves consistently:

1. Plain decision. adr-create "use Pydantic Settings for config" with 0022 as the latest (a worked example — the real head is far past that) → helper prints 0023; create docs/site/adr/0023-use-pydantic-settings-for-config.md with the template's Status: Proposed (pass --status accepted for a decided one), today's date, Deciders resolved from gh api /user; add the index row; stage only.
2. Proposed status + consulted. adr-create "adopt OpenTelemetry" --status proposed --consulted "@product-owner" → Status: Proposed (title-cased from the lowercase arg), Consulted: @product-owner; Supersedes/Superseded-by labels left as empty placeholders.
3. Superseding an old ADR. adr-create "revised severity weights" --status accepted --supersedes 0005 → new ADR gets Supersedes: ADR-0005; remind the user (in next-steps output) to flip ADR-0005's status to Superseded by ADR-NNNN in a follow-up edit.
4. Deprecation without replacement. adr-create "retire the X seam" --status deprecated → Status: Deprecated, no Superseded-by needed.
5. Empty repo / first ADR. docs/site/adr/ missing → helper prints 0001; create 0001-<slug>.md.