/review-docs

name: review-docs
description: Review and improve tldraw SDK documentation against the voice and docs guides, scoring each article and iterating until it passes. Use when asked to review docs, audit an article in apps/docs/content, check whether documentation follows the style guide, or improve existing documentation.

Review documentation

This skill runs an evaluation and improvement loop on a documentation file.

**Target**: $ARGUMENTS

**Relevant skills**: `write-docs`

Workflow overview

┌──────────────────────────────────────────────────────────────┐
│  INITIALIZE: Create state file to track issues               │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│  EVALUATE (parallel)                                         │
│  ┌─────────────────────┐    ┌─────────────────────────────┐  │
│  │ Style Agent         │    │ Content Agent               │  │
│  │ (readability+voice) │    │ (completeness+accuracy)     │  │
│  └─────────────────────┘    └─────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│  UPDATE STATE: Add new issues, verify fixed issues           │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│  SUMMARIZE: Present findings, ask user for next step         │
└──────────────────────────────────────────────────────────────┘
                              ↓
           ┌──────────────────┼──────────────────┐
           ↓                  ↓                  ↓
    [User: improve]   [User: complete]    [User: done]
           ↓                  ↓                  ↓
┌──────────────────┐  ┌──────────────────┐    EXIT
│  IMPROVE         │  │  COMPLETE        │
│  (fix issues)    │  │  (fix all, exit) │
└──────────────────┘  └──────────────────┘
           ↓                  ↓
  LOOP → EVALUATE          EXIT

State file

Create a state file in the scratchpad directory to track all issues across rounds. This prevents re-discovering the same issues and allows verification of fixes.

**Path**: `<scratchpad>/review-<filename>.md`

**Format**:

# Review tracker: [filename]

## Issue tracker

Status values: `pending` | `fixed` | `verified-fixed` | `not-fixed` | `wont-fix`

| ID  | Issue         | Type                        | Status         | Round | Notes            |
| --- | ------------- | --------------------------- | -------------- | ----- | ---------------- |
| 1   | [description] | Style/Accuracy/Completeness | pending        | 1     | [details]        |
| 2   | [description] | Accuracy                    | verified-fixed | 1     | Fixed in round 1 |
| 3   | [description] | Completeness                | wont-fix       | 2     | Out of scope     |

## Round history

### Round 1

- Style: X/10, Voice: X/10, Completeness: X/10, Accuracy: X/10
- **Total: X/40**

**Status definitions**:

• `pending`: Issue discovered, not yet addressed
• `fixed`: Improvement agent claims to have fixed it, needs verification
• `verified-fixed`: Evaluation confirmed the fix was applied correctly
• `not-fixed`: Evaluation found the fix wasn't applied correctly
• `wont-fix`: False alarm, out of scope, or intentional (e.g., completeness issues that require documentation expansion)

Step 1: Initial evaluation

For the **first round**, launch two subagents **in parallel** using the Task tool:

// Single message with two Task tool calls:
Task(subagent_type="general-purpose", model="opus", prompt="Style evaluation...")
Task(subagent_type="general-purpose", model="opus", prompt="Content evaluation...")

Style agent prompt (round 1)

Evaluate documentation style for: $ARGUMENTS

Read the shared guides relative to this skill directory, then read the target document:
1. `../../VOICE.md`
2. `../shared/docs-guide.md`
3. $ARGUMENTS

Score these dimensions (0-10):

READABILITY - How clear and easy to understand is the writing?
- Clear, direct sentences
- Logical flow between sections
- Appropriate use of code snippets and links
- No unnecessary jargon

VOICE - How well does it follow the writing guide?
- Confident assertions (no hedging)
- Active voice, present tense
- No AI writing tells (hollow importance, trailing gerunds, formulaic transitions)
- Appropriate tone (expert-to-developer)
- Sentence case headings

Important! Include as many high-priority fixes as needed.

Return in this exact format:

STYLE REPORT: [filename]

READABILITY: [score]/10
- [specific issue or strength]
- [specific issue or strength]

VOICE: [score]/10
- [specific issue or strength]
- [specific issue or strength]

PRIORITY FIXES:
1. [Most important style issue]
2. [Second most important]
3. [Third most important]
4. ...

Content agent prompt (round 1)

Evaluate documentation content for: $ARGUMENTS

Read $ARGUMENTS, then verify claims against the source code in packages/editor/ and packages/tldraw/.

Score these dimensions (0-10):

COMPLETENESS - How thorough is the coverage?
- Overview establishes purpose before mechanism
- Key concepts explained with enough depth
- Illustrative code snippets where needed
- Links to relevant examples in apps/examples (if applicable)

ACCURACY - Is the technical content correct?
- Code snippets are syntactically correct and use valid APIs
- API references match actual implementation
- Described behavior matches the code
- No outdated information

For accuracy issues, include file:line references to the source code.

Important! Include as many high-priority fixes as needed. Make sure that all accuracy issues are flagged.

Return in this exact format:

CONTENT REPORT: [filename]

COMPLETENESS: [score]/10
- [specific issue or strength]
- [specific issue or strength]

ACCURAC