portfolio/agentlab/decisions/ADR-002-documentation-structure.md

ADR-002: Documentation Structure and Naming Conventions

Status: Proposed — design agreed, migration pending dedicated session.

Problem

The current docs/ directory is a flat catch-all. Files with no clear taxonomy, inconsistent naming, and no indication of what kind of document they are or what project they belong to. Key symptoms:

• HANDOFF.md — whose handoff? Only meaningful inside vps/
• Architecture docs, dictation rollout docs, and agent reference docs all live in the same flat directory with no relationship visible from the name alone
• Dated scratch files mixed with authoritative reference documents
• No way to know, from a filename alone, what kind of document it is or what project it belongs to

This causes agents and operators to either over-read (read everything to find the right document) or under-read (miss relevant documents entirely).

Decision

1. Adopt Diátaxis as the documentation framework

Diátaxis defines four document types, each serving a distinct need:

Type	Purpose	Reader need
Reference	Look up a fact	"What is the current state?"
How-to	Follow a procedure	"How do I do X?"
Explanation	Understand why	"Why is it this way?"
State	Track live work	"What is in progress?"

State is not a Diátaxis type but is operationally distinct in a living infrastructure repo — it changes frequently and must be authoritative.

2. Project-scoped structure

Every significant system is a project with its own subdirectory. Project state files are named with their project prefix so they are self-describing without directory context.

projects/
├── vps/
│   ├── VPS-CURRENT-STATE.md
│   ├── VPS-HANDOFF.md
│   └── VPS-PLAN.md
├── agentlab/
│   ├── AGENTLAB-CURRENT-STATE.md
│   └── AGENTLAB-HANDOFF.md

3. docs/ structure by Diátaxis type

docs/
├── reference/       # Look-up: current facts, inventories, specs
├── how-to/          # Procedures: step-by-step, operator runbooks
├── explanation/     # Why: architecture rationale, design context
├── decisions/       # ADRs: point-in-time architecture decisions
├── open-loops.md    # Active cross-project work tracking
├── deploys/         # Timestamped deploy logs
└── archive/         # Historical records

4. Naming conventions

Rule	Example
Project state files are prefixed with project name	VPS-HANDOFF.md
All filenames are lowercase-hyphenated	agent-model-reference.md
ADRs are numbered and describe the decision	ADR-002-documentation-structure.md
Service docs match the service name exactly	prometheus.md, loki.md
Avoid dates in non-archive filenames	2026-03-25-plan.md

Migration rules

1. Do not migrate files piecemeal — partial migration breaks the required reading chain
2. Update all cross-references atomically in the same commit as file moves
3. Run a grep for every moved filename before committing to catch stale references
4. Migration is a dedicated session — do not start during active build work

Why not a flat structure

A flat docs/ directory forces readers (human and agent) to scan all files to find the relevant document. Naming cannot communicate type, scope, or authority. The Diátaxis structure makes type and scope visible from the path alone: docs/how-to/whisperkit-dictation-rollout.md tells you exactly what it is before you open it.