documentation-placement
Installation
SKILL.md
Documentation Placement
A discipline for arranging documentation so a reader can find a fact exactly once. The core rule is one home per fact: each fact lives in the tier whose job it is, and everywhere else it is a link. This skill tells you where a fact belongs, how deep to go, and how to classify a document. It applies to any repo with documentation.
The defining constraint: the authoring order is locate → set detail → classify → relocate descendant detail → link. You decide where a fact lives before you write it, not after.
The tier taxonomy: one home per fact
Documents form a hierarchy of tiers, each with a job. Place a fact in the tier whose job it is; elsewhere, link there.
| Tier | Job | Does NOT belong there |
|---|---|---|
| Standing orders (top-level agent instructions) | Rules an agent needs in context every session, one to three lines each, linking its home | Stories, worked examples, anything restated from a linked home |
| Architecture map | Ordered map of the system — composition, core pieces, flows, extension points | Type definitions, per-module detail, decision rationale |
| Reference (one page per module/subsystem) | Type definitions, semantics, generated API | Behavior narration |
| Decision records | Active decisions — the why, what was given up, required verification | Migration plans, spec-speak once the decision has shipped |
| How-tos / cookbook | Step-by-step guides with numbered verify steps | Design rationale |
| Package/module README | The per-module consumer contract: config, semantics, limitations, extension points | JSDoc restatement, generated-catalog restatement |
| Generated reference | Exhaustive sources regenerated from source | Hand edits — change the generator instead |