adr

name	adr
description	Manage Architecture Decision Records and ADR-aligned development. Use when user says "we should use", "let's go with", asks "why did we choose X?", implements a feature that may have an ADR, updates ADR status, or needs to check alignment with existing decisions.

Manage Architecture Decision Records (ADRs) throughout their lifecycle: read existing decisions, write new ones, and ensure development aligns with documented decisions. Title must clearly state the decision (not the problem) Context must explain WHY this decision is needed now At least 2 options must be genuinely considered Consequences must include both positive AND negative impacts See `template.md` for the MADR structure (status, context, drivers, options, consequences) See `operations.md` for directory discovery, naming conventions, commit integration, deprecation (`_` prefix), and ADR-aligned development workflow See `queries.md` for finding ADRs by topic, status, or relationship Finding and understanding existing decisions "why did we choose X?", "what's our approach to Y?", "is there an ADR for Z?" 1. Discover ADR directory (see `operations.md`) 2. Search for relevant ADRs by keyword/topic 3. Summarize the decision and its rationale 4. Note if the ADR is active, deprecated, or superseded Creating new architecture decision records "we should use", "let's go with", "I've decided to", trade-off discussions 1. Check for existing ADRs on the topic (may need to supersede) 2. Gather information through clarifying questions 3. Draft ADR using `template.md` 4. Save and commit (amend later if needed) Ensuring development aligns with documented decisions Implementing features, making architectural changes, deviating from existing patterns 1. Before implementation: Check for relevant ADRs 2. During implementation: Reference ADR in commits 3. On completion: Update ADR status (proposed -> accepted) 4. On deviation: Create superseding ADR, deprecate old one with `_` prefix

<best_practices> Decision drivers must link to actual project constraints Confirmation section must describe how to validate the decision Link to related ADRs when relevant Update status when implemented or superseded </best_practices>

<anti_patterns> Recording a decision without documenting alternatives Always document alternatives considered Generic or unclear trade-offs Be specific about trade-offs ADR doesn't answer "why this, why now" The ADR should answer "why this, why now" ADRs not linked to related decisions Link to related ADRs when relevant ADRs with outdated status Update status when implemented or superseded Deviating from an ADR without recording the change If you deviate from an ADR, create a new one </anti_patterns>

Based on MADR - Markdown Architectural Decision Records (Version 4.0, 2024)