writing-review

# Writing Review

Hierarchical bottom-up review that diagnoses structural problems across a drafted document. Produces `.planning/REVIEW.md` — a structured diagnosis consumed by `/writing-revise`.

**Prerequisites:** PRECIS.md, OUTLINE.md, ACTIVE_WORKFLOW.md, and draft files in `drafts/` must exist.

## Shared Enforcement

Auto-load all constraints matching `applies-to: writing-review`:

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

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

**CRITICAL:** The `constraint-loading-protocol` above requires loading the domain skill (writing-legal/econ/general) and ai-anti-patterns before reviewing any prose — see Steps 2 and 2b below.

## Session Resume Detection

Before starting, check for an existing handoff:

1. Check if `.planning/HANDOFF.md` exists
2. **If found:** Read it and present to user:
   - Show the phase, section in progress, and Next Action
   - Ask: "Resume from handoff, or start fresh?"
   - If resume: skip to the recorded phase
   - If fresh: proceed with mode detection
3. **If not found:** Proceed normally

<EXTREMELY-IMPORTANT>
## The Iron Law of Reading

**NO REVIEW WITHOUT READING. Every claim in REVIEW.md must cite specific text from the draft. This is not negotiable.**

If you find yourself writing a review comment without quoting the draft text it refers to:
1. STOP immediately
2. DELETE the comment
3. Go back and READ the draft passage
4. QUOTE the specific text, THEN write your diagnosis

A review that says "transitions could be improved" without citing the actual transition text is useless. A review that says "Section III ends with 'The market has spoken.' and Section IV opens with 'Turning to regulatory concerns...' — no bridge connects the market conclusion to the regulatory pivot" is actionable.

**The writing-review workflow now enforces this structurally:** every reviewer it dispatches must attach a verbatim `quote` + `file:line` to each issue, so a review without reading cannot be produced.
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
## The Iron Law of Evidence

**NO PASSES WITHOUT EVIDENCE. Checking a box requires quoting the text that satisfies it. This is not negotiable.**

If you find yourself marking something as "OK" or "no issues found":
1. STOP
2. Quote the specific text that proves it passes
3. Only THEN mark it as passing

"Transitions are smooth" is a lie unless you can quote adjacent section boundaries and explain why they connect. "No repetition found" is a lie unless you compared the argument summaries across all sections.

**Reporting "all checks pass" without evidence for every checkmark is NOT HELPFUL — undetected issues survive into the published document.**

**The writing-review workflow now enforces this structurally:** its reviewers return quoted evidence per finding, and a mechanical Verify stage confirms each quote resolves to the draft — fabricated or misattributed quotes are dropped before they reach REVIEW.md. Evidence-grounding is no longer honor-system; it is built into the workflow.
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
## Iron Law: Structural Independence

**REVIEW MUST BE PERFORMED BY FRESH SUBAGENTS THAT DO NOT SHARE CONTEXT WITH THE DRAFTER. This is not negotiable.**

The drafter's context contains intent, shortcuts, and assumptions that bias review. A fresh reader catches what the author cannot see. Reviewing your own draft in the same context is rubber-stamping, not reviewing.

**The writing-review workflow now guarantees this by construction:** it always dispatches fresh reviewer subagents (structure, prose, fidelity) that read each draft cold. You do not — and must not — review draft prose in the main conversation yourself.
</EXTREMELY-IMPORTANT>

## Delete & Restart

If you catch yourself in any of these violations, the review output is contaminated. Delete it and start over:

| Violation | Why Contaminated | Action |
|---|---|---|
| Reviewed a section without reading its draft file | You fabricated a review from outline knowledge | DELETE REVIEW.md. Read every draft. Start Level 1 over. |
| Reviewed your own draft in the same context (no fresh subagent) | Self-review is rubber-stamping — you share the drafter's biases | DELETE the section review. Spawn a fresh subagent. Re-review. |
| Wrote REVIEW.md without completing all 3 levels | Partial review misses cross-section issues | DELETE REVIEW.md. Complete all levels. Regenerate. |

**Partial fixes to contaminated reviews create worse outcomes than restarting.** A review built on fabricated evidence will misdirect writing-revise into "fixing" non-problems while real issues persist.

## Red Flags

- About to write "no issues" for a section without quoting evidence → STOP. That is rubber-stamping; quote the text that proves it passes.
- About to skip boundary analysis between sections → STOP. Transition problems are the #1 reason this skill exists; compare every adjacent boundary pair.
- About to review only the section that looks weakest → STOP. Bias blinds the review elsewhere; review ALL sections with equal rigor.
- About to write a vague suggestion ("improve flow") → STOP. Unactionable for writing-revise; cite specific text, diagnose the specific problem, suggest the specific fix.
- About to finish review of a multi-section document in under 5 minutes → STOP. That is skimming; go back and read properly.
- About to copy outline structure as if it were review → STOP. Outline compliance is not quality review; check content quality, not just structural match.

