adr

Name: adr
Author: ncklrs

116installs3forks

How to install adr?

ncklrs/startup-os-skills/adr

$npx -y skills add ncklrs/startup-os-skills --skill adr

Installs into the current project.

Summary

Expert Architecture Decision Record (ADR) creation and lifecycle management

Files · 1

View on GitHub

SKILL.md

1	# Architecture Decision Records
2
3	Expert guidance for creating and managing Architecture Decision Records based on Olaf Zimmermann's research and the MADR (Markdown Architectural Decision Records) methodology.
4
5	## How This Skill Works
6
7	When invoked, this skill guides you through the full ADR lifecycle:
8
9	1. Readiness assessment — Evaluate whether a decision is ready to be recorded (START criteria)
10	2. Creation — Write well-structured ADRs using the MADR template with anti-pattern avoidance
11	3. Quality evaluation — Check completeness using the ECADR "Definition of Done" criteria
12	4. Lifecycle management — Maintain ADR logs, supersede outdated records, track decision status
13
14	## Core Philosophy
15
16	"Don't decide too early, this harms flexibility. Don't decide too late either."
17
18	ADRs function as decision journals — not blueprints or policies. They capture the rationale behind architecturally significant choices: the problem context, the alternatives considered, the criteria applied, and the consequences accepted. Good ADRs are executive summaries that balance tradeoffs, not sales pitches for a predetermined outcome.
19
20	## When to Use This Skill
21
22	- Creating a new ADR for an architectural decision
23	- Evaluating whether a decision is ready to be recorded
24	- Reviewing an existing ADR for completeness and quality
25	- Writing or customizing a MADR template for a project
26	- Assessing whether a requirement is architecturally significant
27	- Managing an ADR log (superseding, deprecating, linking decisions)
28	- Training teams on ADR best practices
29
30	## Command Modes
31
32	\| Argument \| Action \|
33	\|----------\|--------\|
34	\| `create` \| Walk through creating a new ADR interactively \|
35	\| `review` \| Evaluate an existing ADR against quality criteria \|
36	\| `check-ready` \| Assess decision readiness using START criteria \|
37	\| `check-done` \| Assess ADR completeness using ECADR criteria \|
38	\| `template` \| Output a blank MADR template ready to fill in \|
39	\| `list` \| Help organize and maintain an ADR log \|
40	\| (no args) \| General ADR guidance based on context \|
41
42	## The MADR Template (Quick Reference)
43
44	```markdown
45	# ADR-NNNN: [Short Title Describing Decision]
46
47	## Status
48	[proposed \| accepted \| deprecated \| superseded by ADR-XXXX]
49
50	## Date
51	YYYY-MM-DD
52
53	## Decision Makers
54	[Who made or approved this decision]
55
56	## Context and Problem Statement
57	[1-3 paragraphs: What is the issue? Why does it matter?
58	Frame as a question when possible.]
59
60	## Decision Drivers
61	- [Driver 1: quality attribute, business constraint, or technical concern]
62	- [Driver 2]
63	- [Driver 3]
64
65	## Considered Options
66	1. [Option A — the chosen option]
67	2. [Option B]
68	3. [Option C]
69
70	## Decision Outcome
71	Chosen option: "[Option A]", because [justification referencing decision drivers].
72
73	### Consequences
74	- Good, because [positive consequence]
75	- Good, because [another benefit]
76	- Bad, because [accepted tradeoff]
77	- Bad, because [known limitation]
78
79	## Pros and Cons of Options
80
81	### Option A
82	- Good, because [advantage]
83	- Bad, because [disadvantage]
84
85	### Option B
86	- Good, because [advantage]
87	- Bad, because [disadvantage]
88
89	### Option C
90	- Good, because [advantage]
91	- Bad, because [disadvantage]
92
93	## Validation
94	[How will we verify this decision works? Code review, design review,
95	architectural fitness function, spike, etc.]
96
97	## More Information
98	[Links to related ADRs, RFCs, spikes, or external references.
99	Note confidence level and planned review date.]
100	```
101
102	## Key Frameworks
103
104	### START — Definition of Ready
105	Before writing an ADR, confirm all five criteria:
106	- Stakeholders known and available
107	- Timing is the Most Responsible Moment
108	- Alternatives identified (minimum two)
109	- Requirements and context documented
110	- Template selected and instantiated
111
112	### ECADR — Definition of Done
113	Before marking an ADR as accepted, confirm all five criteria:
114	- Evidence that the design will work
115	- Criteria applied to compare at least two alternatives
116	- Agreement from relevant stakeholders
117	- Documentation captured and shared
118	- Realization and review plan scheduled
119
120	### ASR Test — Architectural Significance
121	A requirement warrants an ADR when it scores on these criteria:
122	- High business impact or risk
123	- Critical stakeholder concern
124	- Quality-of-service deviation from current architecture
125	- External dependency that is unpredictable or uncontrollable
126	- Cross-cutting concern affecting multiple components
127	- First-of-a-kind implemen

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

adr

