ADR (Architecture Decision Record) Creator

This skill helps create comprehensive Architecture Decision Records using the AI-driven MADR template from o3-cloud/madr.

Instructions

When creating an ADR, follow these steps:

1. Ask for key information if not provided:

   • What architectural decision needs to be documented?
   • What problem are you trying to solve?
   • What options have you considered?
   • What decision was made (or needs to be made)?

2. Determine the ADR number:

   • Check for existing ADRs in docs/decisions/ or similar directories
   • Use the next sequential number (e.g., if last ADR is 0003, use 0004)

3. Create the ADR file with the naming pattern: XXXX-short-title.md (where XXXX is the zero-padded number)

4. Fill in all relevant sections of the template below, adapting based on the information provided

5. Ask clarifying questions for any sections that need more detail

ADR Template Structure

Use this template when creating ADRs:

markdown
1# {short title of solved problem and solution}
2
3## Context and Problem Statement
4
5{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.}
6
7## Decision Drivers
8
9- {decision driver 1, e.g., a force, facing concern, …}
10- {decision driver 2, e.g., a force, facing concern, …}
11- … <!-- numbers of drivers can vary -->
12
13## Considered Options
14
15- {title of option 1}
16- {title of option 2}
17- {title of option 3}
18- … <!-- numbers of options can vary -->
19
20## Decision Outcome
21
22Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
23
24### Consequences
25
26- Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
27- Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
28- … <!-- numbers of consequences can vary -->
29
30### Confirmation
31
32{Describe how the implementation of this ADR will be validated. This could include fitness functions, metrics to monitor, or specific design reviews.}
33
34## Pros and Cons of the Options
35
36### {title of option 1}
37
38{example | description | pointer to more information | …}
39
40- Good, because {argument a}
41- Good, because {argument b}
42- Neutral, because {argument c}
43- Bad, because {argument d}
44- … <!-- numbers of pros and cons can vary -->
45
46### {title of option 2}
47
48{example | description | pointer to more information | …}
49
50- Good, because {argument a}
51- Good, because {argument b}
52- Neutral, because {argument c}
53- Bad, because {argument d}
54- … <!-- numbers of pros and cons can vary -->
55
56### {title of option 3}
57
58{example | description | pointer to more information | …}
59
60- Good, because {argument a}
61- Good, because {argument b}
62- Neutral, because {argument c}
63- Bad, because {argument d}
64- … <!-- numbers of pros and cons can vary -->
65
66## More Information
67
68{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when this decision when and how the decision should be realized and if/when it should be re-visited and/or how the decision is validated. Links to other decisions and resources might here appear as well.}
69
70---
71
72## AI-Specific Extensions
73
74### AI Guidance Level
75
76{Specify how much autonomy AI agents have when implementing this decision:}
77
78- **Strict**: Follow the decision exactly as specified with minimal deviation
79- **Flexible**: Adapt implementation details while maintaining core principles
80- **Exploratory**: Research and propose alternative approaches if better options emerge
81
82{Chosen level: [strict|flexible|exploratory]}
83
84### AI Tool Preferences
85
86{Document which AI systems should execute this decision and their configuration:}
87
88- Preferred AI tools: {e.g., Claude Code, GitHub Copilot, etc.}
89- Model parameters: {e.g., temperature, max tokens, etc.}
90- Special instructions: {any specific guidance for AI tools}
91
92### Test Expectations
93
94{Define validation criteria that should be met (TDD-oriented):}
95
96- {Expected test 1}
97- {Expected test 2}
98- {Performance criteria}
99- {Quality metrics}
100
101### Dependencies
102
103{List related ADRs, system components, and external requirements:}
104
105- Related ADRs: {links to other ADRs}
106- System components: {affected modules, services, etc.}
107- External dependencies: {libraries, services, APIs, etc.}
108
109### Timeline
110
111{Implementation deadlines and review dates:}
112
113- Implementation deadline: {date}
114- First review: {date}
115- Revision triggers: {conditions that would require revisiting this decision}
116
117### Risk Assessment
118
119{Identify and assess risks:}
120
121#### Technical Risks
122
123- {Risk 1}: {description and mitigation strategy}
124- {Risk 2}: {description and mitigation strategy}
125
126#### Business Risks
127
128- {Risk 1}: {description and mitigation strategy}
129- {Risk 2}: {description and mitigation strategy}
130
131### Human Review
132
133{Specify approval requirements:}
134
135- Review required: {before implementation | after implementation | both}
136- Reviewers: {list of required approvers}
137- Approval criteria: {what needs to be verified}
138
139### Feedback Log
140
141{Post-implementation notes - fill this out after implementation:}
142
143- Implementation date: {date}
144- Actual outcomes: {what actually happened}
145- Challenges encountered: {issues faced}
146- Lessons learned: {organizational learning}
147- Suggested improvements: {for future similar decisions}

Best Practices

1. Keep it concise: ADRs should be readable in 5-10 minutes
2. Focus on "why": Explain the reasoning, not just what was decided
3. Document alternatives: Show what was considered and why it wasn't chosen
4. Update when needed: If a decision is superseded, link to the new ADR
5. Use clear language: Avoid jargon; make it accessible to future team members
6. AI sections are optional: Only fill in AI-specific sections if relevant to the decision

Example Usage

User request: "Create an ADR for choosing PostgreSQL as our database"

Your response should:

1. Find the next ADR number
2. Create a file like docs/decisions/0005-use-postgresql-for-primary-database.md
3. Fill in the template with relevant information
4. Ask for any missing details (e.g., "What other databases did you consider?", "What are the main decision drivers?")

Notes

• ADRs are typically stored in docs/decisions/ directories
• If no directory exists, ask the user where to create it
• ADRs are immutable once accepted - don't edit old ADRs, create new ones that supersede them
• The AI-specific sections are extensions to the standard MADR template for AI-assisted development