Document Refinement

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:

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