architecture-decision-records

Name: architecture-decision-records
Author: tranhieutt

69stars41forks

How to install architecture-decision-records?

tranhieutt/software_development_department/architecture-decision-records

$npx -y skills add tranhieutt/software_development_department --skill architecture-decision-records

Installs into the current project.

Summary

Manages the ADR (Architecture Decision Record) registry. Use when recording tech-stack choices, design patterns, or infrastructure decisions with context, alternatives, and rationale. Supports listing, searching, or creating formal ADR documents.

Files · 1

View on GitHub

SKILL.md

1	# Architecture Decision Records
2
3	## Workflow Protocol
4
5	1. Determine the next ADR number by scanning `docs/internal/adr/` for existing ADRs.
6	2. Run the decision-ledger read gate before drafting:
7	`/trace-history --risk High --last 20`.
8	Include relevant prior decisions, or state that no relevant high-risk prior
9	decision was found.
10	3. Gather context by reading related code and existing ADRs.
11	4. Guide the user through the decision by asking clarifying questions if the title alone is insufficient.
12	5. Generate the ADR following the template below.
13	6. Save the ADR to `docs/internal/adr/ADR-[NNN]-[slug].md`.
14	7. Update the Index Table in `docs/technical/DECISIONS.md`.
15
16	## When to write an ADR vs skip
17
18	\| Write ADR \| Skip ADR \|
19	\|---\|---\|
20	\| New framework/database adoption \| Minor version upgrades \|
21	\| API design patterns \| Bug fixes \|
22	\| Security architecture \| Implementation details \|
23	\| Integration patterns \| Routine maintenance \|
24
25	## ADR lifecycle
26
27	```
28	Proposed → Accepted → Deprecated → Superseded
29	↓
30	Rejected
31	```
32
33	## Template (MADR format — use this)
34
35	```markdown
36	# ADR-NNN: [Title]
37
38	## Status
39	Accepted \| Proposed \| Deprecated \| Superseded by ADR-NNN
40
41	## Context
42	[Problem statement, current situation, constraints, scale]
43
44	## Prior Decision Check
45	[Result of `/trace-history --risk High --last 20`; cite relevant prior entries
46	or state "No relevant prior high-risk decisions found."]
47
48	## Decision Drivers
49	- [Must/Should/Could requirement]
50
51	## Considered Options
52	### Option 1: [Name] — [one-line summary]
53	Pros: ... \| Cons: ...
54
55	### Option 2: [Name]
56	Pros: ... \| Cons: ...
57
58	## Decision
59	We will use [Option N] because [key rationale].
60
61	## Consequences
62	Positive: ...
63	Negative: ...
64	Risks: ... Mitigation: ...
65
66	## Related ADRs
67	- ADR-NNN: [relationship]
68	```
69
70	## Quick examples
71
72	Lightweight ADR (for clear-cut decisions):
73	```markdown
74	# ADR-0012: Adopt TypeScript for Frontend
75
76	Status: Accepted \| Date: 2024-01-15 \| Deciders: @alice, @bob
77
78	## Context
79	50+ React components with prop-type-mismatch bugs. PropTypes are runtime-only.
80
81	## Decision
82	TypeScript for all new frontend code. Migrate incrementally with `allowJs: true`.
83
84	## Consequences
85	Good: Compile-time errors, better IDE support.
86	Bad: Learning curve, initial slowdown.
87	```
88
89	Y-Statement (for concise formal record):
90	```markdown
91	In the context of building a microservices architecture,
92	facing need for centralized auth and rate limiting,
93	we decided for Kong Gateway
94	and against AWS API Gateway and custom Nginx,
95	to achieve vendor independence and plugin extensibility,
96	accepting we manage Kong infrastructure ourselves.
97	```
98
99	## File structure
100
101	```
102	docs/internal/adr/
103	├── ADR-0001-use-postgresql.md
104	└── ADR-0003-mongodb-deprecated.md # [SUPERSEDED by ADR-0020]
105	```
106
107	## Index table (maintain in docs/technical/DECISIONS.md)
108
109	\| ADR \| Title \| Status \| Date \|
110	\|---\|---\|---\|---\|
111	\| 0001 \| Use PostgreSQL \| Accepted \| 2024-01-10 \|
112	\| 0003 \| MongoDB for profiles \| Deprecated \| 2023-06-15 \|
113
114	## Key rules
115
116	- Never modify accepted ADRs — write a new one to supersede
117	- Write early — before implementation starts, not after
118	- Max 1-2 pages — if longer, decision scope is too broad
119	- State real cons — an ADR without honest tradeoffs has no value
120	- Update status — mark deprecated when superseded; link the new ADR
121
122	## Automation
123
124	```bash
125	# Custom repo path:
126	# 1. Create docs/internal/adr/ADR-[NNN]-[slug].md
127	# 2. Append one summary row and one summary entry to docs/technical/DECISIONS.md
128	# 3. Do not overwrite docs/technical/DECISIONS.md; it is append-only
129	```

