review-docs

What this skill does

# 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**:

```markdown
# 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. `../shared/writing-guide.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]

ACCURACY: [score]/10
- [specific issue with file:line reference if inaccurate]
- [specific issue or strength]

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

After round 1, **create the state file** with all discovered issues.

## Step 2: Summarize and prompt user

After both agents return, synthesize their reports into a summary:

```markdown
## Evaluation: [filename]

| Dimension    | Score | Key issue   |
| ------------ | ----- | ----------- |
| Readability  | X/10  | [one-liner] |
| Voice        | X/10  | [one-liner] |
| Completeness | X/10  | [one-liner] |
| Accuracy     | X/10  | [one-liner] |
| **Total**    | X/40  |             |

### Priority fixes

1. [Combined priority 1 from both reports]
2. [Combined priority 2]
3. [Combined priority 3]
4. [Combined priority 4]
5. [Combined priority 5]
6. ...
```

Then ask the user using AskUserQuestion:

- **Improve**: Make improvements based on findings, then re-evaluate
- **Complete and finish**: Fix all remaining issues and exit (no re-evaluation)
- **Done**: Exit the loop without making changes

## Step 3: Triage (before improvement)

Before running the improvement agent, review the pending issues with the user. Mark completeness issues that require adding new sections as `wont-fix` - these are documentation expansion, not review fixes.

Per `AGENTS.md` guidance:

> "Do what has been asked; nothing more, nothing less."
> "Don't add features, refactor code, or make 'improvements' beyond what was asked."

The review skill improves existing content. Adding new sections is a separate task.

## Step 4: Improve

Launch a single improvement agent targeting **only pending issues**:

```
Task(subagent_type="general-purpose", model="opus", prompt="Improve documentation...")
```

### Improvement agent prompt

```
Improve documentation based on specific tracked issues: $ARGUMENTS

Fix ONLY these pending issues:

| ID | Issue | Type | Notes |
|----|-------|------|-------|
[paste pending issues from state file]

Instructions:
1. Read `../shared/writing-guide.md` and `../shared/docs-guide.md` relative to this skill directory
2. Read $ARGUMENTS

3. For each accuracy fix:
   - Read the source file referenced in the notes
   - Verify the correct API/behavior from the source
   - App