Iron rule: Do not write documentation as vision or speculation. Documentation must reflect the current facts of the code, configuration, and decisions.
Workflow
- Step 1: Confirm the documentation type ⚠️ REQUIRED
- 1.1 Determine whether this is a specification document, design description, usage instructions, change log, or skill documentation.
- 1.2 Clarify who the readers are and what questions the documentation needs to answer.
- Step 2: Collect authoritative sources ⚠️ REQUIRED
- 2.1 Extract facts from code, configuration, existing documentation, and commit intent.
- 2.2 When facts are insufficient, mark unknown points first; do not fill them in from your own imagination.
- Step 3: Organize the content
- 3.1 Write the structure first, then add details, commands, examples, and links.
- 3.2 When cross-references are needed, ensure paths and headings are genuinely usable.
- Step 4: Do a synchronization check
- 4.1 Check whether the documentation is consistent with the current code and workflow.
- 4.2 If the code has changed but the documentation cannot be fully updated, clearly state the gaps.
Focus points
- Whether the title accurately reflects the reader's task.
- Whether example commands are genuinely executable.
- Whether links, paths, skill names, and script names exist.
- Whether the documentation explains limitations, prerequisites, and follow-up actions.
Project-specific tips
- If docs/ exists in the repository, check subdirectories such as standards/, design/, and plan/ first, rather than assuming all documentation is in the root directory.
- When diagrams are needed, prefer Mermaid rather than embedding hard-to-maintain image descriptions.
- When the code or skill workflow changes significantly, prioritize updating the commands and paths in the README, design documents, and skill documentation.
Anti-patterns
- Assuming docs/ must exist and writing documentation around a directory that does not exist.
- Copying the code structure without explaining why it is designed that way.
- Replacing operational steps and constraints with slogans.
Pre-delivery checklist
- All documentation conclusions are backed by code, configuration, or existing documentation.
- Paths, links, skill names, and commands have all been verified.
- The intended readers and usage scenarios of the documentation have been clarified.
- Unknown information has not been disguised as established fact.