MCAF: ADR Writing
Trigger On
- a dependency, boundary, platform, contract, or data model is changing
- a design decision has meaningful trade-offs that should be recorded
- a repo-wide engineering policy needs a durable rationale
Value
- produce a concrete project delta: code, docs, config, tests, CI, or review artifact
- reduce ambiguity through explicit planning, verification, and final validation skills
- leave reusable project context so future tasks are faster and safer
Do Not Use For
- feature-level behaviour details without an architecture decision
- generic architecture overview content
Inputs
docs/Architecture/Overview.md
- related feature docs
- the nearest
AGENTS.md
- current constraints, options, and risks
Quick Start
- Read the nearest
AGENTS.md and confirm scope and constraints.
- Run this skill's
Workflow through the Ralph Loop until outcomes are acceptable.
- Return the
Required Result Format with concrete artifacts and verification evidence.
Workflow
- Start from the concrete decision that must be made now.
- If the ADR is missing, scaffold it from
references/adr-template.md.
- Record:
- context and problem
- chosen decision
- alternatives considered
- trade-offs and consequences
- implementation plan
- Add diagrams only when they remove ambiguity.
- Link the ADR to affected feature docs and
docs/Architecture/Overview.md.
Deliver
docs/ADR/ADR-XXXX-short-title.md
- linked updates to architecture docs when the decision changes boundaries
Validate
- the decision and rejected alternatives are explicit
- trade-offs are concrete, not hand-wavy
- implementation impact is clear
- a future engineer can understand why this path was chosen
Ralph Loop
Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
- Plan first (mandatory):
- analyze current state
- define target outcome, constraints, and risks
- write a detailed execution plan
- list final validation skills to run at the end, with order and reason
- Execute one planned step and produce a concrete delta.
- Review the result and capture findings with actionable next fixes.
- Apply fixes in small batches and rerun the relevant checks or review steps.
- Update the plan after each iteration.
- Repeat until outcomes are acceptable or only explicit exceptions remain.
- If a dependency is missing, bootstrap it or return
status: not_applicable with explicit reason and fallback path.
Required Result Format
status: complete | clean | improved | configured | not_applicable | blocked
plan: concise plan and current iteration step
actions_taken: concrete changes made
validation_skills: final skills run, or skipped with reasons
verification: commands, checks, or review evidence summary
remaining: top unresolved items or none
For setup-only requests with no execution, return status: configured and exact next commands.
Load References
- start with
references/adr-template.md
- use
references/ADR-FORMATS.md only for numbering or formatting conventions
Example Requests
- "Write an ADR for moving to event-driven notifications."
- "Document why we are adding PostgreSQL instead of keeping SQLite."
- "Capture the policy decision behind local project AGENTS files."
1---2name: mcaf-adr-writing-43description: "Create or update an ADR under `docs/ADR/` for architectural decisions, dependency changes, data-model changes, or cross-cutting policy shifts. Use when the user asks to write, update, or document an ADR, record a design decision, capture architecture trade-offs, or justify a repo-wide technical policy."4compatibility: "Requires repository write access; produces Markdown ADRs with Mermaid diagrams."5metadata:6 source: https://skillmd.com/skills/managedcode/mcaf-adr-writing-47---89# MCAF: ADR Writing1011## Trigger On1213- a dependency, boundary, platform, contract, or data model is changing14- a design decision has meaningful trade-offs that should be recorded15- a repo-wide engineering policy needs a durable rationale1617## Value1819- produce a concrete project delta: code, docs, config, tests, CI, or review artifact20- reduce ambiguity through explicit planning, verification, and final validation skills21- leave reusable project context so future tasks are faster and safer2223## Do Not Use For2425- feature-level behaviour details without an architecture decision26- generic architecture overview content2728## Inputs2930- `docs/Architecture/Overview.md`31- related feature docs32- the nearest `AGENTS.md`33- current constraints, options, and risks3435## Quick Start36371. Read the nearest `AGENTS.md` and confirm scope and constraints.382. Run this skill's `Workflow` through the `Ralph Loop` until outcomes are acceptable.393. Return the `Required Result Format` with concrete artifacts and verification evidence.4041## Workflow42431. Start from the concrete decision that must be made now.442. If the ADR is missing, scaffold it from `references/adr-template.md`.453. Record:46 - context and problem47 - chosen decision48 - alternatives considered49 - trade-offs and consequences50 - implementation plan514. Add diagrams only when they remove ambiguity.525. Link the ADR to affected feature docs and `docs/Architecture/Overview.md`.5354## Deliver5556- `docs/ADR/ADR-XXXX-short-title.md`57- linked updates to architecture docs when the decision changes boundaries5859## Validate6061- the decision and rejected alternatives are explicit62- trade-offs are concrete, not hand-wavy63- implementation impact is clear64- a future engineer can understand why this path was chosen6566## Ralph Loop6768Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.69701. Plan first (mandatory):71 - analyze current state72 - define target outcome, constraints, and risks73 - write a detailed execution plan74 - list final validation skills to run at the end, with order and reason752. Execute one planned step and produce a concrete delta.763. Review the result and capture findings with actionable next fixes.774. Apply fixes in small batches and rerun the relevant checks or review steps.785. Update the plan after each iteration.796. Repeat until outcomes are acceptable or only explicit exceptions remain.807. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.8182### Required Result Format8384- `status`: `complete` | `clean` | `improved` | `configured` | `not_applicable` | `blocked`85- `plan`: concise plan and current iteration step86- `actions_taken`: concrete changes made87- `validation_skills`: final skills run, or skipped with reasons88- `verification`: commands, checks, or review evidence summary89- `remaining`: top unresolved items or `none`9091For setup-only requests with no execution, return `status: configured` and exact next commands.9293## Load References9495- start with `references/adr-template.md`96- use `references/ADR-FORMATS.md` only for numbering or formatting conventions9798## Example Requests99100- "Write an ADR for moving to event-driven notifications."101- "Document why we are adding PostgreSQL instead of keeping SQLite."102- "Capture the policy decision behind local project AGENTS files."