dss/.knowledge/adrs

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.

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

---
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:

# 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:

## 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)