melodic-software/adr-management

ADR Management

Note: This is the canonical ADR skill for the plugin ecosystem. For detailed ADR templates (Nygard, MADR, Enterprise), use MCP tools (perplexity, context7) to research current best practices.

When to Use This Skill

Use this skill when you need to:

• Document a technology choice or design decision
• Record why a particular approach was selected over alternatives
• Track the history of architectural decisions
• Create a searchable record of decisions for team onboarding

Keywords: adr, architecture decision record, decision log, why we chose, alternatives considered, design decision, technology choice

ADR Workflow

Creating a New ADR

1. Determine the next ADR number

   • Check existing ADRs in /architecture/adr/
   • Use sequential numbering: 0001, 0002, 0003, etc.

2. Create the ADR file

   • Location: /architecture/adr/NNNN-title-in-kebab-case.md
   • Use the template from references/adr-template.md

3. Fill in required sections

   • Status: Start with "Proposed"
   • Date: Current date in YYYY-MM-DD format
   • Context: Describe the problem and constraints
   • Decision: State the decision clearly
   • Consequences: List positive, negative, and neutral outcomes

4. Document alternatives

   • List each alternative considered
   • Include pros, cons, and why it was rejected

5. Optional: Generate context diagram

   • If visualization plugin is available, generate a diagram showing the decision's context
   • Spawn the visualization:diagram-generator agent for C4 or component diagrams
   • Or use the visualization:diagram-patterns skill for diagram type guidance

ADR Status Lifecycle

| Status | Meaning | | --- | --- | | Proposed | Decision is under discussion | | Accepted | Decision has been approved and implemented | | Deprecated | Decision is no longer relevant but kept for history | | Superseded | Decision has been replaced by a newer ADR |

When superseding an ADR:

1. Update the old ADR's status to "Superseded by ADR-XXXX"
2. Reference the old ADR in the new ADR's "Related Decisions" section

Searching Existing ADRs

Before creating a new ADR, search for existing relevant decisions:

# Search ADR titles
ls /architecture/adr/

# Search ADR content for keywords
grep -r "keyword" /architecture/adr/

Integration with Architecture Principles

Link ADRs to architecture principles when the decision:

• Implements a principle
• Makes a trade-off against a principle
• Establishes a new principle

Reference format: "This decision implements Principle P1: [Principle Name]"

Template Reference

The ADR template is available at references/adr-template.md. Key sections:

• Status: Current state of the decision
• Date: When the decision was made
• Deciders: Who was involved
• Context: Problem and constraints
• Decision: What was decided
• Consequences: Outcomes (positive, negative, neutral)
• Alternatives Considered: What else was evaluated
• Related Decisions: Links to related ADRs
• References: Supporting documentation

Best Practices

1. One decision per ADR - Keep ADRs focused
2. Immutable history - Never delete ADRs, only supersede
3. Link decisions - Reference related ADRs
4. Include context - Future readers need to understand the constraints
5. Be honest about trade-offs - Document negative consequences too

Related: Specification-Driven ADRs

If you're extracting decisions FROM specifications, consider using the spec-driven-development plugin's /spec:adr:create which links ADRs directly to specification IDs (SPEC-xxx). Those ADRs are stored in docs/adr/ (linked to specification IDs).

Both approaches use MADR format and can coexist in the same project.

Repository Structure

Ensure your project has the standard architecture directory:

/architecture/
  /adr/
    0001-record-template.md
    0002-first-decision.md
    ...

If the directory doesn't exist, create it before adding ADRs.

User-Facing Interface

When invoked directly by the user, this skill creates a new ADR.

Execution Workflow

1. Determine next ADR number by scanning existing ADRs in /architecture/adr/ (sequential: 0001, 0002, etc.)
2. Create the ADR file using the standard template with sequential numbering, initial status "Proposed", current date (UTC), and title from arguments
3. Report the created file path so the user can complete the Context, Decision, and Consequences sections

Example Usage

/ea:adr-management Use PostgreSQL for persistence
/ea:adr-management Adopt microservices architecture

Version History

• v1.0.0 (2025-12-05): Initial release
  • ADR creation and management workflow
  • Status lifecycle documentation
  • Integration with architecture principles
  • Template reference and best practices

---

Last Updated

Date: 2025-12-05 Model: claude-opus-4-5-20251101