adr-writer_skill

Overview

This skill creates and maintains Architecture Decision Records (ADRs) in Confluence. It helps teams document technical decisions, capture alternatives and trade-offs, and keep a searchable index of decisions for onboarding and audits. Use it to publish, update, or deprecate ADRs and to keep architecture history accurate.

How this skill works

I gather the decision context, options evaluated, rationale, and consequences, then format that content using a standard ADR template (number, date, status, context, decision, consequences, updates). I create or update the ADR page in Confluence, add it to the ADR index, and link related records. I can also change status (Proposed, Accepted, Deprecated, Superseded, Rejected) and append updates or lessons learned over time.

When to use it

• You need to record a new architectural or technology decision
• You want to capture why a chosen solution was selected and which alternatives were considered
• You need to publish an ADR to Confluence and update the ADR index
• A decision’s context or consequences change and you must add updates or deprecate it
• Onboard new engineers and provide a historical rationale for past choices

Best practices

• Write ADRs as decisions occur; capture context while it’s fresh
• Use the consistent template: number, date, status, decision makers, context, decision, consequences
• Be specific: include metrics, constraints, and concrete examples where possible
• Document trade-offs honestly; list positive and negative consequences and mitigation steps
• Link related ADRs and keep an ADR index for quick discovery

Example use cases

• Select a primary database (PostgreSQL vs MySQL vs NoSQL) and publish the rationale
• Decide on deployment strategy (ECS Fargate vs Kubernetes) and record operational impacts
• Adopt an authentication method (OAuth2, SSO) with security trade-offs and rollout plan
• Choose a frontend framework (React vs Vue) and note team expertise and long-term maintenance costs
• Record a process change (microservices migration, feature flagging rollout) with phased rollout and success metrics