Document Refinement
Structured review to answer: "Is this document clear and ready for the next phase?"
Audience: Engineers reviewing brainstorm outputs, plans, or PRDs before handoff. Goal: Catch vagueness and gaps early. Auto-fix minor issues, flag substantive ones.
Assessment Criteria
Score each 1-5:
Criterion 1 (Fail) 3 (Acceptable) 5 (Excellent)
Clarity Vague language, undefined terms Mostly clear, few ambiguities Every statement is actionable and specific
Completeness Missing required sections Has all sections, some thin All sections substantive with no gaps
Specificity "Handle errors appropriately" Some concrete details Exact behaviors, values, and boundaries defined
YAGNI Speculative features, gold-plating Minor scope creep Every item traces to a stated requirement
User Intent Fidelity Drifted from original request Mostly aligned Precisely captures what user asked for
Review Protocol
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)
Output Format
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
- [Issue]: [What's wrong] → [What to specify]
Polish Suggestions
- [Improvement that would raise score but isn't blocking]
Iteration Rules
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)
Anti-Patterns
Anti-Pattern Why It's Wrong Instead
Reviewing implementation code This skill is for documents, not code Use code-review or plan-review
Scoring every line Over-analysis kills velocity Focus on section-level assessment
Blocking on style preferences "I'd phrase it differently" isn't a gap Only block on missing information or ambiguity
Expanding scope during review "You should also add X" Only flag what's missing per doc-type requirements
Perfect scores required 3/5 on all criteria = ready to proceed Block only on scores below 3