adr-generator
ADR Generator
Create well-structured Architectural Decision Records that document technical decisions with clear context, rationale, consequences, and alternatives.
Triggers
| Trigger Phrase | Operation |
|---|---|
create an ADR |
Full ADR generation workflow |
generate ADR |
Full ADR generation workflow |
write an architecture decision record |
Full ADR generation workflow |
new ADR for |
Targeted ADR for a specific decision |
document this architecture decision |
Full ADR generation workflow |
Quick Start
# These all work:
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
When to Use
| Situation | Use This Skill? |
|---|---|
| New architectural decision needs documenting | 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*-*.mdin directories nameddecisions,adr,architecture) - Check common locations:
.agents/architecture/,docs/adr/,docs/architecture/,docs/decisions/,architecture/decisions/ - Check for ADR tooling config: Look for
.adr-dirfiles (used byadr-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/ and docs/architecture/ are monitored by adr-review for auto-triggered review. ADRs in other directories require manual adr-review invocation.
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.mdvs0NNN-slug.md), and section structure - Note:
adr-reviewauto-triggers only match uppercaseADR-*.mdpatterns. 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.mdexists) 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
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
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 |
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:
- All required sections present
- ADR number is unique
- Status is
Proposed - Context explains the problem, not the solution
- At least 2 alternatives with pros/cons
- At least 1 negative consequence documented
- File saved to destination directory determined in Phase G2
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
More from rjmurillo/ai-agents
reflect
CRITICAL learning capture. Extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes and preserve what works. Use PROACTIVELY after user corrections ("no", "wrong"), after praise ("perfect", "exactly"), when discovering edge cases, or when skills are heavily used. Without reflection, valuable learnings are LOST forever. Acts as continuous improvement engine for all skills. Invoke EARLY and OFTEN - every correction is a learning opportunity.
14threat-modeling
Structured security analysis using OWASP Four-Question Framework and STRIDE methodology. Generates threat matrices with risk ratings, mitigations, and prioritization. Use for attack surface analysis, security architecture review, or when asking what can go wrong.
2chestertons-fence
Investigate historical context of existing code, patterns, or constraints before proposing changes. Automates git archaeology, PR/ADR search, and dependency analysis to prevent removing structures without understanding their purpose.
2github-url-intercept
BLOCKING INTERCEPT: When ANY github.com URL appears in user input, STOP and use this skill. Never fetch GitHub HTML pages directly - they are 5-10MB and will exhaust your context window. This skill routes URLs to efficient API calls (1-50KB). Triggers on: pull/, issues/, blob/, tree/, commit/, compare/, discussions/.
2git-advanced-workflows
Advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog. Use when managing complex Git histories, collaborating on feature branches, or recovering from repository issues.
2pr-comment-responder
PR review coordinator who gathers comment context, acknowledges every
2