diegosouzapw ADR (Architecture Decision Record) Skill
Create and maintain Architecture Decision Records following a consistent template.
Trigger Conditions
- A new architecture decision needs to be documented
- An existing ADR needs to be superseded or updated
- User invokes with "create ADR" or "document decision"
Input Contract
- Required: Decision context (what problem are we solving?)
- Required: Options considered (at least 2 alternatives)
- Optional: Constraints, evaluation criteria, stakeholders
Output Contract
- ADR document in markdown format with: Status, Date, Context, Decision, Consequences, Alternatives Considered
- Numbered sequentially (ADR-NNN) in the
docs/adr/directory - Links to related ADRs (supersedes, relates-to)
Tool Permissions
- Read: All project files, existing ADRs, architecture docs
- Write:
docs/adr/directory - Search: Codebase for implementation evidence
Execution Steps
- Gather the decision context from user or triggering event
- Search existing ADRs for related decisions
- Determine the next ADR number
- Draft the ADR using the standard template
- Link to related ADRs and relevant code/config
- Write the ADR file to
docs/adr/ADR-NNN-<title>.md
Success Criteria
- ADR has all required sections filled in
- Status is set (Proposed, Accepted, Deprecated, Superseded)
- Consequences section includes both positive and negative impacts
- File is written to the correct location with proper naming
Escalation Rules
- Escalate if the decision has >$1K/month cost implications
- Escalate if the decision affects regulatory compliance
- Escalate if no clear winner among alternatives
Example Invocations
Input: "We need to decide between PostgreSQL and DynamoDB for the order service"
Output: ADR-005-order-service-database.md with context (high write volume, need transactions), decision (PostgreSQL for ACID guarantees), consequences (operational overhead, need connection pooling), alternatives (DynamoDB rejected due to transaction limitations).