create-adr

Architecture Decision Record (ADR)

When this skill is activated, create an ADR file that documents a significant architectural decision. ADRs are short, durable records that explain why a decision was made — not just what was decided.

Clarifying Questions

Before writing the ADR, you must always ask question 1 first — never skip it, never infer it from context. Wait for the answer before continuing.

1. [Always ask] What is the exact decision being documented? State it in one sentence.

Once you have the answer to question 1, ask the remaining questions. Skip any already clearly answered by the user's response.

2. What forced this decision — what was the situation, constraint, or requirement that made it necessary?
3. Which alternatives were seriously considered (not strawmen)? What made each one worth evaluating?
4. Why was each alternative rejected in favor of the chosen option?
5. What are the most significant trade-offs or risks of the chosen option?
6. What is the current status — Proposed, Accepted, or other?
7. Are there related ADRs this connects to or supersedes?

Steps

1. Use the answers above to understand the decision; fill remaining gaps from conversation context
2. Determine the next ADR number by checking if an adr/ or docs/adr/ folder exists and what ADRs already exist there
3. Write the ADR with full context, considered alternatives, and honest consequences
4. Link it to any related ADRs if they exist

Output

Create a file at docs/adr/NNNN-{short-title}.md (e.g. docs/adr/0003-use-event-sourcing.md). Create the folder if it does not exist. Use sequential numbering starting at 0001 if no ADRs exist yet.

The file must contain exactly these sections:

Title

# NNNN. {Decision Title}

Short, active voice: "Use PostgreSQL for session storage", not "Database Decision"

Status

One of: Proposed | Accepted | Deprecated | Superseded by [NNNN](link)

Date

ISO format: YYYY-MM-DD

Context

What situation, constraint, or requirement forced this decision? Describe the forces at play — technical, organizational, or domain-specific. A reader 2 years from now must understand the pressure that made this decision necessary.

Decision

State the decision clearly in one sentence. Then explain it. Be direct: "We will use X" not "It was decided that X might be considered."

Alternatives Considered

For each alternative that was seriously evaluated:

Option: {Name}

• What it is
• Why it was considered
• Why it was rejected

Do not list strawman alternatives — only options that had real merit.

Consequences

Positive:

• What gets better as a result of this decision

Negative / Trade-offs:

• What gets worse, what we give up, what constraints this introduces

Risks:

• What could go wrong; under what circumstances would we regret this decision

Related Decisions

Links to other ADRs that are affected by or related to this one.

Rules

• One ADR per decision — if two decisions are intertwined, write two ADRs that reference each other
• ADRs are immutable once accepted: do not edit them to change the decision; instead write a new ADR with status "Superseded by" pointing to the old one
• Write for a reader who has no conversation history — all context must be in the document
• Honest consequences matter more than selling the decision: include real trade-offs
• The title must be searchable — use the technology or pattern name, not vague titles