Agent skill
adr-authoring
This skill should be used when writing Architecture Decision Records (ADRs), documenting technical decisions, or reviewing architecture choices. Triggers on phrases like "document this decision", "create ADR", "architecture decision", "why did we choose", "record the decision", "MADR template", or when the user is working on plan files that contain ADR sections.
Install this agent skill to your Project
npx add-skill https://github.com/ddunnock/claude-plugins/tree/main/skills/speckit-generator/skills/adr-authoring
SKILL.md
Architecture Decision Record Authoring
Write clear, useful ADRs that capture the context, options, and rationale behind technical decisions. Good ADRs prevent re-litigation of decisions and help new team members understand the codebase.
Quick Reference
MADR Template Levels
| Level | When to Use | Required Fields |
|---|---|---|
| Lightweight | Quick decisions, low impact | Status, Context, Decision, Consequences |
| Standard | Most architectural decisions | + Date, Decision-makers, Drivers, Options |
| Full | Critical/reversible decisions | + Confirmation, Traceability |
ADR Lifecycle
proposed → accepted → [deprecated → superseded]
↘ rejected
Lightweight ADR Template
For quick decisions with limited impact:
### ADR-XXX: [Short Title]
**Status**: proposed | accepted | rejected | deprecated | superseded
**Context and Problem Statement**
[2-3 sentences describing the situation and what needs to be decided]
**Decision Outcome**
Chosen option: "[Option name]"
[1-2 sentences explaining why]
**Consequences**
- Good: [positive outcomes]
- Bad: [negative outcomes or trade-offs]
Standard ADR Template
For most architectural decisions:
### ADR-XXX: [Short Title]
**Status**: proposed | accepted | rejected | deprecated | superseded
**Date**: YYYY-MM-DD
**Decision-makers**: [names or roles]
**Context and Problem Statement**
[2-3 sentences describing the situation requiring a decision.
What is the issue? Why does it need to be addressed now?]
**Decision Drivers**
- [Driver 1: e.g., "Need to support 10x current load"]
- [Driver 2: e.g., "Team has no experience with technology X"]
- [Driver 3: e.g., "Budget constraint of $X/month"]
**Considered Options**
1. [Option 1 name]
2. [Option 2 name]
3. [Option 3 name]
**Decision Outcome**
Chosen option: "[Option N]" because [1-2 sentence rationale linking to drivers].
**Consequences**
- Good: [positive outcome 1]
- Good: [positive outcome 2]
- Bad: [trade-off or negative outcome]
- Neutral: [side effect that's neither good nor bad]
Full ADR Template
For critical decisions requiring traceability:
### ADR-XXX: [Short Title]
**Status**: proposed | accepted | rejected | deprecated | superseded
**Date**: YYYY-MM-DD
**Decision-makers**: [names or roles]
**Context and Problem Statement**
[Detailed context with background information.
Include relevant constraints and dependencies.]
**Decision Drivers**
- [Driver 1 with quantifiable metric if possible]
- [Driver 2]
- [Driver 3]
**Considered Options**
1. **[Option 1 name]**: [Brief description]
2. **[Option 2 name]**: [Brief description]
3. **[Option 3 name]**: [Brief description]
**Pros and Cons of Options**
#### Option 1: [Name]
- Good: [Pro 1]
- Good: [Pro 2]
- Bad: [Con 1]
#### Option 2: [Name]
- Good: [Pro 1]
- Bad: [Con 1]
- Bad: [Con 2]
#### Option 3: [Name]
- Good: [Pro 1]
- Neutral: [Neither good nor bad]
- Bad: [Con 1]
**Decision Outcome**
Chosen option: "[Option N]" because [rationale].
**Consequences**
- Good: [outcome 1]
- Bad: [outcome 2]
**Confirmation**
[How will we verify this decision was correct?]
- [Metric or checkpoint 1]
- [Metric or checkpoint 2]
**Traceability**
- Requirements: REQ-XXX, REQ-YYY
- Tasks: TASK-XXX, TASK-YYY
- Supersedes: ADR-ZZZ (if applicable)
Writing Effective ADRs
Context Section
Do:
- State the problem clearly in 2-3 sentences
- Include relevant constraints (time, budget, team skills)
- Mention what triggered this decision
Don't:
- Write a novel (save details for options analysis)
- Assume reader knows the background
- Include the solution in the context
Decision Drivers
Quantify when possible:
| Vague | Specific |
|---|---|
| "Need better performance" | "Must handle 1000 req/sec" |
| "Team preference" | "3 of 4 developers have React experience" |
| "Cost concerns" | "Budget limit: $500/month" |
Considered Options
Include at least 2 options. Always include:
- The chosen option
- The obvious alternative
- "Do nothing" if applicable
Consequences
Be honest about trade-offs:
**Consequences**
- Good: Reduces API latency by 40%
- Good: Team already knows this technology
- Bad: Adds operational complexity (new service to maintain)
- Bad: Vendor lock-in to AWS
- Neutral: Requires migration of existing data (one-time effort)
ADR Numbering
Use sequential numbering within the project:
ADR-001: Database Selection
ADR-002: Authentication Strategy
ADR-003: API Versioning Approach
For domain-specific ADRs in larger projects:
ADR-AUTH-001: OAuth Provider Selection
ADR-DATA-001: Cache Strategy
ADR-INFRA-001: Container Orchestration
When to Write an ADR
| Situation | ADR Level |
|---|---|
| Choosing a database | Standard or Full |
| Selecting a framework | Standard |
| API design patterns | Standard |
| Deployment strategy | Standard or Full |
| Library selection | Lightweight |
| Code organization | Lightweight |
| Naming conventions | Lightweight (or skip) |
Integration with SpecKit
ADRs created during /speckit.plan should:
- Use consistent numbering - ADR-001, ADR-002, etc.
- Reference requirements - Link to REQ-XXX from spec
- Be validated -
/speckit.analyzechecks ADR completeness - Trace to tasks - Tasks reference implementing ADRs
Additional Resources
For detailed patterns and examples, see:
references/madr-full-template.md- Complete MADR template with all fieldsreferences/adr-examples.md- Real-world ADR examples
Checklist Before Finalizing
- Status is set (proposed for new ADRs)
- Context explains WHY a decision is needed
- At least 2 options were considered
- Decision clearly states the chosen option
- Consequences include both good AND bad
- Date and decision-makers are recorded (Standard+)
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
ddunnock/claude-plugins
streaming-output
Stream long-form content to markdown files with resume capability. Writes content incrementally with section markers, enabling recovery if context limits are hit. Use when generating long documents (over 1000 lines), B-SPEC or specification writing, multi-section reports, any task where context compaction may occur mid-generation, or when user explicitly requests streaming output. Commands: init, write, status, resume, finalize, repair.
ddunnock/claude-plugins
fishbone-diagram
Create comprehensive Fishbone (Ishikawa/Cause-and-Effect) diagrams for structured root cause brainstorming. Guides teams through problem definition, category selection (6Ms, 8Ps, 4Ss, or custom), cause identification, sub-cause drilling, prioritization via multi-voting, and 5 Whys integration. Generates visual SVG diagrams and professional HTML reports. Use when brainstorming potential causes, conducting root cause analysis, facilitating quality improvement sessions, analyzing defects or failures, structuring team problem-solving, or when user mentions "fishbone", "Ishikawa", "cause and effect diagram", "6Ms", "cause analysis", or "brainstorming causes".
ddunnock/claude-plugins
streaming-output-mcp
Stream structured content to persistent SQLite storage with automatic session break recovery. Core principle: The content IS the state. Every stream_write is automatically persistent. Supports multi-format export (Markdown, HTML, JSON, YAML, CSV, Text) and 7 document templates. Commands: /stream-init, /stream-status, /stream-read, /stream-write, /stream-export. ALWAYS call stream_status after session breaks to check for resume_from and preserved_context.
ddunnock/claude-plugins
fmea-analysis
Conduct Failure Mode and Effects Analysis (FMEA) for systematic identification and risk assessment of potential failures in designs, processes, or systems. Supports DFMEA (Design), PFMEA (Process), and FMEA-MSR (Monitoring & System Response). Uses AIAG-VDA 7-step methodology with Action Priority (AP) risk assessment replacing traditional RPN. Use when analyzing product designs for potential failures, evaluating manufacturing process risks, conducting proactive risk assessment, preparing for APQP/PPAP submissions, investigating field failures, or when user mentions "FMEA", "failure mode", "DFMEA", "PFMEA", "severity occurrence detection", "RPN", "Action Priority", "design risk analysis", or needs to identify and prioritize potential failure modes with their causes and effects.
ddunnock/claude-plugins
problem-definition
Guide RCCA/8D problem definition using 5W2H and IS/IS NOT analysis. Transforms scattered failure data into precise, measurable problem statements that bound investigation scope without embedding cause or solution. Use when defining problems for root cause analysis, writing D2 sections of 8D reports, analyzing nonconformances, investigating failures, or when user mentions problem definition, problem statement, RCCA, 8D, failure analysis, or corrective action.
ddunnock/claude-plugins
kepner-tregoe-analysis
Conduct Kepner-Tregoe (KT) Problem Solving and Decision Making (PSDM) analysis using the four rational processes - Situation Appraisal, Problem Analysis, Decision Analysis, and Potential Problem Analysis. Use when performing structured root cause analysis, making complex decisions, evaluating alternatives with weighted criteria, conducting IS/IS NOT specification analysis, anticipating implementation risks, troubleshooting complex issues, or when user mentions "Kepner-Tregoe", "KT method", "IS/IS NOT", "situation appraisal", "decision analysis", "MUSTS and WANTS", "potential problem analysis", or needs systematic problem-solving methodology. Includes specification matrices, decision scoring, quality rubrics, and professional report generation.
Didn't find tool you were looking for?