octocode-documentation

name	octocode-documentation
description	Use when writing or updating docs: README, API docs, runbooks, AGENTS.md, CLAUDE.md, ADRs, Diátaxis restructuring, or codebase documentation for humans or coding agents.

Octocode Documentation

Evidence-backed docs for humans and agents. Classify first. Gate writes. Prefer durable cross-refs over code dumps.

Flow

UNDERSTAND → RESEARCH → CLASSIFY → OUTLINE GATE → WRITE → VERIFY

Compress when targets and type are named. Expand when claims need verification.

Hard rules

• MUST verify claims in the repo before asserting them.
• MUST pick one mode and load its routes before writing.
• MUST gate creates/overwrites unless the user already approved targets this turn.
• MUST treat AGENTS.md as a docs index (links + non-obvious rules), not a content dump.
• Prefer durable pointers (module path, contract name, doc link) over line numbers and pasted code.
• FORBIDDEN: inventing commands, paths, APIs, or env vars.
• Keep one Diátaxis type per page; link siblings instead of mixing.
• Do not copy README/CONTRIBUTING into AGENTS.md, or paste large code blocks — link the source.

Stop when: outline gate awaits answer; write+verify finishes; fact missing (report gap); user cancels.

Routes

Load only what the step needs:

• Read references/modes.md when choosing mode or audience.
• Read references/evidence-research.md when gathering or verifying repo facts.
• Read references/diataxis.md when writing or reviewing human-docs.
• Read references/agents-md.md when writing or updating agent instruction files.
• Read references/adr.md when recording a decision.
• Read references/agent-readable.md before WRITE (cross-refs, density, durability).
• Read references/write-verify.md for outline gate, write steps, and verify checklist.
• Skip references/references.md during normal tasks (creation audit only).

Related

• Pure code/repo evidence with no docs deliverable → octocode-research.
• Authoring a SKILL.md → octocode-skills.
• Full multi-file pack → octocode-documentation-writer if installed.
• Unclear mode → ask once: agent-docs / human-docs / adr / codebase-pack.
• Conflicting conventions → surface; do not add a second scheme.
• Missing command → omit or mark unverified. No Octocode → host search tools.