# Architecture Decision Records (ADRs)

This directory contains Architecture Decision Records for the DSS project. ADRs capture the rationale behind significant architectural decisions, alternatives considered, and consequences of choices we make.

## Why ADRs?

ADRs serve the principles of **Knowledge Persistence** and **Single Source of Truth** from [PRINCIPLES.md](/docs/01_core/PRINCIPLES.md).

They answer the question: **"Why did we decide this way?"**

## How to Create an ADR

1. Copy `000-template.md` to `NNN-short-title.md` (e.g., `002-use-sqlite-for-local-cache.md`)
2. Fill out all sections
3. Reference relevant DSS principles
4. Link from PRs that implement the decision
5. Commit to git; it becomes part of the decision history

## Format

```yaml
---
id: NNN                           # Sequential number
title: Clear, descriptive title
date: YYYY-MM-DD                 # Decision date
author(s): Your Name             # Who decided this?
status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
principles: [Principle1, Principle2]  # Which DSS principles does this support?
related:
  - doc: Link to documentation
  - adr: Link to related ADRs
  - ticket: Link to issue/PR
---
```

## Status Lifecycle

- **Proposed**: Decision is being considered; not yet finalized
- **Accepted**: Team has consensus; decision is in effect
- **Deprecated**: We no longer recommend this approach but it may still be in use
- **Superseded by ADR-XXX**: This decision was replaced; see referenced ADR for current approach

**Important**: Never delete an ADR. Mark it as Superseded and leave it in place for historical reference.

## Examples

Current ADRs:
- `001-use-markdown-adrs-for-dss-architecture-decisions.md` - How we record decisions

## Tips for Good ADRs

✅ **Do**:
- Write while the decision is fresh
- Include context on why this decision matters
- Explain alternatives and why they were rejected
- Be concise but complete
- Link to related decisions and principles

❌ **Don't**:
- Write implementation details (that belongs in code comments/documentation)
- Make decisions in the ADR; use ADRs to record *already made* decisions
- Use ADRs for minor technical choices (use PRs/code comments instead)
- Delete or significantly rewrite an ADR after acceptance (mark as Superseded instead)

## Querying ADRs

Find ADRs related to a concept:
```bash
# Find all ADRs mentioning "Figma"
grep -r "Figma" .knowledge/adrs/

# Find all deprecated ADRs
grep -r "status: Deprecated" .knowledge/adrs/

# Find ADRs related to MCP principle
grep -r "MCP First" .knowledge/adrs/
```

## Integration with Code Review

When opening a PR that implements a significant decision:

```markdown
## DSS Principles Check
- **ADR Link**: Implements decision in ADR-NNN
- **Principle Alignment**: This work supports [Principle Name] by...
```

See the [updated PR template](#) for details.

## Future Tooling

Year 1: Manual ADR creation and discovery (this system)
Year 2: Automated queries and dashboards for ADR insights
Year 3: ADRs generate code contracts and test suites

---

**Last Updated**: 2025-12-08
**Pilot Project**: `dss_sync_figma`
**Next Review**: Week 4 of December 2025 (retrospective)