dss/.knowledge/adrs/ADR_KNOWLEDGE_MAP.md

ADR Knowledge Map

Visual and textual guide to how DSS architecture connects principles → decisions → implementation

Use this to understand the knowledge graph and trace decisions back to foundational principles.

---

Knowledge Graph Structure

┌─────────────────────────────────────────────────────────────────┐
│                    PRINCIPLES.md (Tier 1)                       │
│  7 governance principles that guide all architectural decisions │
└────────────────────┬────────────────────────────────────────────┘
                     │
                     │ "Linked via ADR principles: field"
                     ↓
┌─────────────────────────────────────────────────────────────────┐
│              .knowledge/adrs/ (Architecture Decisions)           │
│                                                                 │
│  ADR-001: Use Markdown ADRs for DSS Architecture Decisions     │
│           ├─ Principles: [Knowledge Persistence, SSoT]         │
│           ├─ Status: Accepted                                  │
│           └─ Implementation: This ADR system itself             │
│                                                                 │
│  ADR-002+: [Future decisions captured here]                    │
│           ├─ Each linked to 1-3 principles                     │
│           ├─ Traces to specific PRs via PR template            │
│           └─ Becomes searchable knowledge graph                │
└────────┬────────────────────────────────────────────────────────┘
         │
         │ "Linked via PR template: Implements ADR-NNN"
         ↓
┌─────────────────────────────────────────────────────────────────┐
│              Pull Requests & Code Review                        │
│                                                                 │
│  PR #123: Implement caching strategy (ADR-002)                 │
│           └─ "Implements ADR-002"                              │
│           └─ "Supports [Single Source of Truth]"               │
│                                                                 │
│  PR #124: Add API versioning (ADR-003)                         │
│           └─ "Implements ADR-003"                              │
│           └─ "Supports [Foundational Contracts]"               │
└────────┬────────────────────────────────────────────────────────┘
         │
         │ "Code implements the decision"
         ↓
┌─────────────────────────────────────────────────────────────────┐
│                  Code & Implementation                          │
│                                                                 │
│  src/cache/sqlite.ts — Implements caching from ADR-002         │
│  src/api/v2/... — Implements versioning from ADR-003           │
│  server/routes/mcp.js — All MCP tools expose operations        │
│                                                                 │
│  Everything traceable back to: Which principle? Which decision? │
└─────────────────────────────────────────────────────────────────┘

---

How to Trace a Decision

Starting from a principle:

1. Which ADRs link to this principle? (Search: grep -r "principles:" .knowledge/adrs/)
2. Which PRs implement those ADRs? (Search PR descriptions for "Implements ADR-NNN")
3. Which code files are changed in those PRs? (Check the PR diff)
4. Result: You have the full chain from principle to code

Example trace:

Principle: "Single Source of Truth"
  ↓
ADR-002: "Use SQLite for local caching" (links to SSoT)
  ↓
PR #98: "Implement caching layer" (Implements ADR-002)
  ↓
Files: src/cache/sqlite.ts, src/cache/manager.ts, tests/cache.test.ts

Starting from code:

1. What PR changed this file? (Git log or GitHub blame)
2. What ADR does the PR reference? (Check PR description)
3. What principles motivated this ADR? (Check ADR frontmatter)
4. Result: You understand the "why" behind the code

---

Current State (Pilot Phase)

Established ADRs

ID	Title	Principles	Status	Implementation
001	Use Markdown ADRs for DSS Architecture Decisions	Knowledge Persistence, Single Source of Truth	Accepted	This system

In Progress / To Be Created

During the dss_sync_figma pilot (Weeks 2-4 of December 2025):

• ADR-002: Figma API authentication strategy (Phase 5A decision)
• ADR-003: Caching strategy for Figma data
• ADR-004: Async library choice for Python operations
• ADR-005+: Additional dss_sync_figma decisions

Each will:

• Be created by the pilot team as significant decisions are made
• Link to 1-3 DSS principles
• Be referenced in PRs via PR template
• Become part of the queryable knowledge graph

---

Querying the Knowledge Graph

Find ADRs by Principle

# Find all ADRs mentioning "Single Source of Truth"
grep -r "Single Source of Truth" .knowledge/adrs/

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

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

