ADR Generator
Create well-structured Architectural Decision Records that document technical decisions with clear context, rationale, consequences, and alternatives.
Triggers
| Trigger Phrase |
Operation |
write an ADR |
Full ADR generation workflow |
write an architecture decision record |
Full ADR generation workflow |
create an ADR |
Full ADR generation workflow |
generate ADR for |
Full ADR generation workflow |
document these design choices |
Capture rationale for durable architecture or design decisions |
Quick Start
# These all work:
write an ADR for the event model
write an architecture decision record for database selection
create an ADR for database selection
new ADR for authentication strategy
document this architecture decision about event sourcing
generate ADR for switching from REST to gRPC
document these design choices for future us to revisit as models change
record why we chose this instruction-file structure for future maintainers
When to Use
| Situation |
Use This Skill? |
| New architectural decision needs documenting |
Yes |
| Durable design choices or rationale need capturing for future readers |
Yes |
| Changing an existing system or pattern |
Yes (includes Prior Art Investigation) |
| Reviewing or validating an existing ADR |
No, use adr-review skill |
| Minor implementation detail, not architectural |
No |
Process
Phase G1: Gather
Collect required information from the user:
- Decision Title: Clear, concise name
- Context: Problem statement, technical constraints, business requirements
- Decision: Chosen solution with rationale
- Alternatives: Options considered (at least 2) and rejection reasons
- Stakeholders: People or teams involved
If any required information is missing, ask the user before proceeding.
Significance check: Before proceeding, quickly assess whether the decision warrants an ADR using the ASR Test. If the decision is trivially reversible, purely local, and has no stakeholder concern, suggest skipping the ADR.
Readiness check: Verify the decision passes the START Definition of Ready: Stakeholders known, Time (Most Responsible Moment) has come, Alternatives exist, Requirements understood, Template will be determined in G2.
If the decision changes an existing system, trigger Prior Art Investigation using the chestertons-fence skill or manually gather: what exists, why it was built that way, and why change now.
Phase G2: Research
Discover the ADR destination, naming convention, numbering, and template by exploring the codebase.
Step 1: Locate ADR directory
Explore the codebase to find where ADRs live. Do not assume a fixed location.
- Search broadly: Use glob/grep to find files matching ADR patterns (
ADR-*.md, adr-*.md, 0*-*.md in directories named decisions, adr, architecture)
- Check common locations:
.agents/architecture/, docs/adr/, docs/architecture/, docs/decisions/, architecture/decisions/
- Check for ADR tooling config: Look for
.adr-dir files (used by adr-tools) or ADR references in README, CONTRIBUTING, or project documentation
- If user specifies a location: Use that, regardless of what exists elsewhere
Note: .agents/architecture/, docs/adr/, docs/architecture/, docs/decisions/, and architecture/decisions/ are monitored by adr-review for auto-triggered review when the platform honors file triggers. Invoke adr-review manually if automatic review does not fire.
Step 2: Detect template from existing ADRs
If the directory contains existing ADRs:
- Read 2-3 existing ADRs to infer the template in use (section headings, frontmatter style, naming convention, case convention)
- Match against known templates in the ADR templates catalog
- Adopt the detected template, naming convention (e.g.,
ADR-NNN-slug.md vs 0NNN-slug.md), and section structure
- Note:
adr-review auto-triggers only match uppercase ADR-*.md patterns. If existing ADRs use lowercase, warn the user that auto-review will not trigger
- Check for a template file (e.g.,
ADR-TEMPLATE.md, template.md) in the same directory or a parent
Step 3: Handle no existing ADRs
If no ADRs or template files exist anywhere in the codebase:
- Prompt the user to choose a template from the catalog
- Suggest the Project Canonical template as the default (if
.agents/architecture/ADR-TEMPLATE.md exists) or MADR as a widely-adopted alternative
- Ask the user to confirm or specify the target directory
Step 4: Determine next number
- Scan files matching the detected naming pattern in the destination directory
- Determine the next sequential number (zero-padded to match existing convention)
- Verify no collision with existing files in that directory
For this repo's canonical .agents/architecture/ location, use the
deterministic helper instead of eyeballing the directory (it also accounts
for the #2228 allowlist of pre-existing duplicates):
python3 scripts/validation/check_adr_uniqueness.py --print-next
The same script is enforced as a merge-time CI gate
(.github/workflows/validate-adr-number-uniqueness.yml, issue #2253), so a
PR that picked a number which has since been merged by another branch will
fail with a remediation message naming the next free value. Re-run
--print-next and rename the file, the # ADR-NNN: heading, and any
references before pushing.
Phase G3: Generate
Populate the detected template with gathered content:
- Use precise, unambiguous language
- Include both positive and negative consequences
- Document all alternatives with pros/cons table and clear rejection rationale
- Include Prior Art Investigation section when changing existing systems
- Structure for both machine parsing and human reference
- Match the style and conventions of existing ADRs at the destination
Lifecycle frontmatter (ADR-073, Phase 1): when the destination uses this
repo's canonical template (.agents/architecture/ADR-TEMPLATE.md), emit the
machine-readable YAML frontmatter block above the # ADR-NNN: heading with
these safe defaults:
---
id: ADR-NNN # match the number chosen in Step 4
status: proposed # always proposed on a new ADR (never accepted)
date: YYYY-MM-DD # today, last-updated
decision-makers: []
supersedes: [] # ADR ids this record supersedes, if any
superseded-by: null
explainer: null # display-only link; NEVER auto-fetch (CWE-918 SSRF)
implemented: false # flips true at the first merged change
---
Rules the generator MUST honor:
status is always proposed on a new ADR. Only adr-review consensus
changes it (see Phase G5 and the Anti-Patterns table).
implemented is always false on a new ADR; it flips at first merged change.
superseded-by defaults to null; supersedes defaults to [].
explainer defaults to null. If the author supplies one, record the literal
string only. MUST NOT fetch, resolve, or follow the URL (it is a poisoning and
SSRF surface, CWE-918). It is display-only metadata for human click-through.
- The frontmatter
status enum is authoritative for tooling; the prose
## Status section carries the human-readable nuance.
Phase G4: Validate
Self-check against the quality checklist before saving. All structural and content checks must pass.
Phase G5: Save
Write the file to the destination directory determined in Phase G2:
| Rule |
Example |
| Match existing naming convention |
ADR-053-authentication-strategy.md or 0053-authentication-strategy.md |
| Zero-pad number to match existing pattern |
ADR-001, 0001, etc. |
| Lowercase kebab-case slug (3-5 words) |
database-selection, event-sourcing-pattern |
Status always set to Proposed |
Changed only after adr-review debate |
Frontmatter status: proposed, implemented: false, explainer: null |
Phase 1 defaults (ADR-073); explainer never auto-fetched (CWE-918) |
After saving, recommend the user invoke the adr-review skill for multi-agent validation.
Anti-Patterns
Avoid these when creating ADRs. Full catalog with 11+ creation and 7 review anti-patterns in AD Quality Frameworks.
| Avoid |
Why |
Instead |
| Skipping alternatives section |
Decisions without alternatives lack rigor |
Document at least 2 alternatives with pros/cons |
Setting status to Accepted |
ADRs require review before acceptance |
Always use Proposed, let adr-review change it |
| Duplicating an existing ADR |
Causes governance confusion |
Scan existing ADRs in G2, supersede if needed |
| Context that describes the solution |
Context should explain the problem |
Keep context focused on forces and constraints |
| Omitting negative consequences |
Dishonest trade-off analysis ("Free Lunch Coupon") |
Include at least 1 negative consequence |
| Skipping Prior Art when changing systems |
Risk of removing structures without understanding |
Use chestertons-fence skill |
| Sales Pitch language |
Marketing language erodes trust |
Use precise, quantifiable language |
| Dummy alternatives |
Fake options to make preferred choice shine |
Present genuine alternatives with honest pros/cons |
| Ignoring the template at the destination |
Inconsistent ADR log |
Detect template from existing ADRs in Phase G2 |
Style
- No sycophancy, AI filler phrases, or hedging language
- Active voice, direct address
- Replace adjectives with data (quantify impact)
- Short sentences (15-20 words), Grade 9 reading level
Verification
Before delivering, confirm all items in the quality checklist pass:
Related Skills
| Skill |
Responsibility |
adr-generator |
Creates a new ADR from scratch (Phases G1-G5) |
adr-review |
Validates an existing ADR via 6-agent debate |
chestertons-fence |
Investigates historical context before changing existing systems |
References
- ADR Template: This project's canonical ADR document structure
- ADR Templates Catalog: Comparison of Nygard, MADR, Alexandrian, Tyree & Akerman, and other formats
- AD Quality Frameworks: ASR Test, START (DoR), ecADR (DoD), anti-patterns, review checklist (Zimmermann)
- ADR Best Practices: Writing guidance, lifecycle, naming conventions, teamwork advice
- Quality Checklist: Validation checklist for Phase G4
1---2name: adr-generator3version: 1.1.04description: Create comprehensive Architectural Decision Records (ADRs). Researches the destination directory to detect existing template conventions, gathers context, determines next ADR number, generates the ADR, validates completeness, and saves. Supports multiple ADR formats (MADR, Nygard, Alexandrian, project canonical). Use when documenting technical decisions, creating new ADR files, or capturing rationale so future readers can revisit a choice. Use when you say "write an ADR", "document this decision", "document these design choices", "record why we chose this", "capture the rationale", or "for future maintainers", or when creating an ADR-like markdown file under docs/decisions/, docs/adr/, docs/architecture/, architecture/decisions/, or .agents/architecture/. Do NOT use to debate or review an existing ADR (use adr-review).5license: MIT6user-invocable: true7metadata:8 source: https://skillmd.com/skills/rjmurillo/adr-generator9 domains: [architecture, documentation, governance, decision-records]10 type: generator11 inputs: [decision-description, context, alternatives]12 outputs: [adr-markdown-file]13---1415# ADR Generator1617Create well-structured Architectural Decision Records that document technical decisions with clear context, rationale, consequences, and alternatives.1819## Triggers2021| Trigger Phrase | Operation |22|----------------|-----------|23| `write an ADR` | Full ADR generation workflow |24| `write an architecture decision record` | Full ADR generation workflow |25| `create an ADR` | Full ADR generation workflow |26| `generate ADR for` | Full ADR generation workflow |27| `document these design choices` | Capture rationale for durable architecture or design decisions |2829---3031## Quick Start3233```text34# These all work:35write an ADR for the event model36write an architecture decision record for database selection37create an ADR for database selection38new ADR for authentication strategy39document this architecture decision about event sourcing40generate ADR for switching from REST to gRPC41document these design choices for future us to revisit as models change42record why we chose this instruction-file structure for future maintainers43```4445---4647## When to Use4849| Situation | Use This Skill? |50|-----------|----------------|51| New architectural decision needs documenting | Yes |52| Durable design choices or rationale need capturing for future readers | Yes |53| Changing an existing system or pattern | Yes (includes Prior Art Investigation) |54| Reviewing or validating an existing ADR | No, use `adr-review` skill |55| Minor implementation detail, not architectural | No |5657---5859## Process6061### Phase G1: Gather6263Collect required information from the user:6465- **Decision Title**: Clear, concise name66- **Context**: Problem statement, technical constraints, business requirements67- **Decision**: Chosen solution with rationale68- **Alternatives**: Options considered (at least 2) and rejection reasons69- **Stakeholders**: People or teams involved7071If any required information is missing, ask the user before proceeding.7273**Significance check**: Before proceeding, quickly assess whether the decision warrants an ADR using the [ASR Test](references/ad-quality-frameworks.md). If the decision is trivially reversible, purely local, and has no stakeholder concern, suggest skipping the ADR.7475**Readiness check**: Verify the decision passes the [START Definition of Ready](references/ad-quality-frameworks.md): Stakeholders known, Time (Most Responsible Moment) has come, Alternatives exist, Requirements understood, Template will be determined in G2.7677If the decision changes an existing system, trigger **Prior Art Investigation** using the `chestertons-fence` skill or manually gather: what exists, why it was built that way, and why change now.7879### Phase G2: Research8081Discover the ADR destination, naming convention, numbering, and template by exploring the codebase.8283#### Step 1: Locate ADR directory8485Explore the codebase to find where ADRs live. Do not assume a fixed location.86871. **Search broadly**: Use glob/grep to find files matching ADR patterns (`ADR-*.md`, `adr-*.md`, `0*-*.md` in directories named `decisions`, `adr`, `architecture`)882. **Check common locations**: `.agents/architecture/`, `docs/adr/`, `docs/architecture/`, `docs/decisions/`, `architecture/decisions/`893. **Check for ADR tooling config**: Look for `.adr-dir` files (used by `adr-tools`) or ADR references in README, CONTRIBUTING, or project documentation904. **If user specifies a location**: Use that, regardless of what exists elsewhere9192Note: `.agents/architecture/`, `docs/adr/`, `docs/architecture/`, `docs/decisions/`, and `architecture/decisions/` are monitored by `adr-review` for auto-triggered review when the platform honors file triggers. Invoke `adr-review` manually if automatic review does not fire.9394#### Step 2: Detect template from existing ADRs9596If the directory contains existing ADRs:9798- Read 2-3 existing ADRs to infer the template in use (section headings, frontmatter style, naming convention, case convention)99- Match against known templates in the [ADR templates catalog](references/adr-templates-catalog.md)100- Adopt the detected template, naming convention (e.g., `ADR-NNN-slug.md` vs `0NNN-slug.md`), and section structure101- Note: `adr-review` auto-triggers only match uppercase `ADR-*.md` patterns. If existing ADRs use lowercase, warn the user that auto-review will not trigger102- Check for a template file (e.g., `ADR-TEMPLATE.md`, `template.md`) in the same directory or a parent103104#### Step 3: Handle no existing ADRs105106If no ADRs or template files exist anywhere in the codebase:107108- Prompt the user to choose a template from the [catalog](references/adr-templates-catalog.md)109- Suggest the **Project Canonical** template as the default (if `.agents/architecture/ADR-TEMPLATE.md` exists) or **MADR** as a widely-adopted alternative110- Ask the user to confirm or specify the target directory111112#### Step 4: Determine next number113114- Scan files matching the detected naming pattern in the destination directory115- Determine the next sequential number (zero-padded to match existing convention)116- Verify no collision with existing files in that directory117118For this repo's canonical `.agents/architecture/` location, use the119deterministic helper instead of eyeballing the directory (it also accounts120for the #2228 allowlist of pre-existing duplicates):121122```bash123python3 scripts/validation/check_adr_uniqueness.py --print-next124```125126The same script is enforced as a merge-time CI gate127(`.github/workflows/validate-adr-number-uniqueness.yml`, issue #2253), so a128PR that picked a number which has since been merged by another branch will129fail with a remediation message naming the next free value. Re-run130`--print-next` and rename the file, the `# ADR-NNN:` heading, and any131references before pushing.132133### Phase G3: Generate134135Populate the detected template with gathered content:136137- Use precise, unambiguous language138- Include both positive and negative consequences139- Document all alternatives with pros/cons table and clear rejection rationale140- Include Prior Art Investigation section when changing existing systems141- Structure for both machine parsing and human reference142- Match the style and conventions of existing ADRs at the destination143144**Lifecycle frontmatter (ADR-073, Phase 1)**: when the destination uses this145repo's canonical template (`.agents/architecture/ADR-TEMPLATE.md`), emit the146<!-- vendor-portability: declared. adr-generator reads the canonical ADR template under .agents/architecture/; a consumer repo without it falls back to the bundled references/adr-template.md. Issue #2050. -->147machine-readable YAML frontmatter block above the `# ADR-NNN:` heading with148these safe defaults:149150```yaml151---152id: ADR-NNN # match the number chosen in Step 4153status: proposed # always proposed on a new ADR (never accepted)154date: YYYY-MM-DD # today, last-updated155decision-makers: []156supersedes: [] # ADR ids this record supersedes, if any157superseded-by: null158explainer: null # display-only link; NEVER auto-fetch (CWE-918 SSRF)159implemented: false # flips true at the first merged change160---161```162163Rules the generator MUST honor:164165- `status` is always `proposed` on a new ADR. Only `adr-review` consensus166 changes it (see Phase G5 and the Anti-Patterns table).167- `implemented` is always `false` on a new ADR; it flips at first merged change.168- `superseded-by` defaults to `null`; `supersedes` defaults to `[]`.169- `explainer` defaults to `null`. If the author supplies one, record the literal170 string only. MUST NOT fetch, resolve, or follow the URL (it is a poisoning and171 SSRF surface, CWE-918). It is display-only metadata for human click-through.172- The frontmatter `status` enum is authoritative for tooling; the prose173 `## Status` section carries the human-readable nuance.174175### Phase G4: Validate176177Self-check against the [quality checklist](references/quality-checklist.md) before saving. All structural and content checks must pass.178179### Phase G5: Save180181Write the file to the destination directory determined in Phase G2:182183| Rule | Example |184|------|---------|185| Match existing naming convention | `ADR-053-authentication-strategy.md` or `0053-authentication-strategy.md` |186| Zero-pad number to match existing pattern | `ADR-001`, `0001`, etc. |187| Lowercase kebab-case slug (3-5 words) | `database-selection`, `event-sourcing-pattern` |188| Status always set to `Proposed` | Changed only after `adr-review` debate |189| Frontmatter `status: proposed`, `implemented: false`, `explainer: null` | Phase 1 defaults (ADR-073); `explainer` never auto-fetched (CWE-918) |190191After saving, recommend the user invoke the `adr-review` skill for multi-agent validation.192193---194195## Anti-Patterns196197Avoid these when creating ADRs. Full catalog with 11+ creation and 7 review anti-patterns in [AD Quality Frameworks](references/ad-quality-frameworks.md).198199| Avoid | Why | Instead |200|-------|-----|---------|201| Skipping alternatives section | Decisions without alternatives lack rigor | Document at least 2 alternatives with pros/cons |202| Setting status to `Accepted` | ADRs require review before acceptance | Always use `Proposed`, let `adr-review` change it |203| Duplicating an existing ADR | Causes governance confusion | Scan existing ADRs in G2, supersede if needed |204| Context that describes the solution | Context should explain the problem | Keep context focused on forces and constraints |205| Omitting negative consequences | Dishonest trade-off analysis ("Free Lunch Coupon") | Include at least 1 negative consequence |206| Skipping Prior Art when changing systems | Risk of removing structures without understanding | Use `chestertons-fence` skill |207| Sales Pitch language | Marketing language erodes trust | Use precise, quantifiable language |208| Dummy alternatives | Fake options to make preferred choice shine | Present genuine alternatives with honest pros/cons |209| Ignoring the template at the destination | Inconsistent ADR log | Detect template from existing ADRs in Phase G2 |210211---212213## Style214215- No sycophancy, AI filler phrases, or hedging language216- Active voice, direct address217- Replace adjectives with data (quantify impact)218- Short sentences (15-20 words), Grade 9 reading level219220---221222## Verification223224Before delivering, confirm all items in the [quality checklist](references/quality-checklist.md) pass:225226- [ ] All required sections present227- [ ] ADR number is unique228- [ ] Status is `Proposed`229- [ ] Context explains the problem, not the solution230- [ ] At least 2 alternatives with pros/cons231- [ ] At least 1 negative consequence documented232- [ ] File saved to destination directory determined in Phase G2233234---235236## Related Skills237238| Skill | Responsibility |239|-------|---------------|240| `adr-generator` | **Creates** a new ADR from scratch (Phases G1-G5) |241| `adr-review` | **Validates** an existing ADR via 6-agent debate |242| `chestertons-fence` | **Investigates** historical context before changing existing systems |243244---245246## References247248- [ADR Template](references/adr-template.md): This project's canonical ADR document structure249- [ADR Templates Catalog](references/adr-templates-catalog.md): Comparison of Nygard, MADR, Alexandrian, Tyree & Akerman, and other formats250- [AD Quality Frameworks](references/ad-quality-frameworks.md): ASR Test, START (DoR), ecADR (DoD), anti-patterns, review checklist (Zimmermann)251- [ADR Best Practices](references/adr-best-practices.md): Writing guidance, lifecycle, naming conventions, teamwork advice252- [Quality Checklist](references/quality-checklist.md): Validation checklist for Phase G4