Architecture decisions

Use an ADR for a durable architectural choice with meaningful alternatives or consequences. Routine fixes and established implementation choices need no new ADR. Consult relevant accepted records before changing their governed code.

Capture the decision

Read the project's instructions, existing decision index, relevant records, dependencies, and affected code. Reuse existing conventions. In a Brain tree, write prose as .svx.

Extract intent from the request and sources. Ask only for missing decisions that prevent an accurate record. A request to document a settled decision needs no preliminary interview or confirmation round. Keep an unapproved choice proposed; do not accept it merely because it ranked first in a queue.

Capture the trigger, constraints, considered alternatives, selected option, consequences, non-goals, and conditions for revisiting it. Distinguish the user's decision from the agent's recommendation.

Write and verify

Use template variants to choose the simple or MADR template in assets/templates/. Include affected paths, patterns, implementation steps, and observable validation where implementation is in scope. Name only skills actually needed for that work.

Read the review checklist after drafting. Fix factual and completeness gaps from sources. Ask about unresolved consequential choices, not ordinary editing. Add a diagram only when it clarifies architecture; verify any tool or slash command before invoking it.

Link the ADR to governed code and implementation receipts. A short code reference at the relevant boundary is enough. Update the existing index and visual links when applicable.