name: develop-adr
description: Creates an Architecture Decision Record following the Nygard format to document significant technical decisions, their context, and consequences. Use when making technical choices that affect system architecture, technology selection, or development patterns.
phase: develop
version: "2.0.0"
updated: 2026-01-26
license: Apache-2.0
metadata:
category: specification
frameworks: [triple-diamond, lean-startup, design-thinking]
author: product-on-purpose
Architecture Decision Record (ADR)
An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning — especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.
When to Use
- Making significant technical decisions that affect system architecture
- Choosing between technology options (frameworks, databases, services)
- Establishing patterns that future development should follow
- Documenting the rationale for constraints or non-obvious approaches
- Preserving institutional knowledge about past decisions
Instructions
When asked to create an ADR, follow these steps:
Assign a Number and Title
ADRs are numbered sequentially (ADR-001, ADR-002, etc.) for easy reference. The title should be a short noun phrase describing the decision, like "Use PostgreSQL for order data" or "Adopt React for frontend."
Set the Status
New ADRs start as "Proposed." After team review, they become "Accepted," "Deprecated," or "Superseded by ADR-XXX." Status changes should be tracked.
Describe the Context
Explain the circumstances that led to this decision. What problem are you solving? What forces are at play (technical constraints, team expertise, timeline, cost)? This section should help a reader who wasn't there understand why this decision was needed.
State the Decision
Clearly articulate what you decided. Use active voice: "We will use..." rather than "It was decided..." Be specific about what is and isn't included in the decision.
Document the Consequences
List the outcomes of this decision — positive, negative, and neutral. Good ADRs are honest about trade-offs. What becomes easier? What becomes harder? What new constraints or options does this create?
Output Format
Use the template in references/TEMPLATE.md to structure the output.
Quality Checklist
Before finalizing, verify:
Examples
See references/EXAMPLE.md for a completed example.
1---2name: develop-adr3description: <!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->4---5
6<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
7---
8name: develop-adr
9description: Creates an Architecture Decision Record following the Nygard format to document significant technical decisions, their context, and consequences. Use when making technical choices that affect system architecture, technology selection, or development patterns.
10phase: develop
11version: "2.0.0"
12updated: 2026-01-26
13license: Apache-2.0
14metadata:
15 category: specification
16 frameworks: [triple-diamond, lean-startup, design-thinking]
17 author: product-on-purpose
18---
19# Architecture Decision Record (ADR)
20
21An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning — especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.
22
23## When to Use
24
25- Making significant technical decisions that affect system architecture
26- Choosing between technology options (frameworks, databases, services)
27- Establishing patterns that future development should follow
28- Documenting the rationale for constraints or non-obvious approaches
29- Preserving institutional knowledge about past decisions
30
31## Instructions
32
33When asked to create an ADR, follow these steps:
34
351. **Assign a Number and Title**
36 ADRs are numbered sequentially (ADR-001, ADR-002, etc.) for easy reference. The title should be a short noun phrase describing the decision, like "Use PostgreSQL for order data" or "Adopt React for frontend."
37
382. **Set the Status**
39 New ADRs start as "Proposed." After team review, they become "Accepted," "Deprecated," or "Superseded by ADR-XXX." Status changes should be tracked.
40
413. **Describe the Context**
42 Explain the circumstances that led to this decision. What problem are you solving? What forces are at play (technical constraints, team expertise, timeline, cost)? This section should help a reader who wasn't there understand why this decision was needed.
43
444. **State the Decision**
45 Clearly articulate what you decided. Use active voice: "We will use..." rather than "It was decided..." Be specific about what is and isn't included in the decision.
46
475. **Document the Consequences**
48 List the outcomes of this decision — positive, negative, and neutral. Good ADRs are honest about trade-offs. What becomes easier? What becomes harder? What new constraints or options does this create?
49
50## Output Format
51
52Use the template in `references/TEMPLATE.md` to structure the output.
53
54## Quality Checklist
55
56Before finalizing, verify:
57
58- [ ] Title is a short, descriptive noun phrase
59- [ ] Status is clearly indicated (Proposed/Accepted/Deprecated/Superseded)
60- [ ] Context explains why this decision was needed
61- [ ] Decision is stated clearly in active voice
62- [ ] Consequences include both positive and negative outcomes
63- [ ] ADR can stand alone without requiring other documents
64
65## Examples
66
67See `references/EXAMPLE.md` for a completed example.
majiayu000