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 |