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).
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
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).
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)
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):
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 4status:proposed# always proposed on a new ADR (never accepted)date:YYYY-MM-DD# today, last-updateddecision-makers: []
supersedes: [] # ADR ids this record supersedes, if anysuperseded-by:nullexplainer: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