People who liked this also viewed

6 picks

Type

architecture-decision-records

69stars41forks

View on GitHub

How to install architecture-decision-records?

tranhieutt/software_development_department/architecture-decision-records

$npx -y skills add tranhieutt/software_development_department --skill architecture-decision-records

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Architecture Decision Records
2
3	## Workflow Protocol
4
5	1. Determine the next ADR number by scanning `docs/internal/adr/` for existing ADRs.
6	2. Run the decision-ledger read gate before drafting:
7	`/trace-history --risk High --last 20`.
8	Include relevant prior decisions, or state that no relevant high-risk prior
9	decision was found.
10	3. Gather context by reading related code and existing ADRs.
11	4. Guide the user through the decision by asking clarifying questions if the title alone is insufficient.
12	5. Generate the ADR following the template below.
13	6. Save the ADR to `docs/internal/adr/ADR-[NNN]-[slug].md`.
14	7. Update the Index Table in `docs/technical/DECISIONS.md`.
15
16	## When to write an ADR vs skip
17
18	\| Write ADR \| Skip ADR \|
19	\|---\|---\|
20	\| New framework/database adoption \| Minor version upgrades \|
21	\| API design patterns \| Bug fixes \|
22	\| Security architecture \| Implementation details \|
23	\| Integration patterns \| Routine maintenance \|
24
25	## ADR lifecycle
26
27	```
28	Proposed → Accepted → Deprecated → Superseded
29	↓
30	Rejected
31	```
32
33	## Template (MADR format — use this)
34
35	```markdown
36	# ADR-NNN: [Title]
37
38	## Status
39	Accepted \| Proposed \| Deprecated \| Superseded by ADR-NNN
40
41	## Context
42	[Problem statement, current situation, constraints, scale]
43
44	## Prior Decision Check
45	[Result of `/trace-history --risk High --last 20`; cite relevant prior entries
46	or state "No relevant prior high-risk decisions found."]
47
48	## Decision Drivers
49	- [Must/Should/Could requirement]
50
51	## Considered Options
52	### Option 1: [Name] — [one-line summary]
53	Pros: ... \| Cons: ...
54
55	### Option 2: [Name]
56	Pros: ... \| Cons: ...
57
58	## Decision
59	We will use [Option N] because [key rationale].
60
61	## Consequences
62	Positive: ...
63	Negative: ...
64	Risks: ... Mitigation: ...
65
66	## Related ADRs
67	- ADR-NNN: [relationship]
68	```
69
70	## Quick examples
71
72	Lightweight ADR (for clear-cut decisions):
73	```markdown
74	# ADR-0012: Adopt TypeScript for Frontend
75
76	Status: Accepted \| Date: 2024-01-15 \| Deciders: @alice, @bob
77
78	## Context
79	50+ React components with prop-type-mismatch bugs. PropTypes are runtime-only.
80
81	## Decision
82	TypeScript for all new frontend code. Migrate incrementally with `allowJs: true`.
83
84	## Consequences
85	Good: Compile-time errors, better IDE support.
86	Bad: Learning curve, initial slowdown.
87	```
88
89	Y-Statement (for concise formal record):
90	```markdown
91	In the context of building a microservices architecture,
92	facing need for centralized auth and rate limiting,
93	we decided for Kong Gateway
94	and against AWS API Gateway and custom Nginx,
95	to achieve vendor independence and plugin extensibility,
96	accepting we manage Kong infrastructure ourselves.
97	```
98
99	## File structure
100
101	```
102	docs/internal/adr/
103	├── ADR-0001-use-postgresql.md
104	└── ADR-0003-mongodb-deprecated.md # [SUPERSEDED by ADR-0020]
105	```
106
107	## Index table (maintain in docs/technical/DECISIONS.md)
108
109	\| ADR \| Title \| Status \| Date \|
110	\|---\|---\|---\|---\|
111	\| 0001 \| Use PostgreSQL \| Accepted \| 2024-01-10 \|
112	\| 0003 \| MongoDB for profiles \| Deprecated \| 2023-06-15 \|
113
114	## Key rules
115
116	- Never modify accepted ADRs — write a new one to supersede
117	- Write early — before implementation starts, not after
118	- Max 1-2 pages — if longer, decision scope is too broad
119	- State real cons — an ADR without honest tradeoffs has no value
120	- Update status — mark deprecated when superseded; link the new ADR
121
122	## Automation
123
124	```bash
125	# Custom repo path:
126	# 1. Create docs/internal/adr/ADR-[NNN]-[slug].md
127	# 2. Append one summary row and one summary entry to docs/technical/DECISIONS.md
128	# 3. Do not overwrite docs/technical/DECISIONS.md; it is append-only
129	```

People who liked this also viewed

6 picks

Type