116installs3forks

View on GitHub

How to install adr?

ncklrs/startup-os-skills/adr

$npx -y skills add ncklrs/startup-os-skills --skill adr

Installs into the current project.

Summary

Expert Architecture Decision Record (ADR) creation and lifecycle management

Files · 1

View on GitHub

SKILL.md

1	# Architecture Decision Records
2
3	Expert guidance for creating and managing Architecture Decision Records based on Olaf Zimmermann's research and the MADR (Markdown Architectural Decision Records) methodology.
4
5	## How This Skill Works
6
7	When invoked, this skill guides you through the full ADR lifecycle:
8
9	1. Readiness assessment — Evaluate whether a decision is ready to be recorded (START criteria)
10	2. Creation — Write well-structured ADRs using the MADR template with anti-pattern avoidance
11	3. Quality evaluation — Check completeness using the ECADR "Definition of Done" criteria
12	4. Lifecycle management — Maintain ADR logs, supersede outdated records, track decision status
13
14	## Core Philosophy
15
16	"Don't decide too early, this harms flexibility. Don't decide too late either."
17
18	ADRs function as decision journals — not blueprints or policies. They capture the rationale behind architecturally significant choices: the problem context, the alternatives considered, the criteria applied, and the consequences accepted. Good ADRs are executive summaries that balance tradeoffs, not sales pitches for a predetermined outcome.
19
20	## When to Use This Skill
21
22	- Creating a new ADR for an architectural decision
23	- Evaluating whether a decision is ready to be recorded
24	- Reviewing an existing ADR for completeness and quality
25	- Writing or customizing a MADR template for a project
26	- Assessing whether a requirement is architecturally significant
27	- Managing an ADR log (superseding, deprecating, linking decisions)
28	- Training teams on ADR best practices
29
30	## Command Modes
31
32	\| Argument \| Action \|
33	\|----------\|--------\|
34	\| `create` \| Walk through creating a new ADR interactively \|
35	\| `review` \| Evaluate an existing ADR against quality criteria \|
36	\| `check-ready` \| Assess decision readiness using START criteria \|
37	\| `check-done` \| Assess ADR completeness using ECADR criteria \|
38	\| `template` \| Output a blank MADR template ready to fill in \|
39	\| `list` \| Help organize and maintain an ADR log \|
40	\| (no args) \| General ADR guidance based on context \|
41
42	## The MADR Template (Quick Reference)
43
44	```markdown
45	# ADR-NNNN: [Short Title Describing Decision]
46
47	## Status
48	[proposed \| accepted \| deprecated \| superseded by ADR-XXXX]
49
50	## Date
51	YYYY-MM-DD
52
53	## Decision Makers
54	[Who made or approved this decision]
55
56	## Context and Problem Statement
57	[1-3 paragraphs: What is the issue? Why does it matter?
58	Frame as a question when possible.]
59
60	## Decision Drivers
61	- [Driver 1: quality attribute, business constraint, or technical concern]
62	- [Driver 2]
63	- [Driver 3]
64
65	## Considered Options
66	1. [Option A — the chosen option]
67	2. [Option B]
68	3. [Option C]
69
70	## Decision Outcome
71	Chosen option: "[Option A]", because [justification referencing decision drivers].
72
73	### Consequences
74	- Good, because [positive consequence]
75	- Good, because [another benefit]
76	- Bad, because [accepted tradeoff]
77	- Bad, because [known limitation]
78
79	## Pros and Cons of Options
80
81	### Option A
82	- Good, because [advantage]
83	- Bad, because [disadvantage]
84
85	### Option B
86	- Good, because [advantage]
87	- Bad, because [disadvantage]
88
89	### Option C
90	- Good, because [advantage]
91	- Bad, because [disadvantage]
92
93	## Validation
94	[How will we verify this decision works? Code review, design review,
95	architectural fitness function, spike, etc.]
96
97	## More Information
98	[Links to related ADRs, RFCs, spikes, or external references.
99	Note confidence level and planned review date.]
100	```
101
102	## Key Frameworks
103
104	### START — Definition of Ready
105	Before writing an ADR, confirm all five criteria:
106	- Stakeholders known and available
107	- Timing is the Most Responsible Moment
108	- Alternatives identified (minimum two)
109	- Requirements and context documented
110	- Template selected and instantiated
111
112	### ECADR — Definition of Done
113	Before marking an ADR as accepted, confirm all five criteria:
114	- Evidence that the design will work
115	- Criteria applied to compare at least two alternatives
116	- Agreement from relevant stakeholders
117	- Documentation captured and shared
118	- Realization and review plan scheduled
119
120	### ASR Test — Architectural Significance
121	A requirement warrants an ADR when it scores on these criteria:
122	- High business impact or risk
123	- Critical stakeholder concern
124	- Quality-of-service deviation from current architecture
125	- External dependency that is unpredictable or uncontrollable
126	- Cross-cutting concern affecting multiple components
127	- First-of-a-kind implemen

People who liked this also viewed

6 picks

Type