adr
Scannednpx machina-cli add skill tslateman/duet/adr --openclawArchitecture Decision Record Generator
Generate an Architecture Decision Record (ADR) based on the conversation context and any architectural decisions discussed.
ADR Format
Create a markdown file with this structure:
# ADR-[NUMBER]: [TITLE]
**Date:** [YYYY-MM-DD]
**Status:** [Proposed | Accepted | Deprecated | Superseded]
**Deciders:** [Who was involved]
## Context
What is the issue that we're seeing that is motivating this decision or change?
## Decision
What is the change that we're proposing and/or doing?
## Consequences
What becomes easier or more difficult to do because of this change?
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Trade-off 1]
- [Trade-off 2]
### Risks
- [Risk and mitigation]
## Alternatives Considered
### [Alternative 1]
- **Description:** What was this option?
- **Rejected because:** Why didn't we choose it?
### [Alternative 2]
- **Description:** What was this option?
- **Rejected because:** Why didn't we choose it?
## References
- [Related PR, issue, or document]
- [Relevant discussion or prior art]
Instructions
-
Extract from context — Use the conversation to identify:
- The problem or decision being made
- Options that were discussed
- The chosen approach and rationale
- Trade-offs acknowledged
-
Find the ADR location — Look for existing ADRs:
docs/adr/ordocs/decisions/adr/at project root- If none exist, suggest creating
docs/adr/
-
Number appropriately — Check existing ADRs and use the next number
-
Write concisely — ADRs should be scannable:
- Context: 2-4 sentences
- Decision: 1-2 sentences
- Consequences: Bullet points
- Alternatives: Brief, focused on why rejected
-
Capture the why — The decision itself ages; the reasoning stays valuable
See Also
/research— Research informs the decision; ADR captures it/review— Reviews that surface architectural decisions belong in ADRsskills/FRAMEWORKS.md— Full framework index
Overview
Generates an Architecture Decision Record (ADR) from conversation context, capturing the problem, options, decision, and rationale. It follows the standard ADR Markdown structure with sections for Context, Decision, Consequences, Alternatives, and References. The ADR is stored and numbered to preserve architectural trade-offs over time.
How This Skill Works
Parses the discussion to identify the decision, options considered, and rationale. Checks for existing ADRs to assign the next number and outputs a Markdown file named ADR-[NUMBER]: [TITLE] with metadata (Date, Status, Deciders) and the required sections.
When to Use It
- You need to create an ADR in response to a conversation or PR.
- You want to document the rationale behind a technical decision.
- You need to record why a particular technology or approach was chosen.
- You are capturing architectural trade-offs that should be preserved.
- You require traceability for future audits, reviews, or onboarding.
Quick Start
- Step 1: Identify the decision to document and collect context.
- Step 2: Draft ADR-[NUMBER]: [TITLE] with Context, Decision, Consequences, Alternatives, References sections.
- Step 3: Save to docs/adr/ or adr/ and reference the next-number ADR.
Best Practices
- Follow the ADR structure exactly: ADR-[NUMBER], Title, Date, Status, Deciders.
- Write Context in 2-4 sentences, keep Decision to 1-2 sentences.
- Detail Consequences with Positive, Negative, and Risks bullets.
- Limit Alternatives to the essential options and why rejected.
- Store the ADR under docs/adr/ or adr/ and reference related PRs or docs.
Example Use Cases
- ADR-001: Adopt PostgreSQL as the primary OLTP datastore.
- ADR-002: Switch from REST to gRPC for internal service communication.
- ADR-003: Choose Redis as a cache layer for hot data.
- ADR-004: Deploy microservices with a shared config service.
- ADR-005: Use an event-driven architecture with Kafka for cross-service events.
