writing-revise

What this skill does

# Writing Revise

The revision loop for writing projects. Consumes `.planning/REVIEW.md` (produced by `/writing-review`) and applies targeted fixes, then completes when the **blocking** issues (critical + major) are resolved — residual minor polish notes are advisory and the writer accepts them at the iteration cap (they do not block completion).

## Shared Enforcement

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

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

**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 revising any prose.

## 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

## Revise Flowchart (This IS the Spec)

```
START
  │
  ├─ Step 1: Load context (ACTIVE_WORKFLOW, PRECIS, OUTLINE, drafts)
  │
  ├─ Step 2: REVIEW.md exists?
  │  ├─ NO → REFUSE. Suggest /writing-review. EXIT.
  │  └─ YES → Parse issues (critical → major → minor)
  │
  ├─ Step 3: Load constraint layers
  │  ├─ Domain skill (legal/econ/general)
  │  └─ ai-anti-patterns (universal)
  │
  ├─ Step 4: Fix issues in priority order
  │  ├─ 4a: Critical issues (argument-breaking)
  │  ├─ 4b: Major issues (transitions, repetition, late introductions)
  │  └─ 4c: Minor issues (polish)
  │
  ├─ Step 5: Formatting check
  │
  └─ Step 6: Check iteration state (.planning/REVIEW_STATE.md)
     │
     ├─ result.substratePass (0 critical, 0 major) → COMPLETE
     │  └─ Residual MINORS are advisory polish — fix the cheap ones, then Archive → summary → EXIT.
     │     Do NOT loop to drive minors to literal 0 (the prose-reviewer regenerates subjective minors — treadmill).
     │
     ├─ iteration < 3 AND BLOCKING issues remain (critical/major) → CONTINUE
     │  └─ Increment iteration → fix the criticals/majors → Re-invoke /writing-review → Loop
     │
     └─ ESCALATE (decision: user) when EITHER
        ├─ iteration >= 3 AND blocking issues still remain, OR
        └─ substrate clean but minors remain → present them as "accept as-is OR one more polish pass?"
```

If text and flowchart disagree, the flowchart wins.

<EXTREMELY-IMPORTANT>
## IRON LAW: Critique Over Comfort

**If the writing has problems, SAY SO. Being nice is NOT HELPFUL — the user publishes weak prose that gets rejected.**

### Critique Facts

- "Overall flows well" hides section-level problems — each section must be checked against PRECIS claims, and a structural match to the outline says nothing about content quality.
- A checkmark without evidence is an unverified claim presented as verification: reporting "all checks pass" without running every check means the user publishes with undetected problems.
</EXTREMELY-IMPORTANT>

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

**NO "FIXED" CLAIMS WITHOUT FRESH RE-REVIEW. This is not negotiable.**

After applying fixes from REVIEW.md, you MUST:
1. Re-invoke `/writing-review` to regenerate REVIEW.md with fresh diagnostics
2. Verify issues are actually resolved (not assumed)
3. Check for new issues introduced by edits (regressions, new problems)
4. Only THEN claim fixes are complete

"I fixed it" without re-reviewing is NOT HELPFUL — unverified fixes let broken prose reach the user.

### The Audit-Fix Loop (Max 3 Iterations)

```
Iteration 1: Review → REVIEW.md → Revise → Re-Review
              ↓
Iteration 2: Re-Review → REVIEW.md → Revise → Re-Review
              ↓
Iteration 3: Re-Review → REVIEW.md → Revise → Re-Review
              ↓
         Still issues? → ESCALATE to user
         All clean? → COMPLETE
```

**Track iterations in `.planning/REVIEW_STATE.md`:**

```yaml
---
iteration: 1
max_iterations: 3
last_review_date: 2026-03-09
issues_found_count: 5
---
```

**Exit criteria** (gate on the SUBSTRATE — critical + major — not on driving subjective minors to zero):
- **COMPLETE**: `result.substratePass` (0 critical, 0 major) in REVIEW.md. Apply any cheap residual minors, then archive. **Gate type: `human-verify` — auto-advance to archive.** Residual minor polish notes do NOT block completion.
- **CONTINUE**: iteration < 3 AND **blocking** issues remain (critical/major) → fix them, re-invoke /writing-review. **Gate type: `human-verify` — auto-advance.**
- **ESCALATE** `[decision — wait for user]`: iteration >= 3 AND blocking issues still remain (present options); OR substrate is clean but minor polish notes remain — present "accept as-is OR one more polish pass?" The writer decides; do NOT auto-loop on minors.

**Note:** the review still FLAGS every severity (including minors — see the rationalization table; flagging is the reviewer's job). What changed is the loop *exit*: only critical+major **block**; minors are advisory. This is the writing analog of the wc substrate gate — drive the real, convergent findings to zero; don't treadmill on an LLM panel's inexhaustible subjective minors.

**Before claiming "all fixed", check iteration count:**
1. READ `.planning/REVIEW_STATE.md` (create if missing with iteration: 1)
2. If iteration >= 3 and issues remain: ESCALATE (don't say "run review again")
3. If iteration < 3 and issues remain: INCREMENT iteration, re-invoke /writing-review
4. If no issues: COMPLETE

**Claiming "all issues resolved" without re-reviewing is NOT HELPFUL — the user trusts a false "all clear" and publishes with remaining problems.**

### Re-Review Facts

- Revision introduces new errors — fixes cascade into adjacent text, and your eyes glaze over your own edits, so spot-checks and "looks clean" miss what a fresh `/writing-review` catches. Shipping an unverified revised draft asserts a verification that never happened; an unverified claim presented as done is dishonest.
- The rejection-and-rewrite cost far exceeds the re-review cost (a 15-minute re-review vs hours of rework after reviewers reject). Skipping re-review to finish faster is counterproductive on its own terms.
- Hitting the iteration cap with issues remaining means ESCALATE, not approve.
</EXTREMELY-IMPORTANT>

### Revision Facts

- Rewriting an entire section instead of applying the minimum targeted fix introduces new issues and loses the author's voice — destructive ambition, not improvement.
- A fix can break adjacent text; the paragraph before and after the edit must be re-read, and the edited passage itself re-read before the issue is marked fixed — marking it fixed unread is a false completion claim.
- Combining multiple unrelated fixes in one pass makes per-fix verification impossible; one issue at a time.
- "Remembering" the domain rules is guessing — Read() the domain skill every time.

## When to Use

- After `/writing-review` produces `.planning/REVIEW.md`
- When hook suggests it (after ~10 edits)
- Before finishing a writing project

## Prerequisites Gate

Before running edits, verify the workflow is ready:

1. **IDENTIFY**: `.planning/ACTIVE_WORKFLOW.md`, `.planning/PRECIS.md`, `.planning/OUTLINE.md`, and at least one file in `drafts/` must exist
2. **RUN**: Check file existence
3. **READ**: Confirm ACTIVE_WORKFLOW shows `workflow: writing`
4. **VERIFY**: All required files present and draft content exists
5. **CHECK FOR REVIEW.MD**: Look for `.planning/REVIEW.md`

If any file is missing, report and suggest the appropriate phase:
- No PRECIS.md -> `/writing` (start from brainstorm)
- No OUTLINE.md -> writing-setup needed
- No drafts -> writing-draft needed
- **No REVIEW.md** -> suggest `/writing-review` first (see backward-compatibility below)

## Process

### Step 1: Load Context

```
Rea