# 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

```bash
# 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

```bash
# 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

```bash
# 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**
```bash
$ 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**
```markdown
---
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**
```bash
$ git log --all --grep="ADR-002"
Commit: "Implement Figma caching (Implements ADR-002)"
```

**Step 4: Find the code**
```bash
$ 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**
```typescript
// 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