Madr Template Engine

MADR Template Engine — ADR Standard Format Tool

A specialized skill that enhances the ADR documentation capabilities of the adr-author and impact-tracker agents.

Target Agents

• adr-author — MADR format ADR document writing
• impact-tracker — Inter-ADR dependency tracking, status management

MADR Standard Template

# ADR-{NNN}: {Decision Title}

## Status

{Proposed | Accepted | Deprecated | Superseded by ADR-XXX}

## Date

{YYYY-MM-DD}

## Context

{Background, problem situation, and constraints that led to this decision}

## Decision Drivers

* {Driver 1: e.g., Response time must be under 200ms}
* {Driver 2: e.g., Learning curve for a team of 5}
* {Driver 3: e.g., Monthly budget constraint of $X}

## Considered Alternatives

### Alternative 1: {Name}

{Description}

* Pro: {Benefit, because ...}
* Pro: {Benefit, because ...}
* Con: {Drawback, because ...}

### Alternative 2: {Name}

{Description}

* Pro: {Benefit, because ...}
* Con: {Drawback, because ...}
* Con: {Drawback, because ...}

### Alternative 3: {Name}

{Description — compare at least 3 alternatives}

## Decision

We choose Alternative {N}: {Name}.

### Selection Rationale

{Specific reasons for choosing this alternative}

### Rejection Rationale

* Alternative {X} was rejected because: {Reason}
* Alternative {Y} was rejected because: {Reason}

## Consequences

### Positive Impact

* {Expected positive outcome}

### Negative Impact

* {Tradeoff that must be accepted}

### Follow-up Actions

* [ ] {Required follow-up task 1}
* [ ] {Required follow-up task 2}

## Related ADRs

* ADR-{XXX}: {Related decision}
* ADR-{YYY}: {Decision affected by this one}

ADR Status Management

Status Transition Diagram

[Proposed] -> [Accepted] -> [Deprecated]
                    |
              [Superseded by ADR-XXX]

ADR Numbering System

Numbering Rules

ADR-{Sequence}: {Category Code}-{Decision Title}

Category Codes:
  ARCH - Architecture patterns
  DATA - Data storage/processing
  INFRA - Infrastructure/deployment
  SEC - Security
  API - API design
  UI - Frontend
  PROC - Process/methodology

ADR Directory Structure

docs/adr/
├── 0001-arch-monolith-vs-microservice.md
├── 0002-data-postgresql-selection.md
├── 0003-infra-kubernetes-adoption.md
├── 0004-api-rest-vs-graphql.md
├── index.md  <- ADR list and status dashboard
└── template.md

ADR Writing Quality Checklist

Required Elements

• Does the context sufficiently explain the background?
• Are the decision drivers clear?
• Were at least 3 alternatives compared?
• Are the pros and cons of each alternative specific?
• Is the selection rationale logical?
• Are rejection reasons explicitly stated?
• Are tradeoffs honestly described?
• Are follow-up actions specific?

Common Mistakes

ADR Dependency Graph (for impact-tracker)

### ADR Dependency Map

ADR-001 (Microservices)
  ├── ADR-002 (Inter-service communication: gRPC)
  ├── ADR-003 (Service discovery: Consul)
  ├── ADR-004 (Distributed tracing: Jaeger)
  └── ADR-005 (API Gateway: Kong)
       └── ADR-006 (Authentication: OAuth2 + JWT)

Impact Analysis:
If ADR-001 is Deprecated -> ADR-002 through ADR-006 all require re-review