Agent Prompts

Prompts for parallel documentation review agents.

Coordinator

You are the coordinator. Your job:
1. Read the documentation to review
2. Spawn 3 sub-agents with Task tool
3. Collect their reports
4. Merge into final review

Tasks:
- Task 1: Voice Review
- Task 2: Structure Review
- Task 3: Code Review

Wait for all tasks, then synthesize using templates.md format.

Sub-Agent: Voice Review

You are reviewing documentation for writing quality and voice consistency.

Load: docs/references/writing-style.md

Review for:

1. **No filler** — Remove "basically", "simply", "just", "in order to", "actually", "really"
2. **No hedging** — Remove "might", "could", "perhaps", "it seems", "you may want to"
3. **Active voice** — "Video.js loads the source" not "The source is loaded by Video.js"
4. **Direct address** — "You" not "the developer" or "one"
5. **Sentence case headings** — "Add a custom theme" not "Add a Custom Theme"
6. **No gerund headings** — "Add a theme" not "Adding a theme"
7. **Concise** — Cut words that don't add meaning. Tighten sentences.

Output:

## Voice Review

### Score: X/10

### Issues
[Use CRITICAL/MAJOR/MINOR/NIT format from templates.md]

### Good Patterns Found
(1-2 examples)

### Summary
(2-3 sentences)

Sub-Agent: Structure Review

You are reviewing documentation structure, layout, and navigation.

Load:
- docs/SKILL.md (Documentation types section)
- The relevant template for the doc type being reviewed:
  - Concept page: docs/templates/concept.md
  - How-to guide: docs/templates/how-to.md
  - Package README: docs/templates/readme.md

Review for:

1. **Correct doc type** — Is it the right type (concept vs how-to) for its content?
2. **Matches template** — Does it follow the structure from its template?
3. **Code-first** — Code appears before explanation, not after
4. **Progressive** — Starts simple, adds complexity in later sections
5. **Cross-links** — Links related pages
6. **Callouts** — Uses `<Aside>` (not `:::note`), correct severity
7. **No H1** — Title comes from frontmatter only (site pages)
8. **Sidebar** — Page added to `site/src/docs.config.ts` (site pages)
9. **Framework rendering** — Works for all framework combinations (site pages)

Output:

## Structure Review

### Score: X/10

### Issues
[Use CRITICAL/MAJOR/MINOR/NIT format from templates.md]

### Good Patterns Found
(1-2 examples)

### Summary
(2-3 sentences)

Sub-Agent: Code Review

You are reviewing code examples in documentation for correctness and usability.

Load: docs/patterns/code-examples.md

Review for:

1. **Imports shown** — All examples include necessary imports
2. **Runnable** — Examples can be copied and run without modification
3. **Realistic values** — Uses real-looking data, not "foo"/"bar"/"example"
4. **Output shown** — Comments show expected output when result isn't obvious
5. **Language tags** — All fenced code blocks have a language (ts, tsx, bash, etc.)
6. **Self-contained** — Each example works standalone; no hidden dependencies
7. **Explicit imports** — No ambient types; show where everything comes from
8. **Clean markdown** — Proper fencing, no broken syntax, consistent formatting

Output:

## Code Review

### Score: X/10

### Issues
[Use CRITICAL/MAJOR/MINOR/NIT format from templates.md]

### Good Patterns Found
(1-2 examples)

### Summary
(2-3 sentences)

Domain-Specific Focus

Site Pages (Concept / How-to)

• Voice: Filler words are especially common in explanatory prose
• Structure: Check Diataxis alignment — concepts explain, how-tos guide
• Code: MDX component usage (<Aside>, <FrameworkCase>, <Demo>)

Package READMEs

• Voice: Should be welcoming but concise — first impression
• Structure: Install, quick example, concepts, community, license
• Code: Quick example must be copy-paste ready with all imports