Structured MADR Format

Structured MADR is an extension of MADR (Markdown Architectural Decision Records) that adds YAML frontmatter for metadata, comprehensive option analysis, and mandatory audit sections for compliance tracking.

About Structured MADR

Structured MADR is:

• Metadata-rich - YAML frontmatter for structured metadata
• Comprehensive - Full option analysis with risk assessments
• Auditable - Built-in audit section for compliance tracking
• MADR-compatible - Uses standard MADR status values and concepts

Key Differences from Standard MADR

Aspect	Standard MADR	Structured MADR
Frontmatter	None	Required YAML
Option Analysis	Pros/cons lists	Full narrative with risk assessment
Consequences	Single section	Positive/Negative/Neutral split
Audit Trail	None	Required section
Metadata	Inline in "More Information"	Structured in frontmatter
Decision Drivers	Single list	Primary/Secondary hierarchy

Template Structure

Required YAML Frontmatter

---
title: "Decision Title"
description: "Brief description of the decision"
type: adr
category: architecture|api|migration|performance|security|...
tags:
  - relevant-tag
status: proposed|accepted|deprecated|superseded
created: YYYY-MM-DD
updated: YYYY-MM-DD
author: Author Name
project: project-name
technologies:
  - technology-name
audience:
  - developers
  - architects
related:
  - adr_0001.md
---

Frontmatter Fields

Field	Required	Description
title	Yes	Short descriptive title
description	Yes	One-sentence summary
type	Yes	Always adr
category	Yes	Decision category (architecture, api, migration, etc.)
tags	Yes	List of relevant tags
status	Yes	Current status (proposed, accepted, deprecated, superseded)
created	Yes	Creation date (YYYY-MM-DD)
updated	Yes	Last update date (YYYY-MM-DD)
author	Yes	Decision author
project	Yes	Project name
technologies	No	List of technologies involved
audience	No	Target audience (developers, architects, etc.)
related	No	List of related ADR filenames

Status Values

Structured MADR uses standard MADR status values:

• proposed - Decision is under consideration
• accepted - Decision has been approved and is in effect
• deprecated - Decision is no longer recommended
• superseded - Decision has been replaced by another ADR

Section Guide

Title (H1)

Format: # ADR-{NUMBER}: {TITLE}

The title should match the frontmatter title field.

Status

Repeat the status from frontmatter. Include supersession information if applicable:

## Status

Accepted

Supersedes ADR-0003

Context

Split into subsections for clarity:

## Context

### Background and Problem Statement

{Describe the situation requiring a decision}

### Current Limitations

{List specific limitations being addressed}

Decision Drivers

Hierarchical organization:

## Decision Drivers

### Primary Decision Drivers

1. **Performance**: Must handle 10k requests/second
2. **Reliability**: 99.9% uptime requirement

### Secondary Decision Drivers

1. **Team Familiarity**: Prefer known technologies
2. **Cost**: Budget constraints

Considered Options

Each option gets comprehensive analysis:

### Option 1: PostgreSQL

**Description**: Use PostgreSQL as the primary database.

**Technical Characteristics**:
- ACID compliance
- Rich query language
- Mature ecosystem

**Advantages**:
- Strong consistency guarantees
- Excellent tooling support

**Disadvantages**:
- Horizontal scaling requires additional tooling
- Higher operational complexity

**Risk Assessment**:
- **Technical Risk**: Low. Mature and well-documented.
- **Schedule Risk**: Low. Team has existing expertise.
- **Ecosystem Risk**: Low. Large community and vendor support.

Decision

State the decision clearly with implementation details:

## Decision

We will use PostgreSQL 15 as the primary database.

The implementation will use:
- **pgBouncer** for connection pooling
- **pg_stat_statements** for query analysis
- **Citus** for horizontal scaling if needed

Consequences

Split into categories:

## Consequences

### Positive

1. **Strong Consistency**: ACID guarantees simplify application logic
2. **Query Flexibility**: Complex queries without additional tooling

### Negative

1. **Operational Overhead**: Requires DBA expertise for optimization
2. **Scaling Complexity**: Horizontal scaling needs additional planning

### Neutral

1. **Migration Required**: Existing SQLite data must be migrated

Decision Outcome

Summarize achievements and mitigations:

## Decision Outcome

PostgreSQL adoption achieves our primary objectives:
- Handles 10k requests/second with read replicas
- 99.9% uptime via managed service

Mitigations:
- Use managed PostgreSQL to reduce operational overhead
- Document scaling strategy before hitting growth thresholds

