# Adr > 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. Use when this capability is needed. - Skill: `tomevault-io/adr` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/adr` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/adr/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/adr --- # INSTRUCTIONS Manage Architecture Decision Records (ADRs) throughout their lifecycle: read existing decisions, write new ones, and ensure development aligns with documented decisions. - **Template**: See `template.md` for the MADR structure (status, context, drivers, options, consequences) - **Operations**: See `operations.md` for directory discovery, naming conventions, commit integration, deprecation (`_` prefix), and ADR-aligned development workflow - **Queries**: See `queries.md` for finding ADRs by topic, status, or relationship ## Modes ### Read Mode **Trigger**: "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 ### Write Mode **Trigger**: "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) ### ADR-Aligned Development Mode **Trigger**: 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 ## Quality Checklist Before finalizing an ADR: - [ ] Title clearly states the decision (not the problem) - [ ] Context explains WHY this decision is needed now - [ ] At least 2 options were genuinely considered - [ ] Decision drivers link to actual project constraints - [ ] Consequences include both positive AND negative impacts - [ ] Confirmation section describes how to validate the decision ## Anti-Patterns - **Decision without options**: Always document alternatives considered - **Vague consequences**: Be specific about trade-offs - **Missing "why"**: The ADR should answer "why this, why now" - **Orphan ADRs**: Link to related ADRs when relevant - **Stale ADRs**: Update status when implemented or superseded - **Undocumented deviation**: If you deviate from an ADR, create a new one ## Reference Based on [MADR - Markdown Architectural Decision Records](https://adr.github.io/madr/) (Version 4.0, 2024) --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/atusy) — claim your Tome and manage your conversions.