adr-drafting

Name: adr-drafting
Author: giuseppe-trisciuoglio

1.3kinstalls36forks

How to install adr-drafting?

giuseppe-trisciuoglio/developer-kit/adr-drafting

$npx -y skills add giuseppe-trisciuoglio/developer-kit --skill adr-drafting

Installs into the current project.

Summary

Creates new Architecture Decision Record (ADR) documents for significant architectural changes using a consistent template and repository-aware naming and storage guidance. Use when a user or agent decides on an architectural change, needs to document technical rationale, or want

Files · 1

View on GitHub

SKILL.md

1	# ADR Drafting
2
3	Creates new Architecture Decision Record (ADR) documents for major architectural choices so teams can keep a clear history of why important technical decisions were made.
4
5	## Overview
6
7	This skill helps create a new ADR from discovery to final markdown file. It confirms the decision details, inspects the repository for any existing ADR conventions, and drafts a new ADR with the standard sections `Title`, `Status`, `Context`, `Decision`, and `Consequences`.
8
9	When the repository does not already have an ADR convention, default to storing ADRs in `docs/architecture/adr` and use a zero-padded filename such as `0001-use-postgresql-for-primary-database.md`.
10
11	See `references/template.md` for the default ADR template and `references/examples.md` for example ADRs and naming patterns.
12
13	## When to Use
14
15	Use this skill when a user or agent has decided on a meaningful architectural change and needs to document the rationale, chosen direction, and trade-offs in a new Architecture Decision Record. It fits requests such as creating an ADR, documenting an architecture decision, writing a decision record, or preserving the project history behind an important technical choice.
16
17	## Instructions
18
19	### Phase 1: Confirm the ADR inputs
20
21	Ask the user for the minimum information needed to draft a new ADR:
22
23	1. Decision title
24	2. Decision status (`Proposed` by default if not yet finalized)
25	3. Context: the problem, constraints, or forces driving the decision
26	4. Decision: the chosen approach
27	5. Consequences: what becomes easier, harder, riskier, or more expensive
28	6. Confirm that this request is for a new ADR, not for editing an existing ADR
29	7. Confirm the desired repository language if documentation language is unclear
30	8. Confirm whether any existing ADR naming convention must be preserved
31
32	If the user actually wants to update an existing ADR, change statuses in older ADRs, or manage supersession links, explain that this skill only drafts new ADR documents and ask whether they want to proceed with a new record instead.
33
34	### Phase 2: Discover ADR conventions in the repository
35
36	Inspect the repository before drafting:
37
38	1. Search for likely ADR locations such as:
39	- `docs/architecture/adr`
40	- `docs/adr`
41	- `adr`
42	- `architecture/adr`
43	2. If ADR files already exist, read one to three examples to infer:
44	- numbering format
45	- filename pattern
46	- title format
47	- language and tone
48	3. If no ADR directory exists, recommend `docs/architecture/adr`
49	4. Determine the next ADR number from existing files when possible
50	5. If no prior ADR exists, start with `0001`
51
52	Preferred default naming when no convention exists:
53
54	- Directory: `docs/architecture/adr`
55	- Filename: `NNNN-short-kebab-title.md`
56	- Title: `# ADR-NNNN: <Decision Title>`
57
58	### Phase 3: Draft the ADR
59
60	Create a draft using the standard structure:
61
62	```markdown
63	# ADR-NNNN: Decision Title
64
65	## Status
66	Proposed
67
68	## Context
69	What problem, constraints, or trade-offs led to this decision?
70
71	## Decision
72	What architectural choice was made?
73
74	## Consequences
75	What becomes easier, harder, riskier, or more expensive because of this decision?
76	```
77
78	Drafting rules:
79
80	- Keep the title specific and decision-oriented
81	- Capture enough context to explain why the decision was needed
82	- Record the chosen direction clearly and directly
83	- Include both positive and negative consequences when known
84	- Do not invent rationale, constraints, or outcomes that the user did not provide
85	- If critical information is missing, insert concise placeholders or ask follow-up questions before finalizing
86
87	### Phase 4: Review the draft with the user
88
89	Before writing files, present:
90
91	- proposed file path
92	- proposed title
93	- ADR status
94	- a concise preview of the drafted sections
95
96	Ask for approval before creating the file. If the user wants adjustments, revise the draft first.
97
98	### Phase 5: Create the ADR file
99
100	After approval:
101
102	1. Create the ADR directory if it does not exist
103	2. Write the ADR markdown file using the repository's established pattern when available
104	3. Preserve the user's wording for decision rationale as much as possible while keeping the document concise
105	4. Report the final file path and summarize what was created
106	5. Stop after creating the new ADR file so the skill remains focused on a single new decision record
107
108	## Examples
109
110	### Example 1: New database decision
111
112	User request: "Create an ADR for moving from SQLite to PostgreSQL"
113
114	Expected flow:
115
116	1. Confirm the title, status, reasons for the change, and expected consequences
117	2. Check whether the repository already has ADR files
118	3.

