Architecture Decision Record
Capture why you chose a stack, pattern, or vendor in a structured ADR before the decision gets lost in chat history.
Overview
Architecture Decision Record is an agent skill most often used in Validate (also Build, Operate) that produces a standard ADR document with context, decision, consequences, and status lineage for technical choices.
Install
npx skills add https://github.com/yonatangross/orchestkit --skill architecture-decision-recordWhat is this skill?
- Full ADR skeleton: status, authors, supersedes/superseded-by lineage
- Structured Context block with problem, current state, requirements, constraints, and forces
- Decision section with technology choices, rollout strategy, timeline, and ownership
- Consequences split into positive and negative for honest trade-off logging
- Standard status workflow: Proposed → Accepted → Superseded | Deprecated | Rejected
Adoption & trust: 715 installs on skills.sh; 183 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You picked a stack or pattern in chat, but three months later nobody remembers why or what trade-offs you accepted.
Who is it for?
Solo builders documenting non-obvious architecture calls during scope, design reviews, or infra pivots.
Skip if: Trivial one-line choices with no long-term cost, or teams that already mandate ADRs in a locked corporate template you must not alter.
When should I use this skill?
You need a formal ADR drafted or updated when making or revisiting architecture, technology, or major implementation strategy choices.
What do I get? / Deliverables
You get a numbered ADR draft with context, explicit decision, positive/negative consequences, and status fields ready to commit beside your repo docs.
- ADR markdown with status, context, decision, and consequences
- Supersedes/superseded-by links when replacing prior ADRs
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf at validate/scope because solo builders should lock architecture trade-offs while scoping—not after shipping. Scope is where requirements, constraints, and competing forces are explicit; the ADR template mirrors that decision moment.
Where it fits
Compare monolith vs BFF and capture forces before you commit sprint work.
Record the auth and session model once APIs are taking shape.
Add ADR-0003 to /docs so agents onboarding to the repo read decisions first.
Supersede ADR-0002 when migrating regions or changing observability vendor.
How it compares
Use as a structured decision log instead of burying rationale in README bullets or issue comments alone.
Common Questions / FAQ
Who is architecture-decision-record for?
Indie and solo builders who want agent help drafting ADRs that match a consistent template when stack or architecture choices matter.
When should I use architecture-decision-record?
During validate/scope when comparing options, in build/pm when locking design, and in operate/iterate when superseding an old decision—whenever you need a durable “why we chose this.”
Is architecture-decision-record safe to install?
It is a documentation template skill with no bundled executables in the excerpt; review the Security Audits panel on this Prism page before installing from any third-party skills repo.
SKILL.md
READMESKILL.md - Architecture Decision Record
# ADR-####: [Decision Title] **Status**: Proposed | Accepted | Superseded | Deprecated | Rejected **Date**: YYYY-MM-DD **Authors**: [Your Name(s)] **Supersedes**: [ADR-####] (if applicable) **Superseded by**: [ADR-####] (if applicable) --- ## Context [Describe the problem or opportunity. What forces are at play? What constraints exist?] **Problem Statement:** [Clear description of the issue or opportunity] **Current Situation:** [What is the state of the system today?] **Requirements:** - [Business requirement 1] - [Technical requirement 2] - [Stakeholder requirement 3] **Constraints:** - [Time/budget/technology constraint 1] - [Team/skill constraint 2] - [Compliance/security constraint 3] **Forces:** - [Conflicting concern 1] - [Conflicting concern 2] --- ## Decision [Describe the decision clearly and specifically. What are you choosing to do?] **We will:** [Clear statement of the decision] **Technology/Approach:** - [Component/technology 1] - [Component/technology 2] - [Component/technology 3] **Implementation Strategy:** [How will this be rolled out? Phased approach? Big bang?] **Timeline:** [Expected implementation timeline] **Responsibility:** - [Role/Person 1]: [Responsibility area] - [Role/Person 2]: [Responsibility area] --- ## Consequences ### Positive - [Benefit 1] - [Benefit 2] - [Benefit 3] ### Negative - [Cost/risk 1] - [Cost/risk 2] - [Trade-off 3] ### Neutral - [Change that's neither clearly positive nor negative 1] - [Change that's neither clearly positive nor negative 2] --- ## Alternatives Considered ### Alternative 1: [Name] **Description:** [What is this alternative?] **Pros:** - [Advantage 1] - [Advantage 2] **Cons:** - [Disadvantage 1] - [Disadvantage 2] **Why not chosen:** [Clear explanation of why this wasn't selected] ### Alternative 2: [Name] **Description:** [What is this alternative?] **Pros:** - [Advantage 1] - [Advantage 2] **Cons:** - [Disadvantage 1] - [Disadvantage 2] **Why not chosen:** [Clear explanation of why this wasn't selected] ### Alternative 3: [Name] (if applicable) [Same structure as above] --- ## References - [Link to meeting notes or discussion] - [Link to research or article] - [Link to proof of concept] - [Related ADR-####] --- ## Review Notes (Before Acceptance) **Reviewers**: [List of stakeholders who should review] **Questions/Concerns:** - [Question or concern 1] - [Question or concern 2] **Approval:** - [ ] Architect Team - [ ] Engineering Lead - [ ] Product Owner - [ ] DevOps/SRE - [ ] Security Team (if applicable) --- **Template Version**: 1.0.0 **ADR Skill**: architecture-decision-record v1.0.0 # ADR Review Checklist Use this checklist when reviewing Architecture Decision Records before accepting them. ## Pre-Review Checklist Before distributing ADR for review, author should verify: - [ ] **ADR Number**: Sequential 4-digit number assigned (check existing ADRs) - [ ] **File Location**: Placed in `/docs/adr/` or `/architecture/decisions/` - [ ] **File Naming**: Follows format `adr-####-brief-title.md` - [ ] **Status**: Set to "Proposed" (not yet "Accepted") - [ ] **Date**: Current date in YYYY-MM-DD format - [ ] **Authors**: All contributors listed with roles - [ ] **Formatting**: Markdown renders correctly, no broken links - [ ] **Template**: Follows standard ADR template structure --- ## Content Quality Checklist ### 1. Context Section - [ ] **Problem is Clear**: Anyone can understand what needs solving - [ ] **Current State Documented**: What exists today is explained - [ ] **Requirements Listed**: Business and technical needs specified - [ ] **Constraints Identified**: Limitations are explicit (budget, time, tech, skills) - [ ] **Forces Explained**: Competing concerns or trade-offs described - [ ] **Stakeholders Identified**: Who cares about this decision? **Quality Indicators:** - ✅ Context is 3-5 paragraphs (