document-refinement

ドキュメントの精査

「このドキュメントは明確で、次のフェーズに進む準備ができていますか？」に答えるための体系的なレビューです。

対象読者： ブレインストーミングの成果物、計画書、PRDを引き継ぎ前にレビューするエンジニア。 目標： 曖昧さや抜け漏れを早期に発見します。軽微な問題は自動修正し、重要な問題にはフラグを立てます。

評価基準

各項目を1～5で採点します。

基準	1（不合格）	3（許容範囲）	5（優秀）
明確さ	曖昧な表現、定義されていない用語	おおむね明確で、曖昧さはわずか	すべての記述が実行可能で具体的
完全性	必須セクションが不足	すべてのセクションがあるが、一部の内容が薄い	すべてのセクションが充実しており、抜け漏れがない
具体性	「エラーを適切に処理する」	具体的な詳細がいくつかある	正確な動作、値、境界が定義されている
YAGNI	推測的な機能、過剰な作り込み	軽微なスコープの拡大	すべての項目が明示された要件に結び付いている
ユーザーの意図への忠実さ	元の依頼から逸脱している	おおむね意図に沿っている	ユーザーの依頼を正確に捉えている

レビュープロトコル

DOCUMENT = read target document
DOC_TYPE = classify(DOCUMENT) → brainstorm | plan | prd | other
REQUIREMENTS = load references/document-type-requirements.md[DOC_TYPE]
VAGUE_PATTERNS = load references/vague-language-patterns.md

Step 1: Structural Check
  For each REQUIRED_SECTION in REQUIREMENTS[DOC_TYPE].sections:
    If REQUIRED_SECTION missing from DOCUMENT:
      findings.blocking.append({type: "missing_section", section: REQUIRED_SECTION})

Step 2: Vagueness Scan
  For each LINE in DOCUMENT:
    If LINE matches VAGUE_PATTERNS.qualifier_words OR VAGUE_PATTERNS.hedge_phrases:
      If context is risk-identification OR explicit-deferral:
        skip (acceptable vagueness)
      Else if fix is obvious (simple word replacement):
        auto_fixes.append({line: LINE, fix: replacement})
      Else:
        findings.blocking.append({type: "vague_language", line: LINE, suggestion: "specify X"})

Step 3: Criteria Scoring
  For each CRITERION in [Clarity, Completeness, Specificity, YAGNI, User Intent Fidelity]:
    score[CRITERION] = assess(DOCUMENT, CRITERION) → 1-5
    If score[CRITERION] < 3:
      findings.blocking.append({type: "low_score", criterion: CRITERION, details: "..."})

Step 4: Categorize Findings
  blocking = findings where score < 3 OR missing required sections
  polish = findings where score 3-4 (improvable but not blocking)

出力形式

## Document Refinement Report

**Document:** [filename or title]
**Type:** [brainstorm | plan | prd]
**Verdict:** READY | NEEDS REVISION

### Scores
| Criterion | Score | Notes |
|-----------|-------|-------|
| Clarity | X/5 | ... |
| Completeness | X/5 | ... |
| Specificity | X/5 | ... |
| YAGNI | X/5 | ... |
| User Intent Fidelity | X/5 | ... |

### Auto-Fixed (applied)
- [Line X]: "should handle" → "returns 422 with error message"

### Blocking Issues
1. [Issue]: [What's wrong] → [What to specify]

### Polish Suggestions
- [Improvement that would raise score but isn't blocking]

イテレーションのルール

MAX_ROUNDS = 2

If VERDICT == "NEEDS REVISION":
  Apply auto-fixes directly to document
  Present blocking issues to user
  User addresses blocking issues
  Re-run assessment (round 2)

If round 2 still has blocking issues:
  Present remaining issues
  Ask user: "Ship as-is or address remaining items?"
  Do NOT run round 3 (diminishing returns)

アンチパターン

アンチパターン	望ましくない理由	代わりに
実装コードをレビューする	このスキルの対象はドキュメントであり、コードではありません	code-review または plan-review を使用します
すべての行を採点する	過剰な分析はスピードを損ないます	セクション単位の評価に集中します
文体の好みを理由にブロックする	「別の表現にしたい」は抜け漏れではありません	情報不足または曖昧さがある場合にのみブロックします
レビュー中にスコープを拡大する	「Xも追加すべきです」	ドキュメント種別の要件に照らして不足している点のみを指摘します
満点を必須とする	すべての基準が3/5なら、次に進む準備ができています	3未満のスコアがある場合のみブロックします