People who liked this also viewed

6 picks

Type

adr-drafting

1.3kinstalls36forks

View on GitHub

How to install adr-drafting?

giuseppe-trisciuoglio/developer-kit/adr-drafting

$npx -y skills add giuseppe-trisciuoglio/developer-kit --skill adr-drafting

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# ADR Drafting
2
3	Creates new Architecture Decision Record (ADR) documents for major architectural choices so teams can keep a clear history of why important technical decisions were made.
4
5	## Overview
6
7	This skill helps create a new ADR from discovery to final markdown file. It confirms the decision details, inspects the repository for any existing ADR conventions, and drafts a new ADR with the standard sections `Title`, `Status`, `Context`, `Decision`, and `Consequences`.
8
9	When the repository does not already have an ADR convention, default to storing ADRs in `docs/architecture/adr` and use a zero-padded filename such as `0001-use-postgresql-for-primary-database.md`.
10
11	See `references/template.md` for the default ADR template and `references/examples.md` for example ADRs and naming patterns.
12
13	## When to Use
14
15	Use this skill when a user or agent has decided on a meaningful architectural change and needs to document the rationale, chosen direction, and trade-offs in a new Architecture Decision Record. It fits requests such as creating an ADR, documenting an architecture decision, writing a decision record, or preserving the project history behind an important technical choice.
16
17	## Instructions
18
19	### Phase 1: Confirm the ADR inputs
20
21	Ask the user for the minimum information needed to draft a new ADR:
22
23	1. Decision title
24	2. Decision status (`Proposed` by default if not yet finalized)
25	3. Context: the problem, constraints, or forces driving the decision
26	4. Decision: the chosen approach
27	5. Consequences: what becomes easier, harder, riskier, or more expensive
28	6. Confirm that this request is for a new ADR, not for editing an existing ADR
29	7. Confirm the desired repository language if documentation language is unclear
30	8. Confirm whether any existing ADR naming convention must be preserved
31
32	If the user actually wants to update an existing ADR, change statuses in older ADRs, or manage supersession links, explain that this skill only drafts new ADR documents and ask whether they want to proceed with a new record instead.
33
34	### Phase 2: Discover ADR conventions in the repository
35
36	Inspect the repository before drafting:
37
38	1. Search for likely ADR locations such as:
39	- `docs/architecture/adr`
40	- `docs/adr`
41	- `adr`
42	- `architecture/adr`
43	2. If ADR files already exist, read one to three examples to infer:
44	- numbering format
45	- filename pattern
46	- title format
47	- language and tone
48	3. If no ADR directory exists, recommend `docs/architecture/adr`
49	4. Determine the next ADR number from existing files when possible
50	5. If no prior ADR exists, start with `0001`
51
52	Preferred default naming when no convention exists:
53
54	- Directory: `docs/architecture/adr`
55	- Filename: `NNNN-short-kebab-title.md`
56	- Title: `# ADR-NNNN: <Decision Title>`
57
58	### Phase 3: Draft the ADR
59
60	Create a draft using the standard structure:
61
62	```markdown
63	# ADR-NNNN: Decision Title
64
65	## Status
66	Proposed
67
68	## Context
69	What problem, constraints, or trade-offs led to this decision?
70
71	## Decision
72	What architectural choice was made?
73
74	## Consequences
75	What becomes easier, harder, riskier, or more expensive because of this decision?
76	```
77
78	Drafting rules:
79
80	- Keep the title specific and decision-oriented
81	- Capture enough context to explain why the decision was needed
82	- Record the chosen direction clearly and directly
83	- Include both positive and negative consequences when known
84	- Do not invent rationale, constraints, or outcomes that the user did not provide
85	- If critical information is missing, insert concise placeholders or ask follow-up questions before finalizing
86
87	### Phase 4: Review the draft with the user
88
89	Before writing files, present:
90
91	- proposed file path
92	- proposed title
93	- ADR status
94	- a concise preview of the drafted sections
95
96	Ask for approval before creating the file. If the user wants adjustments, revise the draft first.
97
98	### Phase 5: Create the ADR file
99
100	After approval:
101
102	1. Create the ADR directory if it does not exist
103	2. Write the ADR markdown file using the repository's established pattern when available
104	3. Preserve the user's wording for decision rationale as much as possible while keeping the document concise
105	4. Report the final file path and summarize what was created
106	5. Stop after creating the new ADR file so the skill remains focused on a single new decision record
107
108	## Examples
109
110	### Example 1: New database decision
111
112	User request: "Create an ADR for moving from SQLite to PostgreSQL"
113
114	Expected flow:
115
116	1. Confirm the title, status, reasons for the change, and expected consequences
117	2. Check whether the repository already has ADR files
118	3.

People who liked this also viewed

6 picks

Type