// Architecture Decision Record skill for documenting significant architectural decisions with context, options, and consequences. Use during the Research phase when choosing between approaches, or whenever the user asks to document an architectural decision.
| name | adr |
| description | Architecture Decision Record skill for documenting significant architectural decisions with context, options, and consequences. Use during the Research phase when choosing between approaches, or whenever the user asks to document an architectural decision. |
Document significant architectural decisions so institutional knowledge persists across conversations and team members. ADRs capture the why, not just the what.
phase-research.md) when a significant architecture decision is identifiedADRs are stored in docs/decisions/ as numbered files:
docs/decisions/
├── 0001-use-postgresql-for-storage.md
├── 0002-adopt-feature-based-structure.md
├── 0003-use-testcontainers-for-integration.md
└── NNNN-short-title.md
Create the ADR file at docs/decisions/NNNN-short-title.md:
# NNNN. Short Title
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by NNNN
## Context
What is the issue that we're seeing that is motivating this decision?
Include technical constraints, business requirements, and relevant context.
## Options Considered
### Option A: {name}
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High
### Option B: {name}
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High
### Option C: {name} (if applicable)
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High
## Decision
We chose **Option X** because...
## Consequences
### Positive
- What becomes easier or possible as a result
### Negative
- What becomes harder as a result
- Technical debt introduced (if any)
### Risks
- What could go wrong with this decision
- Mitigation strategies
## Related
- Links to relevant rules, previous ADRs, or external resources
docs/decisions/ for the next numberProposed → Accepted (after approval) → optionally Deprecated or SupersededSuperseded by NNNN and create a new ADRADRs should reference applicable rules:
Token-efficient communication protocol. Activate ONLY when: (1) user explicitly requests it (e.g., "use omni", "be concise", "compress output"), (2) dispatched as a sub-agent in /workflow-team pipelines where token budget matters, or (3) agent-to-agent communication via /omni headless modifier. Never activate by default in normal conversations — users expect natural language responses unless they opt in. Compresses prose form while preserving 100% technical accuracy. Code blocks, tool calls, file paths, and data are NEVER compressed.
Structured code review protocol for inspecting code quality against the full rule set. Use when auditing code written by yourself or another agent, during the /audit workflow, or when the user asks for a code review.
Pre-flight checklist and post-implementation self-review protocol. Use before generating any code (pre-flight) and after writing code but before verification (self-review) to catch issues early.
Comprehensive protocol for validating root causes of software issues. Use when you need to systematically debug a complex bug, flaky test, or unknown system behavior by forming hypotheses and validating them with specific tasks.
Profile-driven performance optimization protocol. Use when profiling data (CPU, heap, trace) is available or when the user requests performance analysis. Covers methodology, pattern catalog, safety invariants, and when-to-stop heuristics. Language-specific tooling is in languages/*.md.
OpenAPI 3.1 specification writing, request/response examples, error documentation, versioning, and interactive API portal patterns.