Find Code by ADR

# Find PRs implementing ADR-002
git log --all --grep="ADR-002" --oneline

# Find code files changed in ADR-002's PRs
git log --all --grep="ADR-002" --name-only

Find Principles in Code

# Find comments referencing a principle
grep -r "Single Source of Truth" src/

# Find TODOs about principle compliance
grep -r "TODO.*SSoT" .

---

Example: Complete Trace

Scenario: "Why do we cache Figma data this way?"

Step 1: Find the ADR

$ grep -r "cache" .knowledge/adrs/ --ignore-case
.knowledge/adrs/ADR-002-figma-caching-strategy.md
  → ADR-002 explains: Use in-memory cache with SQLite persistence

Step 2: Read the ADR

---
id: 002
title: Figma Data Caching Strategy
principles: [Single Source of Truth, Knowledge Persistence]
---

## Decision
Cache Figma data in memory with periodic SQLite persistence.
Prevents API rate limiting and supports offline mode.

## Consequences
- Positive: Fast queries, resilience to API outages
- Negative: Stale data window (up to 5 minutes between syncs)

Step 3: Find the implementation PR

$ git log --all --grep="ADR-002"
Commit: "Implement Figma caching (Implements ADR-002)"

Step 4: Find the code

$ git show <commit> --name-only
src/services/figma-cache.ts
src/models/figma-cache.model.ts
tests/figma-cache.test.ts

Step 5: Read the code

// src/services/figma-cache.ts
// Implements: ADR-002 Figma Data Caching Strategy
// Principles: Single Source of Truth (one cache per resource),
//             Knowledge Persistence (decisions captured in ADR-002)

Result: You understand not just how (the code) but why (the principle), what alternatives were considered (the ADR), and who made the decision (the PR).

---

Building Your Own Traces

For Decision-Makers

When you face a decision:

1. Check if a similar ADR already exists
2. If yes: read it; understand the tradeoff; apply same pattern if appropriate
3. If no: create a new ADR linking to relevant principles
4. Record your decision while fresh, before implementation

For Code Reviewers

When reviewing a PR:

1. Check the PR template's "DSS Principles Check" section
2. Verify the ADR referenced actually exists and is relevant
3. Verify principle alignment claims are justified
4. Ask: "Does this PR implement a decision that should have an ADR?"

For New Team Members

To onboard:

1. Read /docs/01_core/PRINCIPLES.md (the constitution)
2. Read .knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md (explains the system)
3. Grep the ADRs for decisions related to your area
4. Follow traces from ADRs → PRs → code to understand the "why"

---

Knowledge Graph Evolution

Year 1 (Current):

• Manual ADR creation and discovery
• Grep-based queries
• Cross-links in Markdown

Year 2 (Planned):

• Automated ADR discovery dashboard
• Principle adoption metrics
• Visual knowledge graph with node queries

Year 3 (Vision):

• ADRs generate code contracts (TypeScript types from architecture)
• ADRs auto-validate code against recorded constraints
• ML-based decision suggestions ("You've made similar decisions before")

---

Related Documents

• Principles: /docs/01_core/PRINCIPLES.md
• Core Reference: .knowledge/adrs/PRINCIPLES_CORE_REFERENCE.md
• ADR Template: .knowledge/adrs/000-template.md
• ADR Guide: .knowledge/adrs/README.md
• Example ADR: .knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md

---

Quick Links for Pilot Phase

During dss_sync_figma pilot (Weeks 1-4):

• Kickoff materials (archived): .knowledge/adrs/archived/operational/KICKOFF_AGENDA.md
• PR template update (archived): .knowledge/adrs/archived/operational/PR_TEMPLATE_UPDATE.md
• Facilitator guide (archived): .knowledge/adrs/archived/operational/FACILITATOR_GUIDE.md
• Slack announcement (archived): .knowledge/adrs/archived/operational/SLACK_ANNOUNCEMENT_TEMPLATE.md
• Execution checklist (archived): .knowledge/adrs/archived/operational/EXECUTION_CHECKLIST.md

All archived files are still available for reference; they're just not in the main working directory.

---

Last Updated: 2025-12-08
Purpose: Navigate the DSS knowledge graph
Audience: All DSS team members, Zen chat context