review-docs

ドキュメントをレビューする

このスキルは、ドキュメントファイルに対して評価と改善のループを実行します。

対象: $ARGUMENTS

関連スキル: write-docs

ワークフローの概要

┌──────────────────────────────────────────────────────────────┐
│  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

状態ファイル

スクラッチパッドディレクトリに状態ファイルを作成し、ラウンドをまたいで全てのissueを追跡します。これにより、同じissueを再発見することを防ぎ、修正の検証が可能になります。

パス: <scratchpad>/review-<filename>.md

フォーマット:

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

ステータスの定義:

• pending: issueを発見したが、まだ対応していない
• fixed: 改善エージェントが修正したと主張しているが、検証が必要
• verified-fixed: 評価により、修正が正しく適用されたことが確認された
• not-fixed: 評価により、修正が正しく適用されなかったことが判明した
• wont-fix: 誤検知、スコープ外、または意図的なもの (例: ドキュメントの拡充を必要とする完全性のissue)

ステップ1: 初回評価

最初のラウンドでは、Taskツールを使用して2つのサブエージェントを並列で起動します:

// 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...")

スタイルエージェントのプロンプト (ラウンド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. ...

コンテンツエージェントのプロンプト (ラウンド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. ...

ラウンド1の後、発見した全てのissueを含む状態ファイルを作成します。

ステップ2: 要約とユーザーへの確認

両方のエージェントが戻ったら、それらのレポートを要約に統合します:

## 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. ...

次に、AskUserQuestionを使用してユーザーに確認します:

• 改善: 調査結果に基づいて改善を行い、その後再評価します
• 完了して終了: 残りの全てのissueを修正して終了します (再評価なし)
• 終了: 変更を加えずにループを終了します

ステップ3: トリアージ (改善の前)

改善エージェントを実行する前に、保留中のissueをユーザーと確認します。新しいセクションの追加を必要とする完全性のissueは wont-fix としてマークします。これらはドキュメントの拡充であり、レビューの修正ではありません。

AGENTS.md のガイダンスより:

「求められたことを行い、それ以上でもそれ以下でもないこと。」 「求められたことを超えて、機能を追加したり、コードをリファクタリングしたり、『改善』を行ったりしないこと。」

レビュースキルは既存のコンテンツを改善します。新しいセクションの追加は別のタスクです。

ステップ4: 改善

保留中のissueのみを対象とする単一の改善エージェントを起動します:

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

改善エージェントのプロンプト

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 `../../VOICE.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
   - Apply the fix based on what the source code actually shows

5. Apply style fixes

6. Run prettier: pnpm exec prettier --write $ARGUMENTS

DO NOT:
- Add new sections
- Expand the document
- Fix issues not in the list above

Return a summary:

CHANGES MADE:

| ID | Fix applied | Verification |
|----|-------------|--------------|
| X | [description] | [source file:line checked] |
| Y | [description] | n/a |

改善後、状態ファイルを更新してissueを fixed としてマークします。

ステップ4b: 完了して終了 (ステップ4の代替)

ユーザーが「完了して終了」を選択した場合、残りの全ての保留中のissueを再評価せずに修正します。これは、評価が満足のいくものであり、ユーザーが修正を適用して先に進みたい場合に便利です。

ワークフロー:

1. トリアージを実行し (ステップ3と同じ)、スコープ外の項目を wont-fix としてマークします
2. 改善エージェントを起動します (ステップ4と同じプロンプト)
3. 状態ファイルを更新してissueを fixed としてマークします
4. ループを終了します - 再評価は行いません

このパスは、改善エージェントが修正を正しく適用することを信頼し、検証サイクルをスキップします。次の場合に使用します:

• issueが単純なスタイルの修正である場合
• 時間が限られており、再評価にコストをかける価値がない場合
• スコアがすでに許容範囲であり、軽微な調整のみが残っている場合

ステップ5: 検証評価

以降のラウンドでは、評価エージェントが修正を検証し、かつ新しいissueを発見します:

スタイルエージェントのプロンプト (検証)

Verify fixes and evaluate documentation: $ARGUMENTS

Read the state file first: [path to state file]

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

Your job:
1. VERIFY fixes marked as "fixed" in the state file - confirm they were actually applied
2. Score style dimensions (do NOT re-flag wont-fix issues)
3. Flag only NEW issues not already in the state file

VERIFY THESE FIXES:
[paste fixed style issues from state file]

Return in this format:

VERIFICATION REPORT:

| ID | Status | Notes |
|----|--------|-------|
| X | verified-fixed / not-fixed | [what you found] |

STYLE SCORES:
READABILITY: [score]/10
VOICE: [score]/10

NEW ISSUES (not already in state file):
- [issue] or "None found"

コンテンツエージェントのプロンプト (検証)

Verify fixes and evaluate documentation content: $ARGUMENTS

Read the state file first: [path to state file]

Then read $ARGUMENTS and verify claims against source code in packages/tldraw/.

Your job:
1. VERIFY accuracy fixes marked as "fixed" in the state file
2. Score content dimensions (do NOT re-flag wont-fix issues)
3. Flag only NEW accuracy issues not already in the state file

VERIFY THESE FIXES:
[paste fixed accuracy issues from state file]

Return in this format:

VERIFICATION REPORT:

| ID | Status | Notes |
|----|--------|-------|
| X | verified-fixed / not-fixed | [what you found in doc AND source] |

CONTENT SCORES:
COMPLETENESS: [score]/10 (score existing content only, ignore wont-fix items)
ACCURACY: [score]/10

NEW ACCURACY ISSUES (not already in state file):
- [issue with source file:line] or "None found"

検証後、状態ファイルを新しいステータスと新たなissueで更新します。

ステップ6: ループ

次のいずれかになるまでループを続けます:

• ユーザーが「終了」を選択する (変更を加えずに終了)
• ユーザーが「完了して終了」を選択する (修正を適用してから終了)
• スコアが許容レベル (40点中32点以上) に達する
• 全てのissueが verified-fixed または wont-fix になる

注意事項

• 状態ファイルは、ラウンドをまたいで同じissueを再発見することを防ぎます
• 評価エージェントは、スコアを付ける前に以前の修正を検証します
• wont-fix は、新しいセクションを必要とする完全性のissueに適しています
• 正確性の検証は重要です: 改善エージェントは、正確性に関する修正を適用する前に、実際のソースコードを読む必要があります
• 効率性のため、スタイル評価とコンテンツ評価は常に並列で実行されます