# Architecture Decision > Creates an Architecture Decision Record (ADR) documenting a significant technical decision, its context, alternatives considered, and consequences. Every major technical choice should have an ADR. - Skill: `tomevault-io/architecture-decision` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/architecture-decision` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/architecture-decision/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/architecture-decision --- When this skill is invoked: 1. **Determine the next ADR number** by scanning `docs/architecture/` for existing ADRs. 2. **Gather context** by reading related code and existing ADRs. 3. **Guide the user through the decision** by asking clarifying questions if the title alone is not sufficient. 4. **Generate the ADR** following this format: ```markdown # ADR-[NNNN]: [Title] ## Status [Proposed | Accepted | Deprecated | Superseded by ADR-XXXX] ## Date [Date of decision] ## Context ### Problem Statement [What problem are we solving? Why does this decision need to be made now?] ### Constraints - [Technical constraints] - [Timeline constraints] - [Resource constraints] - [Compatibility requirements] ### Requirements - [Must support X] - [Must perform within Y budget] - [Must integrate with Z] ## Decision [The specific technical decision made, described in enough detail for someone to implement it.] ### Architecture Diagram [ASCII diagram or description of the system architecture this creates] ### Key Interfaces [API contracts or interface definitions this decision creates] ## Alternatives Considered ### Alternative 1: [Name] - **Description**: [How this would work] - **Pros**: [Advantages] - **Cons**: [Disadvantages] - **Rejection Reason**: [Why this was not chosen] ### Alternative 2: [Name] - **Description**: [How this would work] - **Pros**: [Advantages] - **Cons**: [Disadvantages] - **Rejection Reason**: [Why this was not chosen] ## Consequences ### Positive - [Good outcomes of this decision] ### Negative - [Trade-offs and costs accepted] ### Risks - [Things that could go wrong] - [Mitigation for each risk] ## Performance Implications - **CPU**: [Expected impact] - **Memory**: [Expected impact] - **Load Time**: [Expected impact] - **Network**: [Expected impact, if applicable] ## Migration Plan [If this changes existing code, how do we get from here to there?] ## Validation Criteria [How will we know this decision was correct? What metrics or tests?] ## Related Decisions - [Links to related ADRs] - [Links to related design documents] ``` 5. **Save the ADR** to `docs/architecture/adr-[NNNN]-[slug].md`. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/donchitos) — claim your Tome and manage your conversions.