shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

adr-madr-system

Create, review, and maintain Architecture Decision Records (MADR) as individual files plus an ADR index when documenting or superseding architectural decisions. Focuses on decision drivers, options, consequences, and supersedes semantics so accepted ADRs remain immutable.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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