openmove/engineering-design-playbook / .agents/skills/design-docs-template/new-adr
docs-template-new-adr
VerifiedScaffolds the next numbered ADR from the MADR template (minimal by default), status proposed, and updates the ADR index. Use when a decision is settled and must be recorded immutably. Invoked via design-docs-template.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.1 KB |
SKILL.md
View on GitHub---
name: docs-template-new-adr
description: >-
Scaffolds the next numbered ADR from the MADR template (minimal by default),
status proposed, and updates the ADR index. Use when a decision is settled and
must be recorded immutably. Invoked via design-docs-template.
---
# new-adr — record one decision
**What:** Next `docs/adr/NNNN-slug.md` from MADR + index row, status `proposed`.
**When:** The choice is made (often after an RFC); you need a permanent record.
**Not:** Comparing designs still in flight (that is **new-rfc**) or closing a whole RFC (**close-loop**, which may call this).
## Process
### 1. Locate templates
- Default: `docs/adr/adr-template-minimal.md`
- Full trade-off write-up: `docs/adr/adr-template.md` if they ask
- Read `docs/adr/README.md` for numbering and “do not edit 0000 / upstream templates”
If `docs/adr/` is missing, stop and suggest **bootstrap**.
### 2. Collect inputs
Ask what is missing:
- **Decision title** (short, imperative or noun phrase per repo style) and **slug**
- **Minimal vs full** template (default minimal)
- **Context one-liner** if they already have it (optional — else leave template placeholders)
- **Supersedes ADR-NNNN?** optional
### 3. Pick NNNN
List `docs/adr/[0-9]*.md`. Keep `0000` as the MADR meta-ADR; next id = max of numeric ids + 1 (if only `0000`, next is `0001`).
### 4. Write the file
- Copy chosen template to `docs/adr/NNNN-<slug>.md`
- Status: `proposed`
- Fill title; leave options/consequences as template structure unless the user dictated the outcome in this turn
- If superseding: set old ADR status to `superseded by ADR-NNNN` only when they confirmed the old id
### 5. Index
Add a row to `docs/adr/README.md`. Do **not** mark arc42 §9 updated until **close-loop** or they ask — linking from §9 on acceptance is a separate step.
### 6. Hand off
Report path, id, status. Remind: accepted ADRs are never rewritten; a later change needs a new ADR.
## Hard rules
- Do not edit `adr-template.md`, `adr-template-minimal.md`, or rewrite accepted ADRs.
- One ADR = one decision. Split if they bundled several.
- Prefer empty honest placeholders over invented rationale.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |