Documentation

Iron Law

EVERY DOC IS SMALL, TAGGED, AND LINKED -- ONE CONCEPT PER FILE
YOU MUST keep every doc file under 800 tokens, include YAML frontmatter on every doc, and add a Related section at the bottom of every doc except `docs/DOD.md` (see the defining-done skill's canon template). No exceptions.

Violating the letter of this rule is violating the spirit of this rule.

Announce at start: "I am using the documentation skill to [write/update/review] [description]."

---

BEFORE PROCEEDING

Before writing any documentation:

1. Identify the domain and subdomain from the taxonomy in references/DOCUMENTATION_EXAMPLES.md
2. Confirm the file belongs in docs/<domain>/<subdomain>/ or docs/<domain>/<subdomain>/<subdomain2>/ (not a flat root file unless it's a cross-cutting standard)
3. Confirm no existing file already covers this concept: run grep -rF -- "<concept-title>" docs/ -- if a match exists, link to it instead of duplicating

[+] All 3 met -> proceed to write [-] Any unmet -> resolve before writing a single line

---

Step 1: Determine Documentation Type

Type	Location
API/class reference	Header file comments (<=5 lines inline; longer -> docs/)
Domain guides	docs/<domain>/<subdomain>/ or docs/<domain>/<subdomain>/<subdomain2>/ (third level when a subdomain needs splitting) -- one concept per file, <=800 tokens
Cross-cutting standards	docs/UPPERCASE.md
Agent skills	.claude/skills/<name>/SKILL.md
Skill reference content	.claude/skills/<name>/references/*.md
Agent onboarding	AGENTS.md -- summarize only

---

Step 2: Apply Frontmatter and Linking Rules

Every docs/ file MUST begin with YAML frontmatter -- schema in references/DOCUMENTATION_EXAMPLES.md.

Required fields: title, description, domain, subdomain, tags, related.

• description MUST be one concrete sentence that answers: what exactly does this file cover?
• tags MUST include domain and subdomain as the first two entries
• related uses relative paths from the file's own directory

Every doc file MUST end with a ## Related section with at least one annotated link. Scoped exception: docs/DOD.md, the Definition of Done canon index, ends at its Stamp: line with nothing after it -- the defining-done skill's canon template states the rationale and owns the exception; detail files under docs/dod/ keep the requirement.

Document Mode vs Thread Mode

All files in docs/ MUST be Document Mode -- readable independently, with no assumed conversational context. Thread Mode writing (responses that only make sense inside a conversation) belongs in chat, not in documentation. If a paragraph requires "as discussed above" or "in the previous message," it is Thread Mode. Rewrite it or cut it.

Formatting Standards

1. Use markdown for all documentation
2. Include a Table of Contents for documents with 3+ sections
3. Use code blocks with language tags for all code examples
4. Use relative links -- verify they resolve from the file's directory
5. Keep file <=800 tokens; split at concept boundaries if longer
6. Use ASCII-only text (no Unicode characters) -- replace non-ASCII arrows, em/en-dashes, math operators, and box-drawing chars with ASCII equivalents (-> -- - <= >= != | - +)

---

Step 3: Review Checklist

Before presenting documentation, verify:

1. YAML frontmatter is present with all required fields
2. File is in the correct domain/subdomain directory
3. File is <=800 tokens
4. All relative links resolve correctly from the file's directory
5. Code examples have language tags
6. No content duplicated from another file -- linked instead
7. ## Related section is present at the bottom (sole exception: docs/DOD.md)
8. Documentation matches current code state
9. All acronyms spelled out on first use -- no unexpanded project-specific or technical abbreviations (see Acronym Rule in the writing-skills skill)
10. Relevant docs/INDEX.md and docs/<domain>/INDEX.md updated to include this file

[+] All pass -> documentation is ready to present [-] Any unmet -> resolve all failing items before presenting

---

Rationalization Prevention

Excuse	Reality
"I'll add frontmatter later"	Without frontmatter the doc is invisible to search.
"One big file is easier to navigate"	Large files produce poor retrieval chunks. Split at concepts.
"The related section is optional"	Without it, the retrieval graph has no edges. Link or the doc is isolated.
"I'll document it after it's working"	Documentation written separately from code drifts immediately. Write with the code.
"A long comment will do for now"	Comments >5 lines belong in docs/. Move it.
"I'll update the docs in a follow-up"	Follow-up docs never match the implementation. Update alongside the change.
"The skill already covers this"	Check for duplication -- if both a skill and a doc cover it, consolidate.

---

Red Flags -- STOP

• Doc file over 800 tokens -- STOP. Split at the second concept.
• Missing YAML frontmatter -- STOP. Add the full block before continuing.
• Missing ## Related section -- STOP. Add at least one annotated link. (sole exception: docs/DOD.md -- see the defining-done skill's canon template)
• Two files covering the same concept -- STOP. Delete one; link from the other.
• Updating code without checking related docs -- STOP. Update stale docs first.

---

Related Skills

• writing-skills -- skill authoring standards, anatomy gate, and skill-reviewer dispatch pattern for validating completed skills

Reference

For the domain taxonomy, frontmatter schema, and guide template, see references/DOCUMENTATION_EXAMPLES.md.

Documentation principles: references/DOCUMENTATION_PRINCIPLES.md

Wiki/knowledge-base principles: references/WIKI_PRINCIPLES.md