MADR Decision Records

MADR Decision Records

Purpose

MADR (Markdown Any Decision Records) is a lean template for recording decisions. This skill provides patterns for documenting architectural and technical decisions in a consistent, reviewable format.

When to Use This Skill

• Making significant technical decisions
• Choosing between alternatives
• Documenting constraints and trade-offs
• Recording decisions for future reference
• During Roundtable convergence

Core Concepts

• Context-Decision-Consequences: Every ADR captures why, what, and impact
• Alternatives Considered: Document rejected options to prevent revisiting
• Status Lifecycle: proposed → accepted → deprecated/superseded
• Immutability: ADRs are append-only; supersede rather than modify

ADR Naming Convention (MADR Official)

NNNN-title-with-dashes.md

Examples:
0001-component-separation.md
0002-inline-orchestration.md
0015-api-versioning-strategy.md

Rules:

• 4-digit zero-padded number (supports up to 9,999 ADRs)
• Lowercase title with dashes as word separators
• .md extension
• Sequential numbering

MADR Template (Official Format)

# {Short Title of Solved Problem and Solution}

## Status

{proposed | accepted | deprecated | superseded by [ADR-NNNN](NNNN-slug.md)}

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question.}

## Decision Drivers

- {decision driver 1, e.g., a force, facing concern, ...}
- {decision driver 2, e.g., a force, facing concern, ...}
- ...

## Considered Options

- {title of option 1}
- {title of option 2}
- {title of option 3}
- ...

## Decision Outcome

Chosen option: "{title of option 1}", because {justification. e.g., only option which meets k.o. criterion decision driver | which resolves force {force} | ... | comes out best (see below)}.

### Consequences

- Good, because {positive consequence, e.g., improvement of one or more desired qualities, ...}
- Bad, because {negative consequence, e.g., compromising one or more desired qualities, ...}
- Neutral, because {neutral consequence, e.g., no impact on desired qualities, ...}

## Pros and Cons of the Options

### {title of option 1}

{example | description | pointer to more information | ...}

- Good, because {argument a}
- Good, because {argument b}
- Neutral, because {argument c}
- Bad, because {argument d}
- ...

### {title of option 2}

{example | description | pointer to more information | ...}

- Good, because {argument a}
- Good, because {argument b}
- Neutral, because {argument c}
- Bad, because {argument d}
- ...

## More Information

{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when/how this decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}

Status Lifecycle

proposed → accepted → [deprecated | superseded]
    ↓
  rejected

Status	Meaning
proposed	Under discussion, not yet decided
accepted	Decision made and in effect
deprecated	No longer applicable
superseded	Replaced by newer decision (link to new ADR)
rejected	Considered but not chosen

Minimal Template

For simpler decisions, use this minimal variant:

# {Title}

## Status

{status}

## Context and Problem Statement

{context}

## Decision Outcome

Chosen option: "{option}", because {justification}.

### Consequences

- Good, because {positive}
- Bad, because {negative}

Quick Reference Examples

Technology Choice ADR

# Use PostgreSQL for Primary Database

## Status

accepted

## Context and Problem Statement

We need a database for user data and application state. Which database should we use?

## Decision Drivers

- ACID transactions required
- Complex query support needed
- Team familiarity
- Proven reliability at scale

## Considered Options

- PostgreSQL
- MongoDB
- MySQL

## Decision Outcome

Chosen option: "PostgreSQL", because it provides strong ACID guarantees, excellent query capabilities, and the team has production experience with it.

### Consequences

- Good, because mature ecosystem with excellent tooling
- Good, because team already familiar
- Bad, because requires operational knowledge for scaling
- Neutral, because hosting costs similar to alternatives

Architecture Pattern ADR

# Adopt Event-Driven Architecture for Async Operations

## Status

proposed

## Context and Problem Statement

Some operations are long-running and shouldn't block API responses. How should we handle asynchronous operations?

## Considered Options

- Synchronous with timeout
- Background jobs with polling
- Event-driven with message queue

## Decision Outcome

Chosen option: "Event-driven with message queue", because it provides decoupling, scalability, and built-in retry handling.

### Consequences

- Good, because services are decoupled
- Good, because scales horizontally
- Bad, because adds infrastructure complexity
- Bad, because debugging distributed flows is harder

Integration with S2S

In Spec2Ship projects:

Scope	Location	Created by
Internal (WIP)	.s2s/decisions/	/s2s:design
External (public)	docs/decisions/ or docs/architecture/decisions/	Future /s2s:export

Writing behavior:

• All commands (/s2s:design, etc.) write ADRs to .s2s/decisions/
• External/public ADRs are created via export command (to be implemented)

Reading behavior (for exploration agents and /s2s:plan):

• First check docs/ paths (exported/public - higher priority)
• Then check .s2s/decisions/ (internal/working)
• This ensures public documentation takes precedence

Naming:

• Internal: NNNN-slug.md (4-digit, zero-padded)
• External: Same format, exported to project docs folder

ADR Index Template

For decisions/README.md:

# Architecture Decision Records

| # | Decision | Status | Date |
|---|----------|--------|------|
| [0001](0001-slug.md) | Title | accepted | YYYY-MM-DD |
| [0002](0002-slug.md) | Title | accepted | YYYY-MM-DD |

## Status Legend

- **accepted**: currently in effect
- **proposed**: under discussion
- **deprecated**: no longer applicable
- **superseded**: replaced by another ADR
- **rejected**: considered but not adopted