---

## Process

### Step 1: Load Context

```
Read(".planning/ACTIVE_WORKFLOW.md")
Read(".planning/PRECIS.md")
Read(".planning/OUTLINE.md")
Glob("outlines/*.md")
Glob("drafts/*.md")
```

Verify: every section in OUTLINE.md has both an outline file and a draft file. If any draft is missing, STOP and report — you cannot review what doesn't exist.

### Step 2: Load Domain Skill

Based on `style` in ACTIVE_WORKFLOW.md:

| Style | Action |
|---|---|
| legal | `Read("${CLAUDE_SKILL_DIR}/../../skills/writing-legal/SKILL.md")` |
| econ | `Read("${CLAUDE_SKILL_DIR}/../../skills/writing-econ/SKILL.md")` |
| general | `Read("${CLAUDE_SKILL_DIR}/../../skills/writing-general/SKILL.md")` |

The domain skill contains style rules that inform your review criteria. You MUST read it before reviewing.

### Step 2b: Load Universal Constraints

```
Skill(skill="workflows:ai-anti-patterns")
```

**You MUST load ai-anti-patterns before reviewing.** Domain skills inform domain-specific review criteria; ai-anti-patterns catches AI writing smell (hedging, filler, false balance) that domain skills don't cover. Both layers are required — see `constraints/constraint-loading-protocol.md`.

### Step 2c: Run Constraint Check Scripts (Hard Gate)

Before any review work, run all mechanical constraint checks:

```bash
uv run python3 ${CLAUDE_SKILL_DIR}/../../references/constraints/check-all.py [project-root]
```

This auto-discovers and runs all `writing-*.py` constraint scripts (bold-lead, topic sentences, source-anchored citations, etc.). If any check fails, report violations and fix them before proceeding to Level 1.

Constraint checks are **Leg 1** of two-leg verification. **Leg 2** (convention scoring via reviewer subagents) happens in Level 1.

---

## Run the writing-review workflow

The review is **always parallel** and is owned by an ultracode workflow script — you do NOT choose a strategy and you do NOT dispatch reviewers yourself. The workflow runs all three levels (per-section structure + prose + fidelity fan-out, mechanical quote-verification, transition analysis, and whole-document checks) in the background and returns structured findings.

**1. Resolve the cached workflow path:**

```bash
WF=$(command ls -d ~/.claude/plugins/cache/*/workflows/*/workflows/writing-review.js 2>/dev/null | sort -V | tail -1)
# Fall back to the in-repo path when running from the plugin source (cache glob empty):
[ -z "$WF" ] && WF="${CLAUDE_SKILL_DIR}/../../workflows/writing-review.js"
```

**2. Invoke the workflow:**

```
Workflow({
  scriptPath: "<WF>",
  args: {
    projectDir: "<abs project dir>",          // holds .planning/, outlines/, drafts/, references/sources.bib
    pluginRoot: "${CLAUDE_SKILL_DIR}/../.."    // resolves domain skill + bridge_repetition_check.py
  }
})
```

The workflow runs Levels 1-3 and returns:
- `overallPass` / `substratePass` (== `critical===0 && major===0` — the blocking gate; **minors are advisory, not blocking**), `verdict` (CLEAN | CLEAN (advisory polish notes) | ISSUES FOUND)
- `summary` (`{ critical, major, minor, total, blocking, advisoryMinors }`)
- `style`
- `sections[]` — per-section `issues` (each tagged `source: structure | prose | fidelity`), `boundary`, `argumentSummary`, `unreliable`
- `transitions[]` — adjacent boundary verdicts
- `documentLevel` — `{ conceptOrderIssues, repetition, thesisIssues, completeness }`
- `unreliableSections` — sections where a reviewer returned nothing
- `sectionsThatFlagged` — sections to pass as `onlyChecks` on a re-review

**Re-review (when `/writing-revise` re-invokes after edits):** pass only the changed sections so the workflow re-reviews them and carries the rest forward:

```
Workflow({
  scriptPath: "<WF>",
  args: {
    projectDir: "<abs project dir>",
    pluginRoot: "${CLAUDE_SKILL_DIR}/../..",
    onlyChecks: [<changed section names>],     // re-review only these
    priorReviews: <previous result.sections>   // carry the rest forward
  }
})
```

> **Note:** `references/agent-team-workflow.md` and `references/reviewer-agent-prompt.md` are SUPERSEDED by `workflows/writing-review.js` — the script replaces the hand-rolled agent-team orchestration, and `references/sequential-checklist.md`'s content now lives in the workflow's structure-reviewer prompt. Those reference files are retained for provenance only; do not follow them to dispatch reviewers.

---

## Render REVIEW.md

