non-fiction-revision — Claude Code skill: diagnose book revisions

---
name: non-fiction-revision
description: "Diagnose and guide revisions in non-fiction books. Use for non-fiction book revision, when arguments feel weak, evidence is outdated, readers report confusion, thesis is unclear, or book structure has problems. Keywords: non-fiction, revision, thesis, argument, evidence, structure."
license: MIT
metadata:
  author: jwynia
  version: "1.0"
  type: diagnostic
  mode: diagnostic+assistive
  domain: writing
---

# Non-Fiction Revision Diagnostic

## Purpose

Diagnose and guide revisions in non-fiction books (business, self-help, academic, popular science, memoir). Non-fiction operates across multiple levels simultaneously—thesis, structure, evidence, pedagogy. Changes at one level cascade to others. This skill identifies which level needs attention and prevents revision damage.

## Quick Reference

| State | Signal | Core Issue |
|-------|--------|------------|
| NR1 | Thesis feels unclear or weak | Conceptual level problem |
| NR2 | Arguments don't build logically | Structural problem |
| NR3 | Claims lack adequate support | Evidence problem |
| NR4 | Readers report confusion | Pedagogical problem |
| NR5 | Sources outdated or weak | Credibility problem |
| NR6 | Changes causing new problems | Cascade failure |

## The Multi-Level Structure

Every non-fiction book operates simultaneously across:

### Level 1: Conceptual/Thesis
- Core thesis and main arguments
- Foundational assumptions and frameworks
- Philosophical or theoretical positions
- Overall purpose and intended impact

### Level 2: Structural/Argument
- Logical argument sequence and flow
- Chapter organization and dependencies
- Evidence distribution and support patterns
- Reader journey and persuasion architecture

### Level 3: Content/Evidence
- Specific evidence, examples, and data
- Explanations and clarifications
- Voice, tone, and accessibility
- Citations, sources, and credibility markers

### Level 4: Pedagogical/Reader
- Learning progression and scaffolding
- Cognitive load management
- Engagement and retention strategies
- Practical application guidance

## Critical Principle

**Any change at one level potentially affects argument validity and reader comprehension at all other levels.**

Changes propagate:
- **Upward**: New evidence might undermine existing arguments
- **Downward**: Thesis changes require complete restructuring
- **Lateral**: Chapter reordering affects argument development flow

---

## Diagnostic States

### NR1: Thesis/Core Argument Problem

**Symptoms:**
- Thesis feels unclear or unstated
- Main arguments seem weak or unconvincing
- Central claims are frequently disputed
- Book's purpose is hard to articulate
- Conclusion doesn't deliver on promise

**Diagnostic Questions:**
1. Can you state the thesis in one sentence?
2. What are the 3-5 main arguments supporting it?
3. What evidence backs each main argument?
4. Does the conclusion match the opening promise?
5. What changes if the thesis is wrong?

**Interventions:**
1. Map all current evidence supporting the thesis
2. Identify which chapters depend on current thesis formulation
3. Evaluate what new evidence a revised thesis would require
4. Check how thesis change affects the reader promise
5. Assess impact on conclusion and call-to-action

**Cascade Warning:** Thesis changes are the most dangerous—they can invalidate entire chapters. Before changing thesis, map all dependencies.

---

### NR2: Structural/Organization Problem

**Symptoms:**
- Argument flow feels illogical
- Chapters seem disconnected
- Prerequisite knowledge isn't established before use
- Reader must jump back to understand
- Same points repeated without building

**Diagnostic Questions:**
1. What logical prerequisites exist for each chapter?
2. Does knowledge accumulate or repeat?
3. Are there arguments that depend on later chapters?
4. Could chapters be reordered without breaking logic?
5. Do transitions explain the logical connection?

**Interventions:**
1. Create dependency map of chapter relationships
2. Identify logical prerequisites for each major argument
3. Map reader knowledge accumulation through structure
4. Test alternative sequences against comprehension requirements
5. Ensure examples remain contextually appropriate

**Cascade Warning:** Reordering chapters affects every cross-reference and forward/backward reference. Track all internal citations.

---

### NR3: Evidence/Support Problem

**Symptoms:**
- Claims feel unsupported or handwavy
- "Trust me" rather than "here's proof"
- Evidence exists but doesn't connect to claims
- Support for different claims inconsistent in quality
- Key arguments rest on weak foundations

**Diagnostic Questions:**
1. What type of evidence supports each main claim?
2. Are evidence standards consistent throughout?
3. Which claims have the weakest support?
4. Does evidence actually prove what's claimed?
5. Are there counter-arguments addressed?

**Interventions:**
1. Audit evidence quality for each major claim
2. Identify claims needing stronger or different support
3. Evaluate how new evidence affects existing arguments
4. Check consistency in citation style and source quality
5. Assess whether adding evidence changes argument strength

**Cascade Warning:** Adding strong evidence for one claim can accidentally weaken others by raising the evidence standard readers expect.

---

### NR4: Pedagogical/Comprehension Problem

**Symptoms:**
- Readers report confusion
- Complex concepts introduced too fast
- Examples don't illuminate—they confuse
- Practical application unclear
- Target audience can't follow

**Diagnostic Questions:**
1. Where do readers typically get lost?
2. Are technical terms defined before use?
3. Do examples match reader experience?
4. Is cognitive load distributed or front-loaded?
5. Can readers apply what they learn?

