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
1. [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 |