Write `.planning/REVIEW.md` from `result.*` using the template in `references/review-template.md`:

- **Summary counts** ← `result.summary` (`critical`, `major`, `minor`, `total`)
- **Verdict** ← `result.verdict`
- **Document-Level Issues** ← `result.documentLevel` (`conceptOrderIssues`, `repetition`, `thesisIssues`, `completeness`)
- **Transition Issues** ← `result.transitions` (one block per non-SMOOTH boundary; quote `closes`/`opens`)
- **Section-Level Issues** ← `result.sections` — list each section's `issues` sorted by severity; each issue carries `source` (structure / prose / fidelity), `location` (file:line), `quote`, `detail`, and `fix`
- **Boundary Summaries** ← `result.sections[].boundary`

If `result.unreliableSections` is non-empty, mark those sections **UNRELIABLE** in REVIEW.md (a reviewer returned nothing for them) — do NOT fabricate findings or a clean verdict for them.

> The workflow's reviewers already cite verbatim quotes with file:line and a mechanical Verify stage drops any quote that does not resolve to the draft, so the findings you render are evidence-grounded by construction. Render them faithfully — do not add, invent, or soften.

> **Full REVIEW.md template:** See `references/review-template.md`

---

## Gate: Exit Review

Before declaring review complete:

1. **IDENTIFY**: `.planning/REVIEW.md` exists
2. **RUN**: Read REVIEW.md, verify every section from OUTLINE.md has a review entry
3. **READ**: Confirm every issue has severity + location + quoted evidence + suggestion
4. **VERIFY**: All three levels completed (section, transition, document)
5. **CLAIM**: Only if steps 1-4 pass, announce review complete. **Gate type: `human-verify` — auto-advance to /writing-revise.**
6. **SUMMARY**: Append phase summary to `.planning/PHASE_SUMMARY.md` (see `constraints/phase-summary-frontmatter.md`):
   - phase: review
   - artifacts_produced: [.planning/REVIEW.md]
   - provides: [.planning/REVIEW.md]
   - Include substantive one-liner with issue counts by severity (NOT "Review complete")

**If any section is missing from REVIEW.md, the review is incomplete. Go back.**

---

## Step 5: Update Workflow State

Update `.planning/ACTIVE_WORKFLOW.md`:

```yaml
phase: review
review_completed: true
issues_found: [total count]
critical_issues: [critical count]
```

## Step 6: Announce and Suggest Next Step

```
Review complete. Results written to .planning/REVIEW.md.

Found [N] issues ([critical] critical, [major] major, [minor] minor).

[If issues found]:
Run /writing-revise to fix issues from the review.

[If clean]:
No issues found. Run /writing-revise to complete the workflow.
```

---

### Review Exit Facts

- Subagents confabulate verbatim quotes — Round 1 proved this. Compiling subagent output without spot-checking 3+ quotes per agent against the source launders fabricated evidence into REVIEW.md.
- The Topic Sentence Inventory IS the paragraph-level review. A review without it covers headings, not prose — and presenting it as a prose review is dishonest about what was checked.
- A long single-file document needs MORE structure, not less: build the Section Map and assign line ranges. Skipping it because the file is "too long to split" guarantees skimmed, shallow findings.

## Confidence Scoring

Tag each reported issue with a confidence level:

| Level | Threshold | Placement |
|---|---|---|
| **HIGH** | >= 90% certain this is a real problem | Main report — fix required |
| **MEDIUM** | >= 80% certain | Main report — fix recommended |
| **LOW** | < 80% certain | Separate "Possible Issues" section at end of REVIEW.md |

Only issues at HIGH or MEDIUM confidence appear in the main report. LOW confidence issues go in a separate **"Possible Issues"** section so they are visible but do not clutter actionable fixes. This prevents false positives from overwhelming `/writing-revise`.

## Red Flags

- About to write REVIEW.md without reading all drafts → STOP. That is fabricating a review; read every draft file first.
- About to skip Level 2 (transitions) → STOP. Transitions are the primary reason this skill exists; always run all three levels.
- About to record fewer than 3 issues on a multi-section document → STOP. Statistically implausible; review more carefully.
- About to use vague language ("could be improved") → STOP. Unactionable for writing-revise; quote text, diagnose specifically, suggest specifically.
- About to finish in one pass without re-reading → STOP. Different issue types need different passes; run each level as a separate pass.
- About to compile subagent output without spot-checking quotes → STOP. That launders potentially fabricated evidence; run the Verification Gate first.
- About to assign an agent a full document without line ranges → STOP. Unscoped agents skim; build the Section Map and assign start/end lines.
- About to accept a subagent review missing the Topic Sentence Inventory → STOP. The inventory IS the paragraph-level review; reject and request completion.

---

## Next Phase

After review is complete:

Invoke `/writing-revise` to fix issues identified in `.planning/REVIEW.md`.