SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillswriting-validate

writing-validate

Writing & research

View repository

Updated 10-15 21:37

About this skill

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

Contents

  • The Iron Law of Validation
  • Red Flags
  • Purpose
  • Validation Levels
  • The Process
  • Classification
  • VALIDATION.md Template
  • Gate
  • Validation Facts
  • 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.

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.

  • 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.

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 ${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

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.

Step 7: Write VALIDATION.md

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

VALIDATION.md Template

---
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")

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.

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.