| name | docs-improve |
| description | Comprehensively improve a markdown documentation file — invoke when a doc is thin, disorganized, or stale and a full pass is wanted; use docs-accuracy for correctness-only fixes. Fills missing content, fixes inaccuracies and broken links, reorganizes sections to the document's role, and applies formatting standards |
When to use this vs. docs-accuracy: use docs-improve for a full review (accuracy + reorganization + missing content + formatting). Use docs-accuracy for surgical correctness-only fixes when the doc's structure is already sound.
Before doing anything
Load ref-documentation-roles — the canonical source for each document's role and the editing rules that follow from it (in-scope content stays; out-of-scope content relocates rather than being rewritten in place; self-contained vs. generic docs; the cross-reference policy). Evaluate every proposed change against the target document's role; if a change would violate it, stop and reconsider before editing.
Steps
Create a plan for improving this markdown file, then execute it.
- Confirm the document's role per
ref-documentation-roles. Note any sections currently out of scope; plan to relocate them, not rewrite them in place.
- Look for content that is missing from this file for its role and needs to be added. Use the source code as a reference. If there is a conflict, the source code should be believed over the markdown.
- Apply the
docs-accuracy skill.
- Draft the target section outline for this document's role: one section per in-scope responsibility, ordered along the reader's path through the task. Produce the outline as an explicit list before editing.
- Reorganize the sections to match the outline from step 4; every section's content stays within the document's role.
- Make sure that all referenced files and paths have hyperlinks.
- Check all of the links in the document to make sure they are correct.
- Link every product, website, or service the document references to its canonical URL.
- Apply the
ref-markdown-documentation-standards skill for formatting compliance (including the Table of Contents requirement).
- Final residual-check pass. Walk the document end-to-end one more time against the role from step 1; list any remaining bullets where you can name a concrete defect (out-of-scope content, missing example, broken link, stale fact, ambiguous instruction). If you cannot name a concrete defect, the doc is done — stop. Vague "could be improved" feelings are not findings.
When making documentation changes, only do major rewrites if they are necessary. Do not make massive changes without a compelling reason.
