// Document significant architectural decisions using the ADR (Architecture Decision Record) format. Use during research phases when choosing between approaches, when introducing new dependencies or patterns, or when the user asks to document a technical decision.
| name | adr |
| description | Document significant architectural decisions using the ADR (Architecture Decision Record) format. Use during research phases when choosing between approaches, when introducing new dependencies or patterns, or when the user asks to document a technical decision. |
Document significant architectural decisions so institutional knowledge persists across conversations and team members. ADRs capture the why, not just the what.
ADRs 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:
Execute a structured code review protocol that inspects code quality against the full rule set. Use when auditing code written by yourself or another agent, during code audit workflows, or when the user asks for a code review. Produces a findings document with severity tags.
Structured research protocol for investigating technologies, patterns, and APIs before implementation. Use when exploring unfamiliar technologies, evaluating library options, or documenting technical findings. Covers multi-tool search strategy, research log conventions, and training data fallback honesty protocol.
Apply WCAG accessibility standards when building UI components, forms, interactive elements, or any user-facing interface. Covers semantic HTML, ARIA attributes, keyboard navigation, color contrast, and screen reader support.
Apply REST/HTTP API design conventions when implementing endpoints, handlers, middleware, request validation, or response formatting. Covers resource naming, status codes, error formats, versioning, and pagination.
Apply Kubernetes deployment and GitOps patterns when configuring container orchestration, deployment strategies (rolling, blue-green, canary), ArgoCD/Flux manifests, or Kubernetes secrets management. Supplement to ci-cd-principles.
Apply CI/CD pipeline design patterns when configuring build pipelines, deployment processes, release strategies, Dockerfiles, or GitHub Actions workflows. Covers pipeline stages, artifact management, environment promotion, and rollback strategies.