draft-adr

---
name: draft-adr
description: >-
  Draft a Minsky ADR (Architecture Decision Record) using the Michael-Nygard
  format with sequential numbering in docs/architecture/adr-NNN-<slug>.md.
  Use when committing to one architectural choice among alternatives where
  future readers will ask "why this and not that?" — single decisions, not
  multi-phase proposals.
user-invocable: true
---

# Draft an ADR

Concise authoring path for an Architecture Decision Record. ADRs capture one decision per doc, are numbered sequentially, live in the repo next to the code, and are immutable after acceptance (changes happen by writing a new numbered ADR that supersedes the old).

## Arguments

Required: the decision being recorded. A short phrase naming the architectural choice (e.g., `/draft-adr persistence provider abstraction`, `/draft-adr agent identity model`).

## When to use this skill vs alternatives

- **Use `/draft-adr`** when: one architectural decision with alternatives weighed, no multi-phase roadmap, no cross-cutting strategic direction.
- **Use `/draft-rfc`** instead when: proposing a direction with phases, multiple sub-decisions, or strategic alternatives that need broader discussion. RFCs go to Notion; ADRs stay in the repo.

See `documentation-taxonomy.mdc` for the full taxonomy.

## The Michael-Nygard format

Four sections, in order:

1. **Status** — Proposed / Accepted / Superseded / Deprecated.
2. **Context** — what's the problem; why is a decision needed; what constraints apply.
3. **Decision** — what we're going to do (in active voice, present tense: "We will use X").
4. **Consequences** — what becomes easier; what becomes harder; what's now committed.

ADRs are concise: 1-2 pages typically. If you can't fit the decision into two pages, it's probably an RFC.

## Process

### 1. Confirm ADR scope (not RFC)

If you're tempted to write phases, roadmaps, or "alternative directions weighed at a strategic level," redirect to `/draft-rfc`. ADRs answer "what did we decide here, and why" — not "what's our long-term direction."

### 2. Find the next number

List existing ADRs:

```bash
ls docs/architecture/adr-*.md | sort
```

Determine the maximum existing `adr-NNN` number and add one. Zero-pad the result to three digits. For example, if the highest existing file is `adr-009-foo.md`, the next is `adr-010-<slug>.md`. Do NOT hardcode an expected number — always compute it from the directory listing, because other in-flight branches may have advanced the sequence.

### 3. Choose the slug

Lower-case, hyphenated, descriptive. Examples: `persistence-provider-architecture`, `agent-identity`, `in-band-review-semantics`. Keep it under ~50 characters.

The file path becomes `docs/architecture/adr-NNN-<slug>.md`.

### 4. Research the context

Before drafting:

- `mcp__minsky__memory_search` for prior thinking on the decision
- `mcp__minsky__tasks_search` for related tasks
- Read sibling ADRs (`docs/architecture/adr-*.md`) for tone and depth precedent
- Identify the alternatives that were considered, even briefly — context section should acknowledge them

### 5. Draft the ADR

Use this skeleton:

```markdown
# ADR-NNN: <Topic>

## Status

Proposed

## Context

<Concrete problem statement. Why does this decision need making? What constraints apply? What alternatives were considered?>

## Decision

We will <do X>. <Optionally one paragraph elaborating mechanism.>

## Consequences

<What becomes easier. What becomes harder. What's now committed. What follow-ups this implies.>

## Cross-references

- Related ADRs: ADR-002, ADR-006
- Related tasks: mt#NNNN
- Memory entries: <ids>
```

Keep prose tight. Don't pad consequences with restatements of the decision; consequences are what changes about the future, not a summary of the past.

### 6. Place + commit in a session

ADRs are repo-versioned code changes. Land them via the session workflow:

- Start a session for the ADR's parent task (or a dedicated task if the ADR is the entire deliverable)
- Write the file in the session workspace
- Tests aren't required for ADRs themselves (they're documents), but if the ADR codifies behavior that should be tested, file a sibling task for the test work
- Commit + push + PR through the standard convergence path

### 7. Status transitions

- **Proposed** when first committed. Discussion happens via PR review.
- **Accepted** once the PR merges (the merge IS the acceptance signal — git history is the canonical lifecycle log).
- **Superseded** when a later ADR replaces it. The superseding ADR cites this ADR's number; this ADR's Status section is updated in a follow-up PR to read `Superseded by ADR-MMM`.

Don't try to delete or rewrite an Accepted ADR. The lifecycle is append-only for clarity.

## Output checklist

When the skill completes, verify:

- [ ] File at `docs/architecture/adr-NNN-<slug>.md` with the next sequential NNN
- [ ] Status header reads `Proposed`
- [ ] Context names the problem and acknowledges alternatives
- [ ] Decision is one or two sentences in active voice
- [ ] Consequences names at least one easier-thing and one harder-thing
- [ ] Cross-references section includes related ADRs / tasks / memory entries
- [ ] Committed via session workflow with PR convergence

## Examples currently in Minsky

Read these for tone and depth calibration:

- `docs/architecture/adr-002-persistence-provider-architecture.md`
- `docs/architecture/adr-005-forgebackend-subinterfaces.md`
- `docs/architecture/adr-006-agent-identity.md`
- `docs/architecture/adr-008-attention-allocation-subsystem.md`
- `docs/architecture/adr-009-in-band-review-semantics.md`

## Cross-references

- `documentation-taxonomy.mdc` — the rule that names ADR as a category and points here
- `draft-rfc/SKILL.md` — sibling skill for strategic proposals that don't fit ADR scope
- `engineering-writing/SKILL.md` — writing-craft skill (less load-bearing for ADRs than for RFCs; ADR concision constrains style)
- `implement-task/SKILL.md` — the workflow that lands the ADR via PR