writing-validate

Announce: "Using writing-validate (Phase 3.5) to validate draft sections against PRECIS.md claims."

## Contents

- [The Iron Law of Validation](#the-iron-law-of-validation)
- [Red Flags](#red-flags)
- [Purpose](#purpose)
- [Validation Levels](#validation-levels)
- [The Process](#the-process)
- [Classification](#classification)
- [VALIDATION.md Template](#validationmd-template)
- [Gate](#gate)
- [Validation Facts](#validation-facts)
- [Phase Transition](#phase-transition)

# Claim Validation Against PRECIS.md

Phase between draft and review. Maps every PRECIS.md claim to a draft section and verifies coverage. This is the writing equivalent of DS's DQ validation — without it, review checks quality on prose that may not even address the argument.

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

**NO REVIEW WITHOUT CLAIM VALIDATION. This is not negotiable.**

writing-review MUST NOT start until `.planning/VALIDATION.md` confirms all PRECIS claims are addressed in drafts. Validation is the writing equivalent of test coverage — without it, review is theater.
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
## Red Flags

- About to invoke writing-review without VALIDATION.md → STOP. Review checks quality, not coverage; unvalidated drafts may miss entire claims. Run validation first.
- About to claim "all claims covered" without reading each draft section → STOP. Coverage cannot be verified without reading the prose; check every draft file against every PRECIS claim.
- About to skip validation because the piece is short → STOP. Short pieces still drop claims — fewer sections means each must carry more weight. Validate every piece.
- About to mark a claim COVERED when the draft only mentions it without arguing it → STOP. Mentioning is not arguing; a passing reference is not substantive coverage. Classify as PARTIAL and flag the gap.
</EXTREMELY-IMPORTANT>

## Purpose

This phase sits between writing-draft and writing-review. It runs the **same constraint checks** that review uses — from the writing constraints, the domain skill, and `ai-anti-patterns` — but earlier, so gaps are caught before review begins. Review should NOT be discovering missing claims, broken expansion hierarchy, or AI writing smell.

**The constraint checks ARE the validation.** This phase doesn't invent new checks — it systematically runs the existing ones against every draft section.

## Shared Enforcement

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

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

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

## Constraint Checks to Run

Load and run checks from three sources:

### Source 1: Writing Constraints (atomic files loaded above)

Run these checks from the constraint files:

| Check | From Constraint | What to Verify |
|-------|----------------|----------------|
| **Progressive Expansion** | Expansion Hierarchy | Every PRECIS claim → OUTLINE section → outlines/ file → drafts/ file. No gaps in the chain. |
| **Claim Coverage** | NO DRAFT WITHOUT OUTLINE | Every PRECIS claim has a corresponding draft section that argues it (not just mentions it) |
| **Thesis Threading** | Structural intent | Each draft section connects back to the PRECIS thesis. No tangential sections. |
| **Constraint Loading** | Constraint Loading Protocol | Domain skill + ai-anti-patterns were loaded before drafting (check for violations in prose) |

### Source 2: Domain Skill

Read `.planning/ACTIVE_WORKFLOW.md` for the `style` field, then load the matching domain skill:

| Style | Skill to Load |
|-------|--------------|
| legal | `skills/writing-legal/SKILL.md` |
| econ | `skills/writing-econ/SKILL.md` |
| general | `skills/writing-general/SKILL.md` |

Run domain-specific checks against each draft section (citation format, style compliance, terminology).

### Source 3: AI Anti-Patterns

Invoke `Skill(skill="workflows:ai-anti-patterns")` and check each draft section for AI writing indicators.

## Flowchart — This IS the Spec

```
┌────────────────────────────┐
│  LOAD constraint checks    │
│  (constraints + domain +   │
│   ai-anti-patterns)        │
└────────────┬───────────────┘
             │
             ▼
┌────────────────────────────┐
│  READ .planning/PRECIS.md  │
│  Extract all CLAIM-XX IDs  │
└────────────┬───────────────┘
             │
             ▼
┌────────────────────────────┐
│  READ .planning/OUTLINE.md │
│  Map claims → sections     │
└────────────┬───────────────┘
             │
             ▼
┌────────────────────────────┐
│  For each claim:           │
│  READ drafts/ file         │◄──┐
│  RUN all constraint checks │   │
│  CLASSIFY: COVERED /       │   │
│    PARTIAL / MISSING       │   │
└────────────┬───────────────┘   │
             │                   │
             │ more claims       │
             └───────────────────┘
             │ all claims checked
             ▼
┌────────────────────────────┐
│  Run check-all.sh          │
│  (mechanical constraint    │
│   checks — hard block)     │
└────────────┬───────────────┘
             │
             ▼
┌────────────────────────────┐
│  WRITE .planning/          │
│  VALIDATION.md             │
└────────────┬───────────────┘
             │
        ┌────┴────┐
        │ status? │
        └────┬────┘
     ┌───────┴───────┐
     ▼               ▼
 validated      gaps_found
     │               │
     ▼               ▼
 → review      Present to user
                     │
              ┌──────┴──────┐
              ▼             ▼
           fix (→draft)  accept (→review)
```

### Step 1: Load Constraint Checks

Load all three check sources before reading any drafts. This ensures every section is evaluated against the same criteria.

### Step 2: Extract Claims from PRECIS

Read `.planning/PRECIS.md` and extract every claim:
- Main claims (thesis, sub-theses)
- Counterarguments to be addressed
- Audience-specific framing commitments
- Evidence commitments ("I will show X using Y")

### Step 3: Map Claims to Sections

Read `.planning/OUTLINE.md` and map each claim to sections:
- Which section(s) address this claim?
- Is any claim orphaned (no section maps to it)?
- Is any section present that doesn't serve a claim?

### Step 4: Read and Validate Each Draft

For each claim, read the corresponding draft file and run ALL constraint checks:

| Check | PASS | FAIL |
|-------|------|------|
| Draft exists | File in `drafts/` present | MISSING — no draft for this claim |
| Substantive | >200 words, real argument | Placeholder, stub, or outline-level content |
| Evidence | Citations/sources present per claim | Unsupported assertions |
| Thesis threading | Section argues the PRECIS claim | Tangent — section exists but doesn't address the claim |
| Domain compliance | Passes domain skill checks | Style violations (citation format, terminology, etc.) |
| AI anti-patterns | No AI writing indicators | AI smell detected |

### Step 5: Classify

| Classification | Criteria |
|---------------|----------|
| **COVERED** | All checks pass — section exists, argues the claim, has evidence, passes domain + AI checks |
| **PARTIAL** | Section exists but fails one or more checks (weak evidence, AI smell, domain violation, tangent) |
| **MISSING** | No draft section addresses this claim |

### Step 5b: Run Mechanical Constraint Checks (First Leg)

Run the constraint test suite as the first leg of two-legged verification:

```bash
bash ${CLAUDE_SKILL_DIR}/../../scripts/check-all.sh
```

This runs all constraint check scripts (progressive-expansion, claim-id-traceability, flowchart-authority, no-pause-between-phases). **Any failure is a hard block** — fix before proceeding to Step 6.

The second leg (convention scoring via judgment) happens in Steps 4-5 above and in the writing-review phase.

### Step 6: Flag Gaps to User

<EXTREMELY-IMPORTANT>
**Do NOT auto-draft or auto-fix. Writing requires human judgment on argument direction.**

When gaps are found, present them with the specific check that failed:
- **Fix**: Return to writing-draft to address the gap
- **Accept**: Proceed to writing-review with known gaps

Only the user can decide whether a gap means the claim should be rewritten, dropped, or restructured.
</EXTREMELY-IMPORTANT>

### Step 7: Write VALIDATION.md

Compile all results into `.planning/VALIDATION.md` using the template below.

## VALIDATION.md Template

```markdown
---
status: validated | gaps_found
date: [ISO 8601]
claims_total: N
covered: N
partial: N
missing: N
---
# Claim Validation

## Claims Map
| # | PRECIS Claim | Draft Section | Exists | Substantive | Evidence | Threading | Domain | AI Check | Classification |
|---|-------------|---------------|--------|-------------|----------|-----------|--------|----------|----------------|
| 1 | [from PRECIS] | [drafts/Section.md] | PASS | PASS | PASS | PASS | PASS | PASS | COVERED |
| 2 | [from PRECIS] | [drafts/Section.md] | PASS | PASS | WARN | PASS | PASS | WARN | PARTIAL |
| 3 | [from PRECIS] | — | FAIL | — | — | — | — | — | MISSING |

## Gap Details
[For any PARTIAL or MISSING claim, include:
- Which constraint check failed
- The specific finding
- Suggested remediation (for user decision)]

## Summary
- Claims: N total
- Covered: X
- Partial: Y
- Missing: Z
```

### Status Rules

| Condition | Status |
|-----------|--------|
| All claims COVERED | `validated` |
| Any PARTIAL or MISSING remain | `gaps_found` |

## Gate

`.planning/VALIDATION.md` must exist before proceeding.

- If status is `validated`: proceed to writing-review. **Gate type: `human-verify` — auto-advance.**
- If status is `gaps_found`: present gaps to user before proceeding. **Gate type: `decision` — wait for user.**
  - User decides: **fix** (return to writing-draft) or **accept** (proceed to writing-review with known gaps).

**SUMMARY**: Append phase summary to `.planning/PHASE_SUMMARY.md` (see `constraints/phase-summary-frontmatter.md`):
- phase: validate
- artifacts_produced: [.planning/VALIDATION.md]
- provides: [.planning/VALIDATION.md]
- Include substantive one-liner with claim coverage stats (NOT "Validation complete")

<EXTREMELY-IMPORTANT>
**Do NOT silently proceed past gaps. Present them and wait for user decision.**

Gaps in claim coverage are not cosmetic — they mean the argument has holes. Only the user can decide whether a gap is acceptable or requires returning to the draft phase.
</EXTREMELY-IMPORTANT>

### Validation Facts

- Per-section drafting misses cross-section coverage gaps — a claim that spans two sections can fall between them. Treating per-section checks during drafting as coverage validation leaves exactly the holes this phase exists to catch.
- Review checks prose quality, not claim coverage — a beautifully written section that never addresses its PRECIS claim passes review and fails the paper. Forwarding unvalidated drafts to review sends prose downstream that may not even address the argument the user committed to.

## Visual Output for Decision Checkpoints

When validation finds gaps (status: `gaps_found`), present a claim coverage summary table to help the user decide:

```
## Claim Coverage Summary

| Claim | Section | Status | Issue |
|-------|---------|--------|-------|
| CLAIM-01 | Part I | COVERED | — |
| CLAIM-02 | Part II | PARTIAL | Weak evidence (domain check failed) |
| CLAIM-03 | — | MISSING | No draft section addresses this claim |

Coverage: 1/3 COVERED, 1/3 PARTIAL, 1/3 MISSING
```

This table is generated from VALIDATION.md and presented inline. No separate script needed unless the user asks for the same view 3+ times.

**Observe → record → offer:** record in `.planning/LEARNINGS.md` what the user attends to here (e.g., "user re-checked CLAIM-02 evidence"). Only after the *same* view is requested 3+ times, *offer* (do not impose) to script it — e.g., a coverage heatmap. Text is the default; visual output is never a hard requirement. See `references/constraints/writing-learnings-log.md`.

## Phase Transition

After validation is complete, discover and read the writing-review skill:
Read `${CLAUDE_SKILL_DIR}/../../skills/writing-review/SKILL.md` and follow its instructions.