# Documentation Taxonomy

Where to put new documentation. Inspired by [Diataxis](https://diataxis.fr/) 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](https://diataxis.fr/) -- Four-type documentation framework (Daniele Procida)
- [Cynefin](https://en.wikipedia.org/wiki/Cynefin_framework) -- Complex vs. ordered domains inform when to prescribe vs. let emerge (Dave Snowden)
- [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/) -- "Give Codex a map, not a 1,000-page instruction manual"