adr-generator

Name: adr-generator
Author: girijashankarj

27stars3forks

How to install adr-generator?

girijashankarj/cursor-handbook/adr-generator

$npx -y skills add girijashankarj/cursor-handbook --skill adr-generator

Installs into the current project.

Summary

Generate Architecture Decision Records (ADRs) documenting significant technical decisions with context, options, and consequences. Use when the user asks to document an architecture decision, design choice, or technical trade-off.

Files · 1

View on GitHub

SKILL.md

1	# Skill: ADR Generator
2
3	Create Architecture Decision Records following the Michael Nygard format to document significant technical decisions.
4
5	## Trigger
6	When the user asks to document an architecture decision, record a design choice, or create an ADR.
7
8	## Prerequisites
9	- [ ] Decision to document identified
10	- [ ] Options considered (at least 2)
11	- [ ] Context and constraints understood
12
13	## Steps
14
15	### Step 1: Determine ADR Number
16	- [ ] Check existing ADRs: `ls docs/adr/ 2>/dev/null \|\| echo "no ADR directory"`
17	- [ ] Assign next sequential number: `NNNN` (e.g., `0001`, `0002`)
18	- [ ] Create directory if needed: `mkdir -p docs/adr`
19
20	### Step 2: Gather Decision Context
21	- [ ] What is the problem or need?
22	- [ ] What constraints exist? (technical, business, timeline, team)
23	- [ ] What was the trigger? (new requirement, incident, tech debt)
24	- [ ] Who are the stakeholders?
25
26	### Step 3: Document Options
27	For each option considered:
28	- [ ] Name and brief description
29	- [ ] Pros (advantages, benefits)
30	- [ ] Cons (disadvantages, risks, costs)
31	- [ ] Effort estimate
32	- [ ] Team familiarity
33
34	### Step 4: Generate ADR
35
36	```markdown
37	# ADR-NNNN: [Decision Title]
38
39	## Status
40	[Proposed \| Accepted \| Deprecated \| Superseded by ADR-XXXX]
41
42	## Date
43	YYYY-MM-DD
44
45	## Context
46	[Describe the situation, problem, or need that requires a decision.
47	Include technical and business context. What forces are at play?]
48
49	## Decision
50	[State the decision clearly in 1-3 sentences. Use active voice:
51	"We will use X for Y because Z."]
52
53	## Options Considered
54
55	### Option 1: [Name]
56	- Description: [What this option entails]
57	- Pros:
58	- [Advantage 1]
59	- [Advantage 2]
60	- Cons:
61	- [Disadvantage 1]
62	- [Disadvantage 2]
63	- Effort: [Low / Medium / High]
64
65	### Option 2: [Name]
66	- Description: [What this option entails]
67	- Pros:
68	- [Advantage 1]
69	- Cons:
70	- [Disadvantage 1]
71	- Effort: [Low / Medium / High]
72
73	### Option 3: [Name] (if applicable)
74	...
75
76	## Consequences
77
78	### Positive
79	- [Good outcome 1]
80	- [Good outcome 2]
81
82	### Negative
83	- [Trade-off 1]
84	- [Accepted risk 1]
85
86	### Neutral
87	- [Side effect that isn't clearly positive or negative]
88
89	## Related
90	- [Link to related ADRs, design docs, or tickets]
91	- [Supersedes ADR-XXXX] (if applicable)
92	```
93
94	### Step 5: Save and Index
95	- [ ] Save as `docs/adr/NNNN-kebab-case-title.md`
96	- [ ] Update ADR index if one exists (`docs/adr/README.md`)
97	- [ ] Link from relevant design docs or tickets
98
99	### Step 6: Review
100	- [ ] Verify context is complete enough for a new team member to understand
101	- [ ] Verify all considered options are documented
102	- [ ] Verify consequences include both positive and negative
103	- [ ] Verify no secrets, PII, or internal URLs
104
105	## ADR Categories
106
107	\| Category \| Examples \|
108	\|----------\|---------\|
109	\| Architecture \| Microservices vs monolith, event sourcing, CQRS \|
110	\| Technology \| Database choice, framework, language, cloud provider \|
111	\| Process \| Branching strategy, release process, testing approach \|
112	\| Security \| Auth mechanism, encryption approach, secret management \|
113	\| Infrastructure \| Deployment strategy, scaling approach, caching layer \|
114	\| Data \| Schema design, migration strategy, backup approach \|
115
116	## Rules
117	- ALWAYS document at least 2 options (including the chosen one)
118	- ALWAYS include both positive and negative consequences
119	- ALWAYS set a clear status (Proposed, Accepted, Deprecated, Superseded)
120	- NEVER delete ADRs — deprecate or supersede them
121	- NEVER include secrets or internal infrastructure details
122	- Write for future readers who weren't part of the decision
123	- Keep ADRs concise — 1–2 pages maximum
124	- Date the decision, not the document creation
125
126	## Completion
127	ADR saved to `docs/adr/` with sequential numbering, complete context, options, decision, and consequences.
128
129	## If a Step Fails
130	- Only one option: Document why alternatives were ruled out before analysis
131	- Decision not yet made: Set status to "Proposed" and list options for team discussion
132	- Superseding an old ADR: Reference the old ADR, mark old one as "Superseded by ADR-NNNN"
133	- No ADR directory: Create `docs/adr/` and add a `README.md` index

