# New Adr

> Creates a new Architecture Decision Record (ADR) in docs/decisions/. Auto-numbers the file based on the highest existing ADR number. Use when asked to "create an ADR about X", "record the decision to use X", "document the architecture decision for X", "add to the decision log", "write an ADR for X", or "record why we chose X".

- Skill: `omarsaleh506/new-adr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add omarsaleh506/new-adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/omarsaleh506/new-adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OmarSaleh506 (https://skillmd.com/u/omarsaleh506)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/omarsaleh506/new-adr

---


# new-adr

Creates a properly-numbered ADR file in `docs/decisions/`.

## Steps

1. **Determine the next number**
   - List all files matching `docs/decisions/[0-9]*.md`
   - Extract the leading `NNNN` from each filename
   - Take the highest number and add 1 (pad to 4 digits)
   - If no files exist yet, start at `0002` (0001 is the bootstrap ADR)

2. **Build the filename**
   - Slugify the decision title: lowercase, spaces → hyphens, remove
     punctuation
   - Filename: `docs/decisions/NNNN-<slug>.md`

3. **Write the ADR** using the template below, filled in with the decision
   context the user provided. Leave `[date]` as today's ISO date and
   `[author]` as "Claude Code" unless the user specifies otherwise.

4. **Update the architecture doc** (optional)
   - If `docs/architecture.md` has a "Key Design Decisions" section,
     append a link row. If the section doesn't exist, skip this step.

5. **Report** the file path created and the ADR's title + number.

## ADR Template

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

- **Status:** Draft
- **Date:** [YYYY-MM-DD]
- **Author:** [author]

## Context

_What situation or requirement forced this decision?_

## Decision

_What was decided, stated directly: "We will ..."_

## Consequences

- **Good:** ...
- **Trade-off:** ...
- **Risk:** ...
```

## Rules

- **Never overwrite** an existing ADR — create a new "Supersedes ADR-XXXX" one instead.
- **Status is "Draft"** unless the user explicitly says it's accepted.
- Keep ADRs short. If context needs more than 150 words, summarise.