references/docs-strategy.md

1,336 tokens · o200k_base · 6,206 bytes

Docs Strategy

Modes

The skill operates in one of five modes. Select the mode before doing any substantive work.

Mode	When to use	Output
`maintenance`	The page is structurally sound; only editorial, compliance, or formatting fixes are needed.	Clean up style, components, frontmatter, and formatting. Run validation.
`improve`	The page works but could be clearer, better organized, or better illustrated.	Strengthen framing, order, explanation, and examples while keeping the page's identity. Run validation.
`rewrite`	Local edits will not fix the page because its shape, framing, or scope is fundamentally wrong.	Materially replace the page. Preserve any sound content; discard or restructure the rest. Run validation.
`author`	A new page needs to be created, or a draft needs to be completed from notes or a brief.	Write the page from scratch using the appropriate doc type as a guide. Run validation.
`strategy`	The user wants planning, not edits — page-job analysis, outline, split/merge recommendation.	Return a planning artifact: audience, page job, primary doc type, recommended outline, split/merge recommendation, and a preserve list. Do not run formatting or validation.

Mode Selection Rules

If the user explicitly names a mode (e.g., "rewrite this"), use it.
If the user says "review this doc" without further specifics, use hybrid behavior:
- Critique-first for strategy asks or obviously weak drafts.
- Improve-first for normal cleanup or improvement asks.
If the request is ambiguous (e.g., "improve this doc", "make this better"), default to improve.
If diagnosis reveals the page is structurally weak, escalate from improve to rewrite — do not stop at sentence-level edits when the page shape is the problem.

Doc Types

Every page has one primary doc type. Select it before editing. A page may also contain secondary sections — clearly headed sections whose content follows a different doc type's shape. This is normal and expected. The primary type determines the page's overall shape and evaluation criteria; each secondary section is evaluated by its own type's criteria.

Doc Type	Page Job	Shape
`concept`	Help the reader understand what something is and why it matters.	Definition → mental model → relationship to other concepts → when to use.
`task`	Help the reader accomplish a specific goal.	Goal statement → prerequisites → ordered steps → expected result → troubleshooting.
`reference`	Help the reader look up specific details (options, API, config).	Brief intro → structured entries (name, type, default, description) → examples where helpful.
`troubleshooting`	Help the reader diagnose and fix a problem.	Symptom → cause → fix → verification.
`migration`	Help the reader move from one version or approach to another.	What changed → why → step-by-step migration path → breaking changes → verification.
`decision guide`	Help the reader choose between options.	Decision context → options with trade-offs → recommendation → how to switch later.

Mapping Overview Pages

Overview pages in /docs (e.g., section landing pages) do not get a special type:

Default to concept — most overviews explain what a feature area is and how its parts relate.
Use decision guide when the page is primarily comparative (e.g., choosing a builder or renderer).

Common Secondary Sections

Some doc type combinations appear frequently and are well-structured by convention:

Primary Type	Common Secondary Section	Example
`task`	`reference` — API options or configuration table at the end	A "Configure visual tests" task page ending with a table of config options.
`task`	`troubleshooting` — common errors after the procedure	A "Set up Storybook" task page ending with "Common issues" entries.
`concept`	`task` — brief how-to showing the concept in action	A "Decorators" concept page including a short "Add a decorator" procedure.
`concept`	`reference` — summary table of related API surface	A "Controls" concept page ending with a table of annotation types.
`migration`	`troubleshooting` — known issues during migration	A migration guide ending with "If you see error X" fix entries.
`decision guide`	`reference` — comparison table of options	A "Choose a builder" page with a detailed feature-comparison table.

A secondary section is well-structured when it:

Has its own clear heading that signals the content shift (e.g., "API reference", "Troubleshooting", "Quick start").
Follows the shape expected for its doc type (e.g., a reference section uses structured entries, not prose).
Supports the primary page job rather than introducing an unrelated topic.

Split and Escalation

If diagnosis reveals the page is overloaded — serving multiple jobs with no clear primary — switch to strategy mode or recommend a page split before polishing.

Not overload: A page with well-structured secondary sections (see above) is not overloaded. A task page with a reference table at the end, or a concept page with a brief procedure, is normal.

Signs of genuine overload:

The page has no clear primary doc type — two or more types compete for dominance with roughly equal weight.
The page covers multiple unrelated features under one heading.
A secondary section has grown large enough to stand alone as its own page (rough signal: it exceeds half the length of the primary content).
Conceptual prose and step-by-step instructions are interleaved throughout the page rather than separated into distinct sections.

Intervention Thresholds

Use the smallest intervention that materially improves reader usefulness:

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

Referenced from SKILL.md

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 |

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

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.

Source excerpt starting at line 96.
96Use the thresholds in `references/docs-strategy.md`:

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.