Adr Capture From Tech Spec.instructions

---
description: "Use when writing or reviewing technical specifications to capture major architecture decisions as ADRs with traceable context and rationale."
name: "ADR Capture from Tech Specs"
applyTo: "**/*tech-spec*.md|docs/adr/**/*.md"
---

# ADR Capture from Technical Specs

## Purpose

Capture high-impact technical decisions from each tech spec as Architecture Decision Records (ADRs) so decisions remain traceable and maintainable.

## When an ADR Is Required

Create or update an ADR when a tech spec includes decisions that affect:

- Architecture boundaries or service decomposition
- Data model/storage strategy
- API/event contracts or integration patterns
- Security, privacy, compliance, or reliability posture
- Significant performance or cost tradeoffs
- Migration and compatibility strategy

## ADR Location and Naming

Use this location priority:

1. Existing `docs/adr/`
2. Existing `docs/architecture/adr/`
3. Existing `tasks/adr/`
4. If none exist, create `docs/adr/`

Naming convention:

- `ADR-YYYY-MM-DD-<decision-slug>.md`

## Required ADR Content

Each ADR should include:

- ADR ID and title
- Status (`Proposed`, `Accepted`, `Superseded`)
- Date
- Source tech spec path
- Related PRD requirement references (for example, `FR-2`, `NFR-1`)
- Context
- Decision
- Alternatives considered
- Consequences (positive and negative)
- Rollout or migration implications

## Tech Spec to ADR Traceability Rules

- Every major technical decision in a tech spec must reference an ADR ID.
- If a decision does not warrant an ADR, include one explicit sentence justifying why.
- Add a short decision log section in the tech spec:
  - `Decision: <summary> -> ADR: <ID or path>`

## ADR Quality Bar

An ADR is complete only if:

- The problem context is clear and non-ambiguous.
- The chosen decision is specific and testable in practice.
- At least one alternative and tradeoff is documented.
- Impacts on operations, migration, or compatibility are stated.
- PRD requirement linkage is explicit.

## Update Rules

- If a new decision replaces an existing ADR, mark the old ADR as `Superseded` and reference the replacement.
- Do not silently overwrite historical rationale.