From adr
This skill should be used when the user asks about "structured MADR", "structured-madr", "frontmatter ADR", "comprehensive ADR", "auditable ADR", or needs guidance on creating ADRs using the Structured MADR format with YAML frontmatter and audit sections.
npx claudepluginhub zircote/adrThis skill uses the workspace's default tool permissions.
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.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Uses ctx7 CLI to fetch current library docs, manage AI coding skills (install/search/generate), and configure Context7 MCP for AI editors.
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.
Structured MADR is:
| 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 |
---
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
---
| 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 |
Structured MADR uses standard MADR status values:
Format: # ADR-{NUMBER}: {TITLE}
The title should match the frontmatter title field.
Repeat the status from frontmatter. Include supersession information if applicable:
## Status
Accepted
Supersedes ADR-0003
Split into subsections for clarity:
## Context
### Background and Problem Statement
{Describe the situation requiring a decision}
### Current Limitations
{List specific limitations being addressed}
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
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.
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
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
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
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
External resources:
## Links
- [PostgreSQL Documentation](https://www.postgresql.org/docs/) - Official docs
- [Citus Data](https://www.citusdata.com/) - Horizontal scaling extension
Metadata section:
## More Information
- **Date:** 2025-01-15
- **Source:** SPEC-2025-01-15: Database Selection
- **Related ADRs:** ADR-0001, ADR-0005
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
# Copy template
cp ${CLAUDE_PLUGIN_ROOT}/templates/structured-madr/adr-template.md docs/adr/adr_0001.md
updated date on changes| 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 |
Best for:
Consider other formats when:
Template available at:
${CLAUDE_PLUGIN_ROOT}/templates/structured-madr/adr-template.md
Enable in .claude/adr.local.md:
default_format: structured-madr