People who liked this also viewed

6 picks

Type

adr-generator

27stars3forks

View on GitHub

How to install adr-generator?

girijashankarj/cursor-handbook/adr-generator

$npx -y skills add girijashankarj/cursor-handbook --skill adr-generator

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Skill: ADR Generator
2
3	Create Architecture Decision Records following the Michael Nygard format to document significant technical decisions.
4
5	## Trigger
6	When the user asks to document an architecture decision, record a design choice, or create an ADR.
7
8	## Prerequisites
9	- [ ] Decision to document identified
10	- [ ] Options considered (at least 2)
11	- [ ] Context and constraints understood
12
13	## Steps
14
15	### Step 1: Determine ADR Number
16	- [ ] Check existing ADRs: `ls docs/adr/ 2>/dev/null \|\| echo "no ADR directory"`
17	- [ ] Assign next sequential number: `NNNN` (e.g., `0001`, `0002`)
18	- [ ] Create directory if needed: `mkdir -p docs/adr`
19
20	### Step 2: Gather Decision Context
21	- [ ] What is the problem or need?
22	- [ ] What constraints exist? (technical, business, timeline, team)
23	- [ ] What was the trigger? (new requirement, incident, tech debt)
24	- [ ] Who are the stakeholders?
25
26	### Step 3: Document Options
27	For each option considered:
28	- [ ] Name and brief description
29	- [ ] Pros (advantages, benefits)
30	- [ ] Cons (disadvantages, risks, costs)
31	- [ ] Effort estimate
32	- [ ] Team familiarity
33
34	### Step 4: Generate ADR
35
36	```markdown
37	# ADR-NNNN: [Decision Title]
38
39	## Status
40	[Proposed \| Accepted \| Deprecated \| Superseded by ADR-XXXX]
41
42	## Date
43	YYYY-MM-DD
44
45	## Context
46	[Describe the situation, problem, or need that requires a decision.
47	Include technical and business context. What forces are at play?]
48
49	## Decision
50	[State the decision clearly in 1-3 sentences. Use active voice:
51	"We will use X for Y because Z."]
52
53	## Options Considered
54
55	### Option 1: [Name]
56	- Description: [What this option entails]
57	- Pros:
58	- [Advantage 1]
59	- [Advantage 2]
60	- Cons:
61	- [Disadvantage 1]
62	- [Disadvantage 2]
63	- Effort: [Low / Medium / High]
64
65	### Option 2: [Name]
66	- Description: [What this option entails]
67	- Pros:
68	- [Advantage 1]
69	- Cons:
70	- [Disadvantage 1]
71	- Effort: [Low / Medium / High]
72
73	### Option 3: [Name] (if applicable)
74	...
75
76	## Consequences
77
78	### Positive
79	- [Good outcome 1]
80	- [Good outcome 2]
81
82	### Negative
83	- [Trade-off 1]
84	- [Accepted risk 1]
85
86	### Neutral
87	- [Side effect that isn't clearly positive or negative]
88
89	## Related
90	- [Link to related ADRs, design docs, or tickets]
91	- [Supersedes ADR-XXXX] (if applicable)
92	```
93
94	### Step 5: Save and Index
95	- [ ] Save as `docs/adr/NNNN-kebab-case-title.md`
96	- [ ] Update ADR index if one exists (`docs/adr/README.md`)
97	- [ ] Link from relevant design docs or tickets
98
99	### Step 6: Review
100	- [ ] Verify context is complete enough for a new team member to understand
101	- [ ] Verify all considered options are documented
102	- [ ] Verify consequences include both positive and negative
103	- [ ] Verify no secrets, PII, or internal URLs
104
105	## ADR Categories
106
107	\| Category \| Examples \|
108	\|----------\|---------\|
109	\| Architecture \| Microservices vs monolith, event sourcing, CQRS \|
110	\| Technology \| Database choice, framework, language, cloud provider \|
111	\| Process \| Branching strategy, release process, testing approach \|
112	\| Security \| Auth mechanism, encryption approach, secret management \|
113	\| Infrastructure \| Deployment strategy, scaling approach, caching layer \|
114	\| Data \| Schema design, migration strategy, backup approach \|
115
116	## Rules
117	- ALWAYS document at least 2 options (including the chosen one)
118	- ALWAYS include both positive and negative consequences
119	- ALWAYS set a clear status (Proposed, Accepted, Deprecated, Superseded)
120	- NEVER delete ADRs — deprecate or supersede them
121	- NEVER include secrets or internal infrastructure details
122	- Write for future readers who weren't part of the decision
123	- Keep ADRs concise — 1–2 pages maximum
124	- Date the decision, not the document creation
125
126	## Completion
127	ADR saved to `docs/adr/` with sequential numbering, complete context, options, decision, and consequences.
128
129	## If a Step Fails
130	- Only one option: Document why alternatives were ruled out before analysis
131	- Decision not yet made: Set status to "Proposed" and list options for team discussion
132	- Superseding an old ADR: Reference the old ADR, mark old one as "Superseded by ADR-NNNN"
133	- No ADR directory: Create `docs/adr/` and add a `README.md` index

People who liked this also viewed

6 picks

Type