# DSS Documentation Guide

**Version 1.0.0** | Last Updated: 2025-12-08 | Status: Production

This guide helps you find the right documentation for your task. Start here, find your scenario, and jump to the right doc.

---

## I'm New to DSS

**Goal**: Understand what DSS is and get started

**Read In This Order:**
1. **PRINCIPLES.md** (5 min) - What DSS believes
2. **README.md** (5 min) - Project overview
3. **QUICK_REFERENCE.md** (5 min) - Key links and commands
4. This guide (you're reading it!)

**Then Choose Your Path:**
- Integrating DSS into your project? → INTEGRATION_GUIDE.md
- Contributing to DSS? → CONTRIBUTION_GUIDE.md
- Setting up for development? → DEVELOPMENT_SETUP.md

---

## I Need to Do Something Specific

### I'm Making a Structural Decision

**Question**: Will this affect how components, tokens, or APIs work?

**Read:**
- **PRINCIPLES.md** (understand the 5 core principles)
- **BEST_PRACTICES.md** (how to apply principles)
- **.knowledge/adrs/** (how similar decisions were made)

**Then:**
- Create an ADR documenting your decision
- Open PR referencing the ADR

---

### I'm Writing Code

**Question**: What's the contract I need to follow?

**Read:**
- **ARCHITECTURE.md** (system structure and design)
- **API_CONTRACTS.md** (endpoint specifications)
- **BEST_PRACTICES.md** (implementation patterns for your principle)

**Then:**
- Follow the patterns in ARCHITECTURE.md
- Respect the contracts in API_CONTRACTS.md
- Link to BEST_PRACTICES.md in your PR if needed

---

### I'm Adding an API Endpoint or MCP Tool

**Read:**
- **API_CONTRACTS.md** (existing endpoints)
- **BEST_PRACTICES.md** § Principle 5 (tool-first architecture)
- **docs/03_reference/MCP_TOOLS_SPEC.md** (how to design tools)

**Then:**
1. Design MCP tool (primary)
2. Implement tool
3. REST endpoint wraps tool
4. Document in API_CONTRACTS.md with new version
5. Create ADR for architectural decision

---

### I'm Integrating DSS into My Project

**Read:**
- **QUICK_REFERENCE.md** (overview)
- **INTEGRATION_GUIDE.md** (step-by-step integration)
- **API_CONTRACTS.md** (endpoints you'll use)
- **docs/03_reference/MCP_TOOLS_SPEC.md** (available tools)

**Questions?**
- "How do I do X?" → Search INTEGRATION_GUIDE.md
- "What endpoints are available?" → See API_CONTRACTS.md
- "How do tokens work?" → See docs/03_reference/TOKEN_SYSTEM.md

---

### I'm Deploying DSS

**Read:**
- **PROJECT_STATUS.md** (current deployment status)
- **DEPLOYMENT_GUIDE.md** (step-by-step deployment)
- **PRODUCTION_READINESS.md** (checklist before deploy)
- **TROUBLESHOOTING.md** (when things go wrong)

**Then:**
- Check PRODUCTION_READINESS.md checklist
- Follow DEPLOYMENT_GUIDE.md steps
- Update PROJECT_STATUS.md after successful deploy

---

### I'm Debugging Something

**Read:**
- **PROJECT_STATUS.md** (known issues section)
- **TROUBLESHOOTING.md** (common problems)
- **ARCHITECTURE.md** (understand component interactions)
- Log files in **logs/** directory

**Still stuck?**
- Check .knowledge/adrs/ for related decisions
- Review ANTI_PATTERNS_AND_LEARNINGS.md for common mistakes
- Ask team in Slack with reference to docs you read

---

### I'm Reviewing a PR

**Checklist:**
- [ ] Does this violate any principles? → See PRINCIPLES.md
- [ ] Did they follow best practices? → See BEST_PRACTICES.md
- [ ] Should this be documented? → Where should it go?
- [ ] Is this an architectural change? → ADR needed?
- [ ] Version numbers updated? → See BEST_PRACTICES.md § Principle 2

**Look for anti-patterns:**
See ANTI_PATTERNS_AND_LEARNINGS.md for common mistakes

---

## Documentation by Tier

### Tier 1: Constitutional Documents (Immutable, Versioned)

These change only through semantic versioning. They define the system.

| Document | Purpose | Read When |
|----------|---------|-----------|
| **PRINCIPLES.md** | Core values (5 principles) | Onboarding, making decisions |
| **API_CONTRACTS.md** | API endpoint specifications | Building integrations, implementing endpoints |
| **ARCHITECTURE.md** | System design, structure | Understanding system, making changes |

**Update Process:**
1. Change file
2. Bump version (MAJOR.MINOR.PATCH)
3. Add changelog entry
4. Open PR
5. Merge and tag (git tag v1.2.0)

---

### Tier 2: Current State Documents (Living, Weekly Updates)

These reflect production reality. Updated at least weekly.

| Document | Purpose | Read When |
|----------|---------|-----------|
| **PROJECT_STATUS.md** | Current deployment, bugs, roadmap | Weekly reviews, planning, status checks |
| **IMPLEMENTATION_SUMMARY.md** | Feature inventory by phase | Understanding what's shipped |
| **README.md** | Project overview, quick links | First time visiting repo |

**Update Process:**
1. Every Friday: Review and update
2. Mark "Last Updated" with current date
3. Update bugs, roadmap, deployment status
4. Commit to main branch

---

### Tier 3: How-To Guides (Reference Documents)

Detailed guidance on specific tasks. Updated as needed.

| Document | Purpose | Read When |
|----------|---------|-----------|
| **QUICK_REFERENCE.md** | Cheat sheet, commands, quick links | Need to find something fast |
| **INTEGRATION_GUIDE.md** | How to integrate DSS into your project | Using DSS in your own project |
| **DEPLOYMENT_GUIDE.md** | Step-by-step deployment process | Deploying to production |
| **MIGRATION_GUIDE.md** | How to upgrade between versions | Upgrading DSS version |
| **MCP_TOOLS_SPEC.md** | Available MCP tools and how to use them | Using MCP tools in automation |
| **CONTRIBUTION_GUIDE.md** | How to contribute to DSS | Contributing code changes |
| **DEVELOPMENT_SETUP.md** | Local development environment | Setting up to develop DSS |
| **PRODUCTION_READINESS.md** | Pre-deployment checklist | Before deploying to production |
| **TROUBLESHOOTING.md** | Common problems and solutions | Debugging issues |

**Update Process:**
1. Update when procedures change
2. Mark "Last Updated" date
3. Review monthly for staleness
4. Archive if superseded by new guide

---

### Tier 4: Knowledge Archive

Historical records, old versions, archived docs.

| Document Type | Purpose | Read When |
|---------|---------|-----------|
| **.knowledge/adrs/** | Architecture Decision Records | Understanding why decisions were made |
| **docs/archive/versions/** | Old API/Architecture versions | Integrating with old systems |
| **docs/archive/** | Historical documents | Research, understanding evolution |

---

## Documentation Structure

```
docs/
├── 01_core/
│   ├── PRINCIPLES.md                    # Tier 1: What we believe
│   ├── BEST_PRACTICES.md               # How to apply principles
│   ├── API_CONTRACTS.md                # Tier 1: API spec
│   ├── ARCHITECTURE.md                 # Tier 1: System design
│   ├── ANTI_PATTERNS_AND_LEARNINGS.md  # What not to do
│   └── DOCUMENTATION_GUIDE.md          # This file
│
├── 02_status/
│   ├── PROJECT_STATUS.md               # Tier 2: Current state
│   ├── IMPLEMENTATION_SUMMARY.md       # Tier 2: Feature inventory
│   └── CHANGELOG.md                    # Version history
│
├── 03_reference/
│   ├── QUICK_REFERENCE.md              # Tier 3: Cheat sheet
│   ├── INTEGRATION_GUIDE.md            # Tier 3: How to integrate
│   ├── DEPLOYMENT_GUIDE.md             # Tier 3: How to deploy
│   ├── MIGRATION_GUIDE.md              # Tier 3: Version upgrades
│   ├── MCP_TOOLS_SPEC.md               # Tier 3: Tool reference
│   ├── TOKEN_SYSTEM.md                 # Tier 3: Token guide
│   ├── PRODUCTION_READINESS.md         # Tier 3: Deploy checklist
│   ├── TROUBLESHOOTING.md              # Tier 3: Common problems
│   ├── CONTRIBUTION_GUIDE.md           # Tier 3: How to contribute
│   └── DEVELOPMENT_SETUP.md            # Tier 3: Dev environment
│
├── archive/
│   ├── versions/
│   │   ├── v1.0.0/
│   │   │   ├── API_CONTRACTS.md
│   │   │   └── ARCHITECTURE.md
│   │   └── v1.1.0/
│   │       └── ...
│   ├── phases/
│   └── 2024/
│
└── README.md                           # Repo overview
```

---

## How to Find Information

### By Task

| I Want To... | Start Here |
|-------------|-----------|
| Understand DSS | PRINCIPLES.md |
| Integrate DSS | INTEGRATION_GUIDE.md |
| Deploy DSS | DEPLOYMENT_GUIDE.md |
| Contribute code | CONTRIBUTION_GUIDE.md |
| Write an endpoint | API_CONTRACTS.md + BEST_PRACTICES.md |
| Use MCP tools | MCP_TOOLS_SPEC.md |
| Debug something | TROUBLESHOOTING.md |
| Check status | PROJECT_STATUS.md |
| Upgrade version | MIGRATION_GUIDE.md |
| Understand a decision | .knowledge/adrs/ |

### By Role

| I'm A... | Read These |
|---------|-----------|
| **New Developer** | PRINCIPLES.md → README.md → QUICK_REFERENCE.md |
| **Product Manager** | PROJECT_STATUS.md → IMPLEMENTATION_SUMMARY.md |
| **DevOps Engineer** | DEPLOYMENT_GUIDE.md → PRODUCTION_READINESS.md |
| **API Consumer** | API_CONTRACTS.md + INTEGRATION_GUIDE.md |
| **System Architect** | ARCHITECTURE.md + ANTI_PATTERNS_AND_LEARNINGS.md |
| **PR Reviewer** | PRINCIPLES.md + BEST_PRACTICES.md |

### By Principle

| Principle | Learn More In |
|-----------|--------------|
| Design is Architectural | PRINCIPLES.md § 1, ARCHITECTURE.md |
| Contracts are Immutable | BEST_PRACTICES.md § Principle 2, API_CONTRACTS.md |
| Single Source of Truth | BEST_PRACTICES.md § Principle 3, ANTI_PATTERNS_AND_LEARNINGS.md |
| Decisions Traceable | BEST_PRACTICES.md § Principle 4, .knowledge/adrs/ |
| Operations as Tools | BEST_PRACTICES.md § Principle 5, MCP_TOOLS_SPEC.md |

---

## Reading Paths

### Path 1: Onboarding (30 minutes)
```
1. PRINCIPLES.md (5 min)
   ↓
2. README.md (5 min)
   ↓
3. QUICK_REFERENCE.md (5 min)
   ↓
4. Start with relevant Tier 3 guide for your task (15 min)
```

### Path 2: Making a Decision (45 minutes)
```
1. PRINCIPLES.md (5 min)
   ↓
2. BEST_PRACTICES.md for relevant principle (15 min)
   ↓
3. .knowledge/adrs/ - similar decisions (15 min)
   ↓
4. ANTI_PATTERNS_AND_LEARNINGS.md (10 min)
   ↓
5. Create ADR for your decision
```

### Path 3: Architectural Change (1 hour)
```
1. ARCHITECTURE.md (20 min)
   ↓
2. BEST_PRACTICES.md (15 min)
   ↓
3. ANTI_PATTERNS_AND_LEARNINGS.md (10 min)
   ↓
4. .knowledge/adrs/ for similar decisions (15 min)
   ↓
5. Design change, create ADR, open PR
```

### Path 4: Integration (2 hours)
```
1. INTEGRATION_GUIDE.md (30 min)
   ↓
2. API_CONTRACTS.md (30 min)
   ↓
3. QUICK_REFERENCE.md (10 min)
   ↓
4. Implement integration, reference docs
   ↓
5. TROUBLESHOOTING.md if issues (20 min)
```

---

## Docs That Reference Each Other

**Single Source of Truth Flow:**
```
PRINCIPLES.md (what we believe)
    ↓
BEST_PRACTICES.md (how to implement)
    ↓
API_CONTRACTS.md, ARCHITECTURE.md (actual specs)
    ↓
IMPLEMENTATION_GUIDE.md, DEPLOYMENT_GUIDE.md (how-to guides)
    ↓
Actual code implementation
```

**Decision Flow:**
```
BEST_PRACTICES.md (decision criteria)
    ↓
.knowledge/adrs/ (record decision)
    ↓
PR links to ADR (traceability)
    ↓
Code implements decision
    ↓
ARCHITECTURE.md or API_CONTRACTS.md (documents result)
```

---

## Keeping Docs Current

### Weekly (Every Friday)
- [ ] Update PROJECT_STATUS.md
  - Mark "Last Updated"
  - Update bugs list
  - Update roadmap
  - Update deployment status

### Monthly (First Friday)
- [ ] Audit all Tier 3 docs for staleness
  - Any docs older than 30 days?
  - Still accurate?
  - Update or archive?

### Per Release
- [ ] Update API_CONTRACTS.md version
- [ ] Add CHANGELOG entry
- [ ] Update MIGRATION_GUIDE.md if breaking changes
- [ ] Update IMPLEMENTATION_SUMMARY.md with new features
- [ ] Create tag (git tag vX.Y.Z)

### When Making Major Changes
- [ ] Create or update ADR
- [ ] Update relevant Tier 1 docs
- [ ] Link PR to ADR
- [ ] Update related Tier 3 guides

---

## FAQ: Finding Documentation

**Q: Where are API endpoints documented?**
A: API_CONTRACTS.md (Tier 1, immutable)

**Q: Why did we choose this architecture?**
A: Check ARCHITECTURE.md or .knowledge/adrs/ (decision records)

**Q: What's currently deployed?**
A: PROJECT_STATUS.md (Tier 2, updated weekly)

**Q: How do I integrate DSS?**
A: INTEGRATION_GUIDE.md (Tier 3, reference guide)

**Q: How do I deploy changes?**
A: DEPLOYMENT_GUIDE.md (Tier 3, step-by-step)

**Q: What's the status of feature X?**
A: IMPLEMENTATION_SUMMARY.md or PROJECT_STATUS.md

**Q: What changed between versions?**
A: CHANGELOG.md or MIGRATION_GUIDE.md

**Q: Is this documented?**
A: Yes! (probably) → Use this guide to find it

---

**Last Updated**: 2025-12-08
**Version**: 1.0.0 (new navigation guide)
**Status**: PRODUCTION