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:
• Index:
• 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.
• scripts/validate_adr.sh validates that a single MADR file contains required sections.
• 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:

• ADR_DIR=docs/adr ADR_INDEX=docs/adr/README.md ./adr-madr-system/scripts/new_adr.sh "Use PostgreSQL"
• ADR_DIR=docs/adr ADR_INDEX=docs/adr/README.md ./adr-madr-system/scripts/update_index.sh
• ./adr-madr-system/scripts/validate_adr.sh docs/adr/ADR-0001-sample.md
• ADR_DIR=docs/adr ADR_INDEX=docs/adr/README.md ./adr-madr-system/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