Structured MADR — MIF Compliance

Structured MADR

Machine-Readable Architectural Decision Records for the AI Era

Structured MADR is an extension of MADR (Markdown Architectural Decision Records) that adds YAML frontmatter for machine-readable metadata, comprehensive option analysis with risk assessments, and required audit sections for compliance tracking.

Why Structured MADR?

Traditional ADR formats were designed for human readers. While they capture decisions effectively, they lack:

• Machine-readable metadata for programmatic access
• Structured risk assessment for option evaluation
• Audit trails for compliance verification
• Explicit relationships between decisions

Structured MADR addresses these gaps while remaining fully human-readable and compatible with existing ADR workflows.

Key Features

Feature	Description
YAML Frontmatter	Machine-parseable metadata for tooling integration
Hierarchical Drivers	Primary and secondary decision drivers
Risk Assessment	Technical, schedule, and ecosystem risk per option
Split Consequences	Positive, negative, and neutral outcomes
Audit Section	Built-in compliance tracking with findings tables
Explicit Relationships	Typed links between related decisions

Quick Start

1. Copy the Template

curl -O https://raw.githubusercontent.com/modeled-information-format/structured-madr/main/templates/template.md
mv template.md docs/adr/0001-your-decision.md

2. Fill in the Frontmatter

---
title: "Use PostgreSQL for Primary Storage"
description: "Decision to adopt PostgreSQL as the application database"
type: adr
category: architecture
tags:
  - database
  - postgresql
status: proposed
created: 2025-01-15
updated: 2025-01-15
author: Architecture Team
project: my-application
technologies:
  - postgresql
audience:
  - developers
  - architects
---

3. Document Your Decision

Follow the template sections to capture context, options, decision, and consequences.

4. Add Audit Trail

After implementation, add audit entries to track compliance:

## Audit

### 2025-02-01

**Status:** Compliant

**Findings:**

| Finding | Files | Lines | Assessment |
|---------|-------|-------|------------|
| PostgreSQL configured | `src/db/config.rs` | L15-L45 | compliant |

**Summary:** Implementation follows ADR specifications.

**Action Required:** None

Template Structure

┌─────────────────────────────────────────────┐
│  YAML Frontmatter (Required)                │
│  - Metadata for machine parsing             │
│  - Status, dates, author, tags              │
├─────────────────────────────────────────────┤
│  # ADR-{NUMBER}: {TITLE}                    │
├─────────────────────────────────────────────┤
│  ## Status                                  │
│  - Current decision status                  │
├─────────────────────────────────────────────┤
│  ## Context                                 │
│  - Background and Problem Statement         │
│  - Current Limitations                      │
├─────────────────────────────────────────────┤
│  ## Decision Drivers                        │
│  - Primary Decision Drivers                 │
│  - Secondary Decision Drivers               │
├─────────────────────────────────────────────┤
│  ## Considered Options                      │
│  - Option 1 (with risk assessment)          │
│  - Option 2 (with risk assessment)          │
│  - ...                                      │
├─────────────────────────────────────────────┤
│  ## Decision                                │
│  - The chosen approach                      │
│  - Implementation specifics                 │
├─────────────────────────────────────────────┤
│  ## Consequences                            │
│  - Positive                                 │
│  - Negative                                 │
│  - Neutral                                  │
├─────────────────────────────────────────────┤
│  ## Decision Outcome                        │
│  - Summary and mitigations                  │
├─────────────────────────────────────────────┤
│  ## Related Decisions                       │
│  - Links to related ADRs                    │
├─────────────────────────────────────────────┤
│  ## Links                                   │
│  - External resources                       │
├─────────────────────────────────────────────┤
│  ## More Information                        │