---
name: docs-review
description: 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.
---

# Documentation Review

## Scope

This 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`).

## Use This Skill When

- Asked to review, improve, rewrite, or author documentation in `/docs`.
- Asked for advice on page structure, doc type, audience, or content strategy for `/docs`.
- Asked to fix formatting, style, or compliance issues in `/docs`.

## Use a Light Touch When

- The request is a trivial grammar or typo fix that does not need full diagnosis.
- The page is already structurally sound and only needs minor editorial cleanup.

## Reference Files

This skill uses four reference files under `references/`. Load them in order and only as needed:

| File | Owns | When to Load |
|------|------|--------------|
| `references/docs-principles.md` | North star, quality dimensions, dual-reader requirement | Always — read first |
| `references/docs-strategy.md` | Modes, doc types, intervention thresholds, page-shape guidance | Always — read second |
| `references/docs-antipatterns.md` | Diagnosis patterns and corrective moves | When diagnosing a weak or confusing draft |
| `references/storybook-style.md` | Editorial, MDX components, frontmatter, formatting, validation rules | In `maintenance` mode, or as the final pass of edit modes |

### Ownership Rules

- Strategy references do not own formatting or component rules.
- `storybook-style.md` does not own doc-type or intervention logic.
- This file (`SKILL.md`) owns workflow and handoffs only.

## Workflow

Follow this sequence for every request. Steps 1–4 are diagnosis; steps 5–7 are action.

### 1. Determine the Requested Outcome

Read the user's request and map it to a mode:

| Request Pattern | Mode |
|----------------|------|
| "Fix links, callouts, formatting" | `maintenance` |
| "Make this clearer", "improve this page" | `improve` |
| "This doc is a mess; rewrite it" | `rewrite` |
| "Draft docs for feature X" | `author` |
| "What kind of page should this be?" | `strategy` |
| "Review this doc" (unspecified) | **hybrid** — see below |

**Hybrid behavior:** For vague asks like "review this doc":
- If the draft is obviously weak or the ask implies planning → critique-first (lead with diagnosis).
- If the page is decent and the ask implies cleanup → improve-first (lead with edits).

**Default:** When ambiguous, default to `improve`, not `maintenance`.

### 2. Determine the Primary Doc Type

Read the page and classify it using the doc types in `references/docs-strategy.md`:

- `concept` — explains what something is and why it matters
- `task` — walks the reader through accomplishing a goal
- `reference` — lookup for options, API, or config
- `troubleshooting` — diagnose and fix a problem
- `migration` — move from one version or approach to another
- `decision guide` — choose between options

Always select **one** primary type, even if the page contains secondary elements.

After 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.

### 3. Diagnose the Draft

Evaluate the page against the quality dimensions in `references/docs-principles.md`, in order:

1. Intent clarity
2. Audience fit
3. Information shape
4. Conceptual clarity
5. Task usability
6. Example quality
7. Economy

For 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.

If the page shows signs of structural weakness, load `references/docs-antipatterns.md` and check for common patterns.

### 4. Choose the Intervention Level

Use the thresholds in `references/docs-strategy.md`:

- No structural issues, minor style problems → `maintenance`
- Structure is okay but framing, order, or examples are weak → `improve`
- Structure is wrong for the page's job → `rewrite`
- Page does not exist → `author`
- User wants advice, not edits → `strategy`

**Hard rule:** When the draft is structurally weak, do not stop at sentence-level edits. Reorder, split, replace examples, or rewrite the page shape.

**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.

### 5. Improve or Plan

Execute based on the chosen mode:

- **`maintenance`:** Apply editorial and compliance fixes. Load `references/storybook-style.md` as primary guide.
- **`improve`:** Strengthen framing, order, explanation, and examples. Keep the page's identity. Use `references/storybook-style.md` for the final pass.
- **`rewrite`:** Materially replace the page. Preserve sound content; discard or restructure the rest. Use `references/storybook-style.md` for the final pass.
- **`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.
- **`strategy`:** Return a planning artifact containing:
  - Audience
  - Page job
  - Primary doc type
  - Recommended outline
  - Split/merge recommendation (if applicable)
  - Preserve list (content worth keeping)
  - Do **not** edit files or run validation.

When editing, you may also improve docs-owned snippet files in `docs/_snippets/` if example quality depends on them.

### 6. Apply Storybook Style

For edit modes (`maintenance`, `improve`, `rewrite`, `author`):

- Load `references/storybook-style.md` if not already loaded.
- Apply voice, tone, heading, link, component, and frontmatter rules.
- This step is always downstream of structural and editorial work — never the first pass.

### 7. Validate

For edit modes only:

```bash
yarn fmt:write
yarn docs:check
```

Fix any errors reported by `yarn docs:check`, then run it again to confirm.

**Do not run validation in `strategy` mode** or when no files were edited.

## Handoffs

- **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.
- **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.