Related Decisions

Link to related ADRs:

## Related Decisions

- [ADR-0001: Use Rust](adr_0001.md) - Language choice that informed library selection
- [ADR-0005: Event Sourcing](adr_0005.md) - Depends on this storage decision

Links

External resources:

## Links

- [PostgreSQL Documentation](https://www.postgresql.org/docs/) - Official docs
- [Citus Data](https://www.citusdata.com/) - Horizontal scaling extension

More Information

Metadata section:

## More Information

- **Date:** 2025-01-15
- **Source:** SPEC-2025-01-15: Database Selection
- **Related ADRs:** ADR-0001, ADR-0005

Audit (Required)

The audit section tracks compliance:

## Audit

### 2025-01-20

**Status:** Compliant

**Findings:**

| Finding | Files | Lines | Assessment |
|---------|-------|-------|------------|
| PostgreSQL connection configured | `src/db/pool.rs` | L15-L45 | compliant |
| pgBouncer deployed | `deploy/k8s/pgbouncer.yaml` | L1-L50 | compliant |

**Summary:** Database implementation follows ADR specifications.

**Action Required:** None

Audit Section Guidelines

Audit Status Values

• Pending - Not yet audited
• Compliant - Implementation matches decision
• Non-Compliant - Implementation deviates from decision
• Partial - Some aspects compliant, others not

Assessment Values

• compliant - Finding confirms adherence
• non-compliant - Finding shows deviation
• partial - Partially implemented

When to Audit

• After initial implementation
• After major refactoring
• During periodic compliance reviews
• When related ADRs change

Creating Structured MADR ADRs

# Copy template
cp ${CLAUDE_PLUGIN_ROOT}/templates/structured-madr/adr-template.md docs/adr/adr_0001.md

Structured MADR Best Practices

Do

• Fill all required frontmatter fields
• Provide comprehensive option analysis with risk assessments
• Split consequences into Positive/Negative/Neutral
• Keep audit section updated after implementation
• Link related ADRs bidirectionally

Don't

• Leave placeholder text in published ADRs
• Skip the audit section (it's required)
• Use non-standard status values
• Forget to update the updated date on changes
• Mix MADR and Structured MADR formats in one project

Comparison with Other Formats

Aspect	Structured MADR	MADR	Nygard
Sections	12+	10	5
Frontmatter	Required	None	None
Option detail	Full narrative	Pros/cons	Implicit
Audit trail	Required	None	None
Best for	Regulated/audited projects	Tech decisions	Quick records

When to Use Structured MADR

Best for:

• Projects requiring compliance auditing
• Complex decisions with multiple stakeholders
• Regulated industries (finance, healthcare)
• Teams wanting comprehensive documentation
• Long-lived projects where decisions need tracking

Consider other formats when:

• Quick, simple decisions
• Small teams with informal processes
• Decisions unlikely to need auditing
• Preference for brevity over comprehensiveness

Searching Structured MADR Collections

When asked to search, find, or navigate a collection of Structured MADR records, do not read every ADR end-to-end. SMADR's required YAML frontmatter is a cheap structured index. Use the frontmatter-first, progressive-disclosure protocol:

1. Index: extract only the --- frontmatter from every docs/adr/[0-9]*.md into a compact triage table.
2. Filter and rank: narrow by status, category, tags, technologies, audience, created/updated, and the related cross-reference graph. When reporting results, briefly state why each excluded record was dropped (e.g. "excluded: category ui, not database" or "excluded: status proposed, not accepted") — not just which records matched.
3. Deep-read: read full bodies only for the shortlist, then follow related: links (resolve by ADR number, not exact filename).

For small collections (fewer than ~10 records) just read each frontmatter block directly. See references/frontmatter-first-search.md for copy-pasteable recipes.

Additional Resources

Reference Files

• references/frontmatter-first-search.md - Frontmatter-first progressive-disclosure search for SMADR collections
• references/structured-madr-examples.md - Complete Structured MADR examples

Templates

Template available at: ${CLAUDE_PLUGIN_ROOT}/templates/structured-madr/adr-template.md

Related Skills

• adr-fundamentals - ADR basics and lifecycle management
• adr-quality - Quality criteria and review process
• adr-compliance - Auditing ADRs against code
• adr-format-madr - Standard MADR format
• adr-decision-drivers - Identifying decision drivers

Configuration

Enable in .claude/adr.local.md:

default_format: structured-madr