docs/DOCS_TAXONOMY.md

Documentation Taxonomy

Where to put new documentation. Inspired by Diataxis but adapted for agentic engineering where both humans and AI agents consume docs.

Decision Tree

"I need to write something down."
    │
    ├── Does it tell someone HOW TO do a specific task?
    │   └── YES → docs/guides/                    [how-to]
    │
    ├── Does it describe WHAT something IS (APIs, interfaces, facts)?
    │   └── YES → docs/references/                [reference]
    │         or → docs/ARCHITECTURE.md            [reference]
    │         or → docs/delivery-specs/            [reference]
    │
    ├── Does it explain WHY a decision was made?
    │   └── YES → docs/design-docs/               [explanation]
    │         or → vision/                         [explanation]
    │
    ├── Does it validate WHETHER we should build something?
    │   └── YES → docs/discovery/                  [explanation]
    │
    ├── Is it a durable pattern extracted from work?
    │   └── YES → docs/learnings/<category>.md     [reference]
    │
    ├── Is it an idea, investigation, or scratchpad?
    │   └── YES → docs/exploration/                [exploration]
    │
    └── Is it tracking active work progress?
        └── YES → docs/exec-plans/                 [how-to]

Directory Purpose Map

Directory	Diataxis Type	Audience	Created By	Mutability
docs/guides/	How-to	Humans + Agents	Manual or extracted	Stable
docs/design-docs/	Explanation	Humans + Agents	design-doc skill	Append-only (decisions are permanent)
docs/discovery/	Explanation	Humans (agents read)	discovery skill	Per-feature, stable once validated
docs/delivery-specs/	Reference	Agents + Humans	delivery-spec skill	Stable once approved
docs/references/	Reference	Agents	Manual or generated	Updated as needed
docs/learnings/	Reference	Agents + Humans	compound-engineer	Append-only (budgeted)
docs/exploration/	Exploration	Humans only	Manual	Ephemeral -- graduate or archive
docs/exec-plans/	How-to	Humans (agents read)	Manual	Active then archived
vision/	Explanation	Humans + Agents	strategy skill or manual	Rare changes
specs/	Reference	Agents	Autocode skills	Per-feature lifecycle

Self-Organization Rules

1. Start minimal. Don't create directories until you have content for them. Skills create directories on-demand.
2. Graduate content. Exploration docs that prove durable should move to the appropriate permanent location (learnings, guides, references).
3. One purpose per doc. If a document is doing two things (e.g., explaining WHY and telling HOW), split it.
4. Agents navigate by maps. Keep AGENTS.md as a pure index. Keep docs/README.md as the docs index. Don't inline content in indexes.
5. Enforce mechanically. Use DOCS_CONTRACT.json and opencode-ctx docs validate to prevent drift. Narrative instructions degrade with context length; lints apply everywhere.

Sources

• Diataxis -- Four-type documentation framework (Daniele Procida)
• Cynefin -- Complex vs. ordered domains inform when to prescribe vs. let emerge (Dave Snowden)
• OpenAI Harness Engineering -- "Give Codex a map, not a 1,000-page instruction manual"