writing-precis-reviewer

What this skill does

# Precis Document Reviewer

**Purpose:** Catch precis gaps BEFORE they survive into outlining and drafting. A vague thesis that survives into outlining means every section wanders, every draft rewrites, and the document never coheres.

## Shared Enforcement

Auto-load all constraints matching `applies-to: writing-precis-reviewer`:

!`uv run python3 ${CLAUDE_SKILL_DIR}/../../scripts/load-constraints.py writing-precis-reviewer`

**You MUST have these constraints loaded before proceeding. No claiming you "remember" them.**

## When to Dispatch

After writing-setup writes `.planning/PRECIS.md` and before `.planning/OUTLINE.md` creation begins.

```
Step 2: Interview → PRECIS.md written
  → [THIS SKILL] Dispatch precis reviewer subagent
  → Issues found? Fix PRECIS.md → re-dispatch reviewer
  → Approved? → Step 3: Create OUTLINE.md
```

<EXTREMELY-IMPORTANT>
## The Iron Law of Precis Review

**NO OUTLINE WITHOUT REVIEWED PRECIS. This is not negotiable.**

A bad precis that survives into outlining means:
- Sections that don't advance a clear thesis
- Claims that overlap or repeat each other
- Counterarguments that are strawmen, easily dismissed
- Scope that balloons because boundaries were never set
- An audience nobody specific, so the prose speaks to nobody

**Catching a precis gap NOW costs 1 minute. Catching it during drafting costs a full rewrite.**
</EXTREMELY-IMPORTANT>

### Rationalization Table - STOP If You Think:

| Excuse | Reality | Do Instead |
|--------|---------|------------|
| "The precis looks complete to me" | Self-review is rubber-stamping | Dispatch independent reviewer |
| "User already confirmed the thesis" | User confirms intent, not precision | Reviewer checks what user might miss |
| "This will slow us down" | 30-second review saves hours of rewriting | Dispatch the reviewer |
| "It's a short piece, no review needed" | Short pieces with vague theses are the worst — nowhere to hide | Review it anyway |
| "I'll refine the thesis during drafting" | You won't. You'll write around the vagueness and produce mush | Review BEFORE outlining |

## Dispatch Template

Use this Task invocation to dispatch the precis reviewer:

```
Agent(
  subagent_type="general-purpose",
  description="Review PRECIS document",
  prompt="""
You are a precis document reviewer. Verify this precis is sharp, complete, and ready to guide outlining and drafting.

**Tool restrictions:** You may ONLY use Read, Grep, and Glob tools. Do NOT use Write, Edit, or Bash. Your job is to evaluate, not fix.

**Precis to review:** .planning/PRECIS.md

Read the precis file, then evaluate against ALL categories below.

## What to Check

| Category | What to Look For |
|----------|------------------|
| Thesis Specificity | Is it a real claim? Or vague like "X is important" / "X matters" / "X is complex"? A thesis must be arguable — someone reasonable could disagree. |
| Claim Distinctness | Are claims genuinely different? Or do 2+ claims say the same thing in different words? Each claim must advance a separate leg of the argument. |
| Counterargument Substance | Are counterarguments steel-manned? Or strawmen that no serious reader would hold? Each objection must be one a smart opponent would actually raise. |
| Scope Clarity | Are IN and OUT lists specific? Or vague ("we cover the main issues")? Scope must draw clear boundaries. |
| Audience Specificity | Is the audience a real group? Or "anyone interested"? The audience must be specific enough to guide tone, assumed knowledge, and purpose. |
| Source Support | Do the listed sources actually support the claims? Are there claims without any source backing? |
| Completeness | Any TODOs, TBDs, placeholders, or empty sections? |
| Internal Consistency | Do claims contradict each other? Does scope conflict with thesis? |

## CRITICAL — Look Especially Hard For:

- Thesis that is a topic statement, not a claim ("This paper examines..." is NOT a thesis)
- Claims that are really the same point rephrased
- Counterarguments that no informed person would actually make
- Scope IN that is so broad the document would be a book
- Scope OUT that is empty or vague
- Audience described as "general readers" or "anyone interested"
- Any TODO or TBD markers
- Missing sections

## Output Format

## Precis Review

**Status:** APPROVED | ISSUES_FOUND

**Issues (if any):**
- [Section]: [specific issue] - [why it matters for outlining]

**Recommendations (advisory — don't block approval):**
- [suggestions for improvement that aren't blocking]
""")
```

## Handling Reviewer Output

### If APPROVED

Write the gate artifact so downstream phases can verify the gate ran:

```
Write(".planning/PRECIS_REVIEWED.md", """---
status: APPROVED
date: [ISO 8601]
reviewer: precis-reviewer-subagent
---
# Precis Review: APPROVED

[Include reviewer's approval summary here]
""")
```

Proceed immediately to Step 3 (create OUTLINE.md) in writing-setup.

### If ISSUES_FOUND

Staged improvement criteria per iteration:

| Iteration | Focus | Expected Improvement |
|-----------|-------|---------------------|
| 1 | Fix blocking issues (vague thesis, missing claims) | Thesis becomes arguable, claims become distinct |
| 2 | Fix secondary issues (weak counterarguments, vague scope) | Counterarguments steel-manned, scope boundaries clear |
| 3 | Fix refinement issues (audience specificity, source mapping) | All sections complete and internally consistent |
| 4-5 | Polish (if still needed) | Edge cases, consistency between sections |

Process:
1. Fix the specific issues in `.planning/PRECIS.md`
2. Re-dispatch the reviewer (same template)
3. Repeat until APPROVED or max 5 iterations

### If 5 Iterations Without Approval
Escalate to user:
```
"Precis reviewer has flagged issues 5 times. Remaining issues:
[list issues]
Should I: (A) Fix these, (B) Proceed with known gaps, (C) Rethink the precis?"
```

## Drive-Aligned Framing

**Proceeding to outlining with a vague precis is NOT HELPFUL — the user builds an entire document on a foundation that collapses under review.**

You know the thesis is fuzzy. You know the claims overlap. You know the counterarguments are weak. Outlining built on a bad precis produces a structure that doesn't cohere. Drafting built on a bad structure produces prose that wanders. The reader will notice even if you don't.

**Fix the precis now. It costs minutes, not hours.**

## Gate Function

```
1. IDENTIFY: `.planning/PRECIS.md` exists with content
2. DISPATCH: Send to reviewer subagent
3. READ: Reviewer returns APPROVED or ISSUES_FOUND
4. VERIFY: If ISSUES_FOUND, fix and re-dispatch (max 5)
5. CLAIM: Only proceed to OUTLINE.md creation when APPROVED
```