**Interventions:**
1. Map cognitive load distribution across chapters
2. Identify concepts needing better scaffolding
3. Evaluate example effectiveness and relevance
4. Check that practical guidance is actionable
5. Assess whether complexity progression is appropriate

**Cascade Warning:** Simplifying can accidentally remove nuance that supports arguments. Balance accessibility with accuracy.

---

### NR5: Credibility/Source Problem

**Symptoms:**
- Sources feel outdated
- Citation patterns inconsistent
- Author authority questioned
- Examples from wrong era
- "According to experts" without naming them

**Diagnostic Questions:**
1. How old are the oldest sources?
2. Are sources appropriate to the field?
3. Is citation style consistent throughout?
4. Do you name experts or speak generally?
5. Are there sources readers would expect that are missing?

**Interventions:**
1. Audit source currency and quality
2. Identify claims needing more recent support
3. Standardize citation style and depth
4. Replace generic expert references with specific citations
5. Add expected canonical sources for the field

**Cascade Warning:** Updating sources can accidentally change what the evidence actually says. Verify new sources support the same conclusions.

---

### NR6: Cascade Failure

**Symptoms:**
- Fixes create new problems
- Changes in one chapter break another
- Evidence update invalidates argument
- Structural change creates new confusion
- Progress feels impossible

**Diagnostic Questions:**
1. What was the original change that started the cascade?
2. What dependencies weren't mapped?
3. Is there a stable rollback point?
4. What's the minimum viable change that tests the idea?
5. Are the problems localized or systemic?

**Interventions:**
1. Stop implementing and assess damage scope
2. Identify last stable state
3. Map actual dependencies (not assumed ones)
4. Consider whether original change is worth the cascade cost
5. If proceeding, create checkpoint system for controlled changes

**Rollback Criteria:**
- Fundamental logical structure breaks down
- Evidence requirements become impossible to meet
- Changes create more credibility problems than they solve
- Reader comprehension significantly compromised

---

## Pre-Change Protocol

Before implementing ANY revision:

### 1. Identify Change Level
- [ ] Conceptual (thesis, main arguments, frameworks)
- [ ] Structural (chapter sequence, argument flow, organization)
- [ ] Content (evidence, examples, explanations)
- [ ] Pedagogical (presentation, scaffolding, application)

### 2. Map Dependencies
For each change, document:
- **Prerequisites**: What must remain intact for this change to work?
- **Dependents**: What later claims rely on this element?
- **Evidence**: What support becomes necessary or obsolete?
- **Comprehension**: How does this affect the learning journey?

### 3. Assess Cascade Risk
- [ ] Low: Change is isolated, no dependencies
- [ ] Medium: 2-3 other elements need updating
- [ ] High: Affects multiple chapters or core arguments
- [ ] Critical: Threatens book's foundational structure

### 4. Define Success Criteria
Before changing, know how you'll evaluate:
- Logical coherence: Does the argument still flow?
- Evidence adequacy: Are claims still supported?
- Reader comprehension: Can they still follow?
- Credibility: Does authority remain intact?

---

## Change Record Template

```markdown
# Revision: [Brief Description]

## Change Type
- [ ] Conceptual  - [ ] Structural  - [ ] Content  - [ ] Pedagogical

## Rationale
[Why this change improves the book]

## Dependency Analysis
- Prerequisites affected:
- Dependent elements:
- Evidence changes needed:
- Comprehension impacts:

## Cascade Risk Level
- [ ] Low  - [ ] Medium  - [ ] High  - [ ] Critical

## Success Criteria
- Logical coherence check:
- Evidence adequacy standard:
- Reader comprehension benchmark:

## Implementation Status
- [ ] Initial change complete
- [ ] Dependencies updated
- [ ] Cross-references revised
- [ ] Cascade effects resolved

## Outcome
[Complete after implementation]
```

---

## Non-Fiction Type Variations

### Academic/Research
- Methodology consistency paramount
- Literature review must stay current
- Anticipate peer review critique
- Contribution clarity essential

### Business/Self-Help
- Practical applicability above all
- Examples must feel current
- Implementation guidance required
- ROI/benefit must be clear

### Popular Science
- Accessibility without dumbing down
- Research currency matters
- Analogies must actually illuminate
- Balance education with engagement

### Memoir/Personal Narrative
- Factual accuracy + compelling narrative
- Emotional authenticity preserved
- Privacy boundaries respected
- Personal connects to universal

---

## Anti-Patterns

### The Endless Revision Spiral
Fixing one thing breaks another, which breaks another. The book never reaches stable state.

**Fix:** Define minimum viable change, implement, stabilize before next change.

### The Evidence Addiction
Adding more and more sources without improving argument quality. Quantity masking weakness.

**Fix:** Better evidence, not more evidence. One strong study beats ten weak ones.

### The Clarity Trap
Simplifying until accuracy suffers. Readers can follow but learn the wrong thing.

**Fix:** Scaffold complexity rather than remove it. Build up to nuance.

### The Thesis Drift
Small changes accumulate until the book argues something different than intended.

**Fix:** Regularly check: does the conclusion still match the introduction's promise?

---

## Integration Points

**Inbound:**
- From `research`: When gathering new evidence
- From `revision`: For overall revision strategy

**Outbound:**
- To `prose-style`: After structural issues resolved
- To `fact-check`: For evidence verification

**Complementary:**
- `research`: For evidence gathering
- `revision`: For fiction revision (parallel skill)