---
id: 001
title: Use Markdown ADRs for Recording DSS Architecture Decisions
date: 2025-12-08
author(s): Claude Code + Gemini 3 Pro
status: Accepted
principles: [Knowledge Persistence, Single Source of Truth, Foundational Contracts]
related:
  - doc: /docs/01_core/PRINCIPLES.md
  - doc: /.knowledge/adrs/000-template.md
  - ticket: DSS-Principles-Pilot
---

## Context

The DSS project has defined 7 core principles that guide all architectural and governance decisions. However, principles are only as valuable as their adoption and application in real work. Without a lightweight, practical mechanism to capture why decisions were made, alternatives were considered, and consequences were evaluated, the principles become aspirational rather than operational.

Additionally, as the DSS evolves, decision rationale is often lost or scattered across commit messages, Slack discussions, or in developers' heads. This makes it difficult to:
- Understand why a past decision was made
- Know which decisions are still valid vs. need reconsideration
- Onboard new team members who need to understand the system's evolution
- Identify when to revisit or supersede past decisions

We needed a simple, version-control-friendly mechanism to record architectural decisions that would be low-friction (encouraging adoption) while remaining structured (enabling automated tooling later).

### Alternatives Considered

1. **JSON-only format** (.knowledge/decisions/adr-001.json)
   - Pros: Machine-readable from the start
   - Cons: Developers have to write JSON, which is tedious and error-prone; harder to edit in typical workflows
   - Rejected: Too much friction; would be skipped in favor of verbal discussions

2. **Database-backed ADR system** (MongoDB, PostgreSQL records)
   - Pros: Queryable, structured, supports automated workflows
   - Cons: Adds external dependencies; cannot be version-controlled; requires setup
   - Rejected: Over-engineered for Year 1; adds maintenance burden

3. **Markdown with YAML frontmatter** (this approach)
   - Pros: Humans love Markdown; YAML frontmatter is machine-parseable; works with git; requires zero setup
   - Cons: Requires manual curation (no automated queries yet); files need to be discovered manually
   - Selected: Best balance of ease-of-use and future-proofing

## Decision

We will record Architecture Decision Records (ADRs) as **Markdown files with YAML frontmatter** in the `.knowledge/adrs/` directory.

### Format

```yaml
---
id: NNN
title: Short descriptive title
date: YYYY-MM-DD
author(s): Name(s)
status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
principles: [Relevant principles from PRINCIPLES.md]
related:
  - doc: Documentation link
  - adr: Other ADR link
  - ticket: Issue/PR link
---

# Markdown content here

## Context
## Decision
## Consequences
## Related Principles
```

### Process

1. **Create ADR during decision**: When a significant architectural decision is made, a team member creates a Markdown file following the template
2. **Link from PRs**: PRs that implement a decision reference the ADR (`Implements ADR-NNN`)
3. **Review in Code Review**: Reviewers validate that decision and consequences are clearly stated
4. **Status Lifecycle**: ADRs start as `Proposed`, become `Accepted` after consensus, and can be marked `Deprecated` or `Superseded` as the system evolves
5. **No Deletion**: ADRs are never deleted; superseded ADRs remain in place with status marked

### Scope

ADRs are for **significant architectural decisions** that:
- Impact multiple components or systems
- Involve trade-offs or alternatives
- Will be referenced in future decisions
- Need rationale captured for future developers

**Not** for every technical decision (e.g., "use this variable name" or "fix this bug").

## Consequences

**Positive:**
- **Knowledge Capture**: Rationale is captured while fresh, not reconstructed later from git history
- **Principle Alignment**: Forces explicit connection to DSS principles; strengthens principle adoption
- **Onboarding**: New team members understand "why" decisions were made, not just "what"
- **Traceability**: Decision → Implementation (PR) → Code → Testing forms a clear chain
- **Future Guidance**: When reconsidering a decision, the old ADR shows what was tried and why
- **Git-Friendly**: ADRs are version-controlled, reviewable in PRs, queryable via grep
- **Low Friction**: Markdown is familiar; YAML is structured; zero infrastructure needed
- **Extensible**: Can add structured queries, automation, or dashboards later without changing format

**Negative:**
- **Manual Curation**: Someone must remember to create ADRs; no automatic enforcement (yet)
- **File Discovery**: ADRs must be discovered manually or via grep (no centralized index yet)
- **Status Drift**: Developers might forget to mark ADRs as `Superseded` when a decision changes
- **Incomplete Coverage**: Not all past decisions will have ADRs (only going forward)

## Related Principles

- **Knowledge Persistence**: ADRs are the executable capture of architectural knowledge; they live in the graph and can be queried/analyzed
- **Single Source of Truth**: Decision rationale is recorded once in the ADR; referenced (not duplicated) from code/docs/PRs
- **Foundational Contracts**: ADRs that document API or architecture changes become part of the immutable Tier 1 contract
- **Current State Transparency**: Status field (Accepted, Deprecated, Superseded) keeps the decision record truthful and current
- **MCP First**: Future tooling (MCP tools) can query the ADR repository and suggest decisions based on project changes

## Next Steps

1. **Pilot on dss_sync_figma** (Week 1-4 of December 2025)
   - Team will create 2-3 ADRs for foundational decisions
   - Gather feedback on process and template
   - Refine based on real-world use

2. **Retrospective** (Week 4)
   - Did ADRs help clarify decisions?
   - Was the process too heavy or too light?
   - What needs to change for broader adoption?

3. **Broader Rollout** (Month 2+)
   - Share learnings with broader team
   - Encourage ADRs on new features
   - Build tooling (queries, dashboards) based on feedback

---

**Status**: Ready for pilot implementation
**Approved by**: DSS Core Principles Initiative