WIP: Demo run of docs-review skill to update Stories docs section

.agents/skills/docs-review/SKILL.md

@@ -0,0 +1,151 @@
+---
+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.

.agents/skills/docs-review/references/docs-antipatterns.md

@@ -0,0 +1,85 @@
+# Docs Antipatterns
+
+Each antipattern includes the problem, how to recognize it, and what to do about it.
+
+## 1. Background-First Opening
+
+**Problem:** The page opens with history, motivation, or context before telling the reader what the page is about or what they will be able to do.
+
+**Recognize it:** The first heading or paragraph talks about why something was built, how it evolved, or what problem it solves in the abstract — before stating what the feature *is*.
+
+**Fix:** Open with what the thing is and what the reader can do with it. Move background to a later section or inline it where it supports a specific point.
+
+## 2. Unseparated Mixed Doc Types
+
+**Problem:** A single page interleaves explanatory prose, step-by-step instructions, and reference tables without clear sectional boundaries. The reader cannot scan for what they need.
+
+**Recognize it:** The page alternates between doc type shapes *within the same sections* — e.g., conceptual paragraphs between procedure steps, or config tables dropped mid-narrative with no heading. There are no clear headings signaling a transition from one type of content to another.
+
+**Not this antipattern:** A page with a clear primary type and well-separated secondary sections (each with its own heading and following its own type's shape) is fine. See "Common Secondary Sections" in `docs-strategy.md`.
+
+**Fix:** Identify the primary doc type. For secondary content that belongs on this page, extract it into its own clearly headed section and ensure it follows its type's shape. For secondary content large enough to stand alone, recommend splitting into a separate page. The primary type determines the page's overall shape.
+
+## 3. Edge Cases Before the Default Path
+
+**Problem:** Exceptions, caveats, and special configurations appear before the reader sees the standard approach.
+
+**Recognize it:** The first code example or instruction set handles a non-default scenario. Callouts with warnings appear before the basic usage.
+
+**Fix:** Lead with the default path. Move edge cases, exceptions, and advanced configuration after the reader has seen the standard approach. Exception: safety-critical warnings that must precede action.
+
+## 4. Technically Valid but Weak Examples
+
+**Problem:** Code examples are syntactically correct but do not represent realistic usage. They teach the API surface without showing how a real project would use the feature.
+
+**Recognize it:** Examples use placeholder names like `foo`/`bar`, show only the minimum required props, or demonstrate a feature in isolation from any meaningful context.
+
+**Fix:** Replace with examples that reflect real usage patterns. Use realistic component names, props, and data. Show enough context that the reader can adapt the example to their own project.
+
+## 5. Late Term Definition
+
+**Problem:** A key term is used several times before it is defined. The reader must re-read earlier sections once they finally encounter the definition.
+
+**Recognize it:** A Storybook-specific term (e.g., "decorator", "loader", "play function") appears in the opening paragraphs but is not defined or linked until later.
+
+**Fix:** Define or link the term on first use. If the page is *about* the term, the opening sentence should define it.
+
+## 6. Feature List Without Helping the Reader Act or Decide
+
+**Problem:** The page lists what a feature can do without helping the reader understand when to use it, how to choose between options, or what to do next.
+
+**Recognize it:** Bullet points or paragraphs describe capabilities ("X supports Y", "You can also Z") without connecting them to reader goals or decisions.
+
+**Fix:** Frame capabilities around reader tasks or decisions. "Use X when you need Y" is more useful than "X supports Y."
+
+## 7. Buried Procedure Outcome
+
+**Problem:** A task page walks through steps but never states what the reader will have when they are done. The outcome is implied, not stated.
+
+**Recognize it:** The procedure ends with the last step. There is no "you should now see…" or "this gives you…" summary.
+
+**Fix:** State the expected outcome after the procedure. If possible, show what success looks like (a screenshot, a terminal output, or a description of the resulting behavior).
+
+## 8. Preserving Weak Structure Because It Is "Clean"
+
+**Problem:** A page has correct grammar, consistent formatting, and no broken links — but its structure does not serve the reader. A `maintenance` pass would miss the real issue.
+
+**Recognize it:** The page feels polished but unhelpful. Readers would need to read the whole page to find what they need. Sections are ordered by implementation detail rather than reader need.
+
+**Fix:** Escalate to `improve` or `rewrite`. Clean formatting is not a reason to preserve a page shape that does not work.
+
+## 9. Overexplaining Basics While Underexplaining Storybook-Specific Behavior
+
+**Problem:** The page spends space on concepts the target audience already knows (e.g., what a component is, how imports work) while glossing over Storybook-specific behavior that is actually confusing.
+
+**Recognize it:** Paragraphs explaining general web development concepts sit alongside one-sentence descriptions of Storybook features that have no obvious analog.
+
+**Fix:** Assume basic web development knowledge (HTML, CSS, JavaScript, components). Invest explanation space in Storybook-specific concepts, behaviors, and mental models.
+
+## 10. Tightening Prose When Rewrite Is Actually Needed
+
+**Problem:** Sentence-level edits are applied to a page whose fundamental organization is wrong. The page gets shorter and cleaner but remains unhelpful.
+
+**Recognize it:** After a pass of prose tightening, the page still does not clearly serve its intended job. The reader's experience is not materially better.
+
+**Fix:** Step back and diagnose at the page level. If the shape is wrong, restructure or rewrite — do not keep polishing.

.agents/skills/docs-review/references/docs-principles.md

@@ -0,0 +1,46 @@
+# Docs Principles
+
+## North Star
+
+Good documentation reduces **time-to-understanding** or **time-to-success** for the reader. Every edit, restructure, or rewrite should move the page closer to one of these outcomes.
+
+## Dual-Reader Requirement
+
+Storybook docs must work for two audiences simultaneously:
+
+1. **Frontend developers** scanning for answers, examples, and steps they can act on immediately.
+2. **LLMs and retrieval systems** that parse docs for accurate, structured information to surface in AI-assisted workflows.
+
+Write for the human first. Structure for both.
+
+## Quality Dimensions
+
+Use these dimensions to evaluate whether a page is doing its job. They are ordered from most structural to most surface-level — fix the top of the list before polishing the bottom.
+
+### 1. Intent Clarity
+
+The page states what it will help the reader do or understand within the first two sentences. A reader (or retrieval system) can decide whether this page is relevant without scrolling.
+
+### 2. Audience Fit
+
+The page assumes the right level of prior knowledge. It does not over-explain web fundamentals or under-explain Storybook-specific behavior. It meets the reader where they are.
+
+### 3. Information Shape
+
+The page is organized around the reader's task or question, not around the feature's implementation. Sections follow a logical progression: context → action → result, or definition → usage → edge cases. When a page contains secondary sections of a different doc type, each section follows the progression appropriate to its own type.
+
+### 4. Conceptual Clarity
+
+Abstract ideas are grounded in concrete terms. Relationships between concepts are explicit. The reader can build a mental model, not just follow steps.
+
+### 5. Task Usability
+
+Procedures are complete, ordered, and testable. The reader can follow them without guessing at missing steps. The default path comes first; variations and edge cases follow.
+
+### 6. Example Quality
+
+Code examples are representative of real usage, not minimal to the point of being misleading. They demonstrate the concept or task the page is about, not just syntactic validity.
+
+### 7. Economy
+
+Every sentence earns its place. Redundant explanations, filler transitions, and throat-clearing preamble are removed. Brevity serves the reader — but not at the cost of clarity.