Adr Management

ADR Status Lifecycle

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