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*-*.mdin directories nameddecisions,adr,architecture) - Check common locations:
.project-toolkit/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: .project-toolkit/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.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
.project-toolkit/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
For this repo's canonical .project-toolkit/architecture/ location, use the
deterministic helper instead of eyeballing the directory (it also accounts
for the 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), 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 (.project-toolkit/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:
statusis alwaysproposedon a new ADR. Onlyadr-reviewconsensus changes it (see Phase G5 and the Anti-Patterns table).implementedis alwaysfalseon a new ADR; it flips at first merged change.superseded-bydefaults tonull;supersedesdefaults to[].explainerdefaults tonull. 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
statusenum is authoritative for tooling. A prose## Statussection is optional: add it only for nuance the enum cannot carry, never to restate the enum (ADR-073, amended 2026-09-29).
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) |
Mandatory Exit Gates
Run these five gates in order against the saved draft before handing it to
adr-review. They are a measured pilot, not a permanent policy: use one fixed
ADR cohort before and after the pilot, then retain them only when avoided writer
rework exceeds maintenance and runtime cost. Record factual-finding share in
round one, rounds to consensus, writer correction time, total model cost, false
blocks, gate escapes, model, harness version, and wall time. The abort condition
is false blocks or gate escapes increasing without lower writer correction time.
Every gate result is VERIFIED, NOT RUN, UNAVAILABLE, or FAILED. Do not
invent a correction when evidence is unavailable or a claim remains uncertain.
Claims ledger. Create one row for every factual claim: claim text, kind (
path,count,absence,behavior, orquote), command, and result. Store it as.project-toolkit/critique/ADR-NNN-claims-ledger.mdbeside the debate log. An absence row needs a whole-repository search. For eachpath:linerow, read the cited range directly from the working tree and record the observed text. Do not usecheck_citation_freshness.py; it checks only citations on lines added between committed revisions.Documentation accuracy. Run
Skill(skill="doc-accuracy")Phase 4 with the saved ADR as the documentation file and its mapped source files as the source input. Do not use--diff-base; it scans committed changes and cannot select this uncommitted ADR.Self-consistency. Compare every Decision item with every other Decision item and with Consequences. Record contradictions or the
VERIFIEDresult.Refuting seat. Run one seat, not the panel:
Task(subagent_type="analyst", model="haiku", prompt="Refute only the claims ledger against the repository tree. Return factual findings and evidence."). The outcome isVERIFIEDonly when no factual findings remain. Do not invokeadr-reviewwhile this seat reports a factual finding; record unavailable evidence asUNAVAILABLE, never as a fabricated correction. The seat is a bounded experiment, not independent proof. It may use a different failure mode or externally grounded evidence; record its cost and wall time.ADR review hand-off. Pass the ledger path and contents with the ADR to
adr-review. In Phase 1, record the path in the new debate log before evaluating findings. A factual finding already covered by the ledger is a gate escape, not proof that the writer must fabricate a same-pass correction.
Phase G6: Hand Off
After the gates pass, refresh the ADR index, then hand the ADR and its claims
ledger to adr-review for multi-agent validation.
The ADR index (.project-toolkit/architecture/README.md) is generated from the
ADR corpus. It lists each record's status, title, and decision
summary. The gates above can edit the title and decision summary; status stays
proposed until adr-review reaches consensus. Run the generator after the
gates so the index shows the post-gate draft instead of drifting until the next
unrelated build. Status changes after hand-off need another run.
Run it only in the rjmurillo/ai-agents repository. Check first:
git remote get-url origin | grep -Eq '^((https|ssh)://([^@/]+@)?|[^@/]+@)github\.com[:/]rjmurillo/ai-agents(\.git)?/?$' \
&& test -f build/scripts/generate_adr_index.py \
&& uv run python build/scripts/generate_adr_index.py
If the check fails, skip the refresh: either this is another repository (a fork
clone included), or build/scripts/generate_adr_index.py does not exist in this
checkout. Another repository's script of that name is that repository's code, and
running it here would execute whatever its branch supplied. The index has not
shipped in a consumer checkout, so nothing needs regenerating. A fork clone of
this repository, or an origin that is a mirror or proxy URL of it, fails the check
too: the index stays stale until the next build_all.py run regenerates it, so tell
the user to run that. The check
keeps an agent from running an unknown repository's script by accident. It scopes by
repository, not by script content: a branch checked out in this repository runs
its own copy of the script, as pytest or build_all.py would.
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
- Claims ledger records each factual claim and its evidence status
- Documentation accuracy, self-consistency, and refuting-seat results recorded
- In the
rjmurillo/ai-agentsrepository,build/scripts/generate_adr_index.pyran after the gates (Phase G6); in any other checkout it was skipped - ADR review hand-off includes the claims ledger path and gate escapes
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