improve-doc

Improve Doc

Analyze an existing markdown document, classify sections by Diataxis type, identify issues, and interactively refine each section.

Arguments

• Path: Path to the markdown document to improve (required)

Workflow Overview

Invoke the improve-doc skill with a document path, e.g. improve-doc docs/guides/getting-started.md.

The skill runs in two phases:

1. Analysis Phase: Parse document, classify sections, identify issues
2. Refinement Phase: Interactive loop to improve each section

Gates

Hard sequencing — advance only when the pass condition is met (artifact or explicit user input, not assumed).

Before Phase 2 (refinement):

1. Read — Full contents of the file at Path are loaded.
   • Pass: Enumerated sections (from # / ## / ### headings) cover every heading in the file; titles match the source.
2. Core skill — docs-style is loaded (or its path read) before classification.
   • Pass: Analysis output reflects at least one concrete principle from that skill (name it or quote briefly).
3. Handoff — User saw an analysis summary (template in Step 5 or equivalent) and entered start to begin refinement, or abort to exit.
   • Pass: If abort, no writes to Path. If start, proceed to Phase 2.

Before overwriting the file (Phase 2, Step 4):

1. Choices — Every section with open issues has a terminal outcome: applied yes, unchanged skip, or modify loop finished with yes or skip.
   • Pass: No section left in a pending modify state unless the user aborted the whole session (then do not write).
2. Skips — Content for every skip matches the original section text (copy preserved, not paraphrased).
   • Pass: Full block equality check against the initial read (line-for-line, including whitespace).
3. Write — Only after the above.
   • Pass: Single save to Path; completion report notes backup or major restructure if applicable (Rules).