docs-review Skill

1---2name: docs-review3description: Review, improve, rewrite, author, or plan Storybook documentation in /docs. Use this when asked to review docs, improve a page, rewrite documentation, draft new docs, or advise on docs strategy.4---5 6# Documentation Review7 8## Scope9 10This skill applies to documentation files in `/docs` and docs-owned snippet files in `docs/_snippets/`. Do not use this skill for non-docs files (code, configuration, READMEs outside `/docs`).11 12## Use This Skill When13 14- Asked to review, improve, rewrite, or author documentation in `/docs`.15- Asked for advice on page structure, doc type, audience, or content strategy for `/docs`.16- Asked to fix formatting, style, or compliance issues in `/docs`.17 18## Use a Light Touch When19 20- The request is a trivial grammar or typo fix that does not need full diagnosis.21- The page is already structurally sound and only needs minor editorial cleanup.22 23## Reference Files24 25This skill uses four reference files under `references/`. Load them in order and only as needed:26 27| File | Owns | When to Load |28|------|------|--------------|29| `references/docs-principles.md` | North star, quality dimensions, dual-reader requirement | Always — read first |30| `references/docs-strategy.md` | Modes, doc types, intervention thresholds, page-shape guidance | Always — read second |31| `references/docs-antipatterns.md` | Diagnosis patterns and corrective moves | When diagnosing a weak or confusing draft |32| `references/storybook-style.md` | Editorial, MDX components, frontmatter, formatting, validation rules | In `maintenance` mode, or as the final pass of edit modes |33 34### Ownership Rules35 36- Strategy references do not own formatting or component rules.37- `storybook-style.md` does not own doc-type or intervention logic.38- This file (`SKILL.md`) owns workflow and handoffs only.39 40## Workflow41 42Follow this sequence for every request. Steps 1–4 are diagnosis; steps 5–7 are action.43 44### 1. Determine the Requested Outcome45 46Read the user's request and map it to a mode:47 48| Request Pattern | Mode |49|----------------|------|50| "Fix links, callouts, formatting" | `maintenance` |51| "Make this clearer", "improve this page" | `improve` |52| "This doc is a mess; rewrite it" | `rewrite` |53| "Draft docs for feature X" | `author` |54| "What kind of page should this be?" | `strategy` |55| "Review this doc" (unspecified) | **hybrid** — see below |56 57**Hybrid behavior:** For vague asks like "review this doc":58- If the draft is obviously weak or the ask implies planning → critique-first (lead with diagnosis).59- If the page is decent and the ask implies cleanup → improve-first (lead with edits).60 61**Default:** When ambiguous, default to `improve`, not `maintenance`.62 63### 2. Determine the Primary Doc Type64 65Read the page and classify it using the doc types in `references/docs-strategy.md`:66 67- `concept` — explains what something is and why it matters68- `task` — walks the reader through accomplishing a goal69- `reference` — lookup for options, API, or config70- `troubleshooting` — diagnose and fix a problem71- `migration` — move from one version or approach to another72- `decision guide` — choose between options73 74Always select **one** primary type, even if the page contains secondary elements.75 76After selecting the primary type, identify any **secondary sections** — sections with their own heading whose content follows a different doc type's shape. Note these for Step 3. See "Common Secondary Sections" in `references/docs-strategy.md` for expected combinations.77 78### 3. Diagnose the Draft79 80Evaluate the page against the quality dimensions in `references/docs-principles.md`, in order:81 821. Intent clarity832. Audience fit843. Information shape854. Conceptual clarity865. Task usability876. Example quality887. Economy89 90For secondary sections, evaluate dimensions 3 (Information Shape) and 5 (Task Usability) against the secondary section's own doc type, not the page's primary type. All other dimensions apply page-wide.91 92If the page shows signs of structural weakness, load `references/docs-antipatterns.md` and check for common patterns.93 94### 4. Choose the Intervention Level95 96Use the thresholds in `references/docs-strategy.md`:97 98- No structural issues, minor style problems → `maintenance`99- Structure is okay but framing, order, or examples are weak → `improve`100- Structure is wrong for the page's job → `rewrite`101- Page does not exist → `author`102- User wants advice, not edits → `strategy`103 104**Hard rule:** When the draft is structurally weak, do not stop at sentence-level edits. Reorder, split, replace examples, or rewrite the page shape.105 106**Split/escalation rule:** If the dominant job is unclear or the page serves multiple unrelated jobs, switch to `strategy` mode or recommend a page split before polishing. Well-structured secondary sections (see `references/docs-strategy.md`) are not a reason to split.107 108### 5. Improve or Plan109 110Execute based on the chosen mode:111 112- **`maintenance`:** Apply editorial and compliance fixes. Load `references/storybook-style.md` as primary guide.113- **`improve`:** Strengthen framing, order, explanation, and examples. Keep the page's identity. Use `references/storybook-style.md` for the final pass.114- **`rewrite`:** Materially replace the page. Preserve sound content; discard or restructure the rest. Use `references/storybook-style.md` for the final pass.115- **`author`:** Write the page from scratch using the primary doc type's shape as a guide. Use `references/storybook-style.md` for the final pass.116- **`strategy`:** Return a planning artifact containing:117  - Audience118  - Page job119  - Primary doc type120  - Recommended outline121  - Split/merge recommendation (if applicable)122  - Preserve list (content worth keeping)123  - Do **not** edit files or run validation.124 125When editing, you may also improve docs-owned snippet files in `docs/_snippets/` if example quality depends on them.126 127### 6. Apply Storybook Style128 129For edit modes (`maintenance`, `improve`, `rewrite`, `author`):130 131- Load `references/storybook-style.md` if not already loaded.132- Apply voice, tone, heading, link, component, and frontmatter rules.133- This step is always downstream of structural and editorial work — never the first pass.134 135### 7. Validate136 137For edit modes only:138 139```bash140yarn fmt:write141yarn docs:check142```143 144Fix any errors reported by `yarn docs:check`, then run it again to confirm.145 146**Do not run validation in `strategy` mode** or when no files were edited.147 148## Handoffs149 150- **PR creation:** Do not create a PR automatically. If the user asks for end-to-end execution including a PR, hand off to the `pr` skill.151- **Snippet files:** This skill may edit files in `docs/_snippets/` when example quality requires it, but does not own snippet creation for non-docs purposes.152