ADR MADR System

Provides guidance to create high-quality ADRs (MADR style) as separate files and maintain a lightweight index for discoverability.

Defines explicit outputs for each step, reduces merge conflicts, and preserves decision history via superseding instead of rewriting accepted ADRs.

Use this skill when

Making a decision that affects architecture boundaries, persistence, auth/security posture, API style, reliability/SLOs, scaling, or major vendor/tool choices.
Changing a previously accepted architectural decision (create a new ADR that supersedes the old one).

Do not use this skill when

Capturing minor implementation notes, routine refactors, or small patches with no architectural impact.

Defaults (override if the repo already has conventions)

ADR directory: docs/adr/
ADR index: docs/adr/README.md
File naming: ADR-XXXX-short-title.md (XXXX is zero-padded)
Status lifecycle: Proposed -> Accepted -> Rejected/Deprecated/Superseded

Required inputs

Decision topic and scope.
Known constraints and decision drivers (with source artifacts if available).
Existing ADR list or index location (or confirmation to use defaults).
Stakeholders or approvers if required by repo conventions.

Constraints and conventions

Follow any existing ADR templates, numbering, or status policies in the repo.
Keep ADRs as append-only history; use superseding instead of edits.
Keep ADR and index paths consistent within the same change.
Prefer repo-local paths or already-provided URLs; do not assume network access.

Workflow

Step A: Decide if an ADR is required

Output: 3-5 bullets answering:

What decision is being made?
Why now (what triggered it)?
What scope is affected?

Decision point:

If the decision is cross-cutting or long-lived, proceed with an ADR.
If it is a local implementation detail, stop and capture a brief note elsewhere.

Step B: Pull inputs from the spec

Output: a short list of constraints and decision drivers with links or paths to spec/track/task artifacts (repo-local preferred).

Constraints: must/must-not/should, deadlines, platform limits, compliance.
Drivers: ranked priorities (cost, latency, operability, DX, security, time-to-deliver).

Decision point:

If no link to a source artifact is available, record the owner to confirm before acceptance.

Step C: Consider options (minimum 2)

Output: 2-4 viable options with pros/cons evaluated against the drivers. If there is only 1 realistic option, explicitly justify why.

Step D: Record the decision

Output: a MADR document that includes:

Decision and rationale tied to drivers
Consequences (positive and negative)
Risks and mitigations
Follow-ups (implementation notes or tasks)

Use references/templates.md for templates.

Step E: Apply governance (supersedes, don’t rewrite)

Output: supersedes section populated when replacing an accepted ADR, with the old ADR left intact.

Rule: Do not edit accepted ADRs to change the rationale/decision.

If changing direction: create a new ADR and mark it as superseding the old one.
The old ADR remains as historical context.

Step F: Update the ADR index in the same change

Output: update docs/adr/README.md to include the new/updated ADR metadata and links. Use references/index-format.md for the index table format and update rules.

Step G: Self-check pitfalls

Output: a short checklist of “done” confirmations.

Every section in the template is present (no missing headings).
Decision drivers are ranked and referenced in the rationale.
Consequences include at least one tradeoff.
Supersedes section present when replacing an accepted ADR.

Output contract (always report)

New or updated ADR file path(s)
Updated ADR index path
Link(s) between ADR(s) and spec/track/task artifacts
If superseding: old ADR ID and new ADR ID
Verification commands/results when scripts are used

Reporting format:

ADRs: <list of ADR file paths>
Index: <ADR index path>
Links: <spec/track/task references>
Supersedes: <old ADR ID -> new ADR ID or "none">
Verification: <commands/results or "none">

Quality gates

Before finalizing, check references/quality-gates.md and references/README.md for the latest guidance.

SDD integration notes

When the ADR is accepted, update the relevant spec/track/task artifact to link to it (and ensure the ADR links back). See references/sdd-integration.md.

Verification

If any script from scripts/ is run, report the command(s) and result(s).
Do not claim completion without verification output when scripts are used.

Optional scripts

scripts/new_adr.sh scaffolds a new MADR file and updates the ADR index block.
scripts/update_index.sh rebuilds the ADR index block deterministically from ADR files, preserving hand-maintained Tags cells.
scripts/validate_adr.sh validates that a single MADR file contains required sections (accepts MADR-canonical heading variants).
scripts/validate_repo.sh validates all ADRs in a repo and checks index coverage.

Script requirements:

POSIX shell, awk, sed, grep (or rg), date, and standard coreutils.
No network access required.

Script usage (run from the target repo root):

ADR_DIR=docs/adr ADR_INDEX=docs/adr/README.md sh <skill-folder>/scripts/new_adr.sh "Use PostgreSQL"
ADR_DIR=docs/adr ADR_INDEX=docs/adr/README.md sh <skill-folder>/scripts/update_index.sh
sh <skill-folder>/scripts/validate_adr.sh docs/adr/ADR-0001-sample.md
ADR_DIR=docs/adr ADR_INDEX=docs/adr/README.md sh <skill-folder>/scripts/validate_repo.sh

Script verification:

Ensure the command exits with status 0 before claiming success.
Capture script output and include it in the final report when used.
If a script fails, stop and report the error output instead of continuing.

Common pitfalls

Editing accepted ADRs instead of superseding them.
Missing links back to the motivating spec/track/task.
Skipping decision drivers and ending up with untraceable rationale.
Forgetting to update the ADR index in the same change.

Examples

Example output (reporting format):

ADRs: docs/adr/ADR-0007-event-delivery.md
Index: docs/adr/README.md
Links: docs/specs/eventing.md#L40
Supersedes: none