dss/.knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md

id, title, date, author(s), status, principles, related

id	title	date	author(s)	status	principles	related
001	Use Markdown ADRs for Recording DSS Architecture Decisions	2025-12-08	Claude Code + Gemini 3 Pro	Accepted	Knowledge Persistence Single Source of Truth Foundational Contracts	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

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