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:

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:

# ADR-NNN: <Topic>

**The call: <the decision in one directive sentence — what we will do, written so a reader who stops here still knows what was decided>.**

## 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.

Why the one-line call sits above the Status header. An ADR is a decision artifact and its reader is usually deciding or auditing a decision, so the decision must be readable before the reasoning — the same requirement /draft-rfc enforces with its executive-summary block. It is ONE line here rather than that skill's multi-bullet block because an ADR is already short and Nygard's Decision / Consequences sections carry the detail a page later; five summary bullets atop a one-page document is padding, and padding is the same disease as burying. If an ADR ever grows long enough that the call is not visible on the first screen, it has outgrown this format — use the RFC-sized block, or reconsider whether it should have been an RFC.

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
• One-line bolded The call sits immediately under the title, above Status
• 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