Menu
Create an Architectural Decision Record (ADR) to document a significant design or technology choice
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | create-adr |
| description | Create an Architectural Decision Record (ADR) to document a significant design or technology choice |
| compatibility | >=1.4 |
Skill metadata: version "1.0"; license MIT; tags [documentation, architecture, decision, adr]; compatibility ">=1.4"; recommended tools [editFiles, codebase].
Create a structured ADR document that captures the context, decision, consequences, and alternatives for a significant architectural choice.
Gather inputs — Collect or infer: decision title (verb phrase), context (problem/constraints), decision (what and why), alternatives (rejected and why), stakeholders. Ask if required inputs are missing.
Determine sequence number — List docs/adr/ (create if absent). Next 4-digit number.
Write the ADR — Save to docs/adr/adr-NNNN-<title-slug>.md using template below.
Confirm — Show the created file path.
---
title: "ADR-NNNN: [Decision Title]"
status: "Proposed"
date: "YYYY-MM-DD"
authors: "[Stakeholder Names/Roles]"
tags: ["architecture", "decision"]
supersedes: ""
superseded_by: ""
---
# ADR-NNNN: [Decision Title]
## Status
**Proposed** | Accepted | Rejected | Superseded | Deprecated
## Context
[Problem statement, technical constraints, business requirements, and environmental factors
requiring this decision.]
## Decision
[Chosen solution with clear rationale for selection.]
## Consequences
### Positive
- **POS-001**: [Beneficial outcomes and advantages]
- **POS-002**: [Performance, maintainability, scalability improvements]
### Negative
- **NEG-001**: [Trade-offs, limitations, drawbacks]
- **NEG-002**: [Technical debt or complexity introduced]
## Alternatives Considered
### [Alternative 1 Name]
- **ALT-001**: **Description**: [Brief technical description]
- **ALT-002**: **Rejection Reason**: [Why this option was not selected]
### [Alternative 2 Name]
- **ALT-003**: **Description**: [Brief technical description]
- **ALT-004**: **Rejection Reason**: [Why this option was not selected]
## Implementation Notes
- **IMP-001**: [Key implementation considerations]
- **IMP-002**: [Migration or rollout strategy if applicable]
- **IMP-003**: [Monitoring and success criteria]
## References
- **REF-001**: [Related ADRs]
- **REF-002**: [External documentation]
- **REF-003**: [Standards or frameworks referenced]
Health check procedures D1–D14 for the Audit agent — structural validation, attention budget, version checks, workspace integrity, and static audit
Configure and manage Model Context Protocol servers for external tool access
Review a UI for accessibility — WCAG 2.1 AA compliance, semantic HTML, ARIA usage, keyboard navigation, focus management, colour contrast, and screen reader compatibility
Design or review a REST or GraphQL API — resource modeling, versioning strategy, error contract, OpenAPI/schema-first workflow, and security baseline
Generate a CHANGELOG.md entry from staged changes, a commit range, or a PR diff — following Keep a Changelog format with conventional commit classification
Set up and audit environment variable management — create .env.example, add startup validation, separate secrets from config, and document every variable