🇺🇸English

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

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

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

Weekly Installs

102

Repository

jwynia/agent-skills

GitHub Stars

42

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode85

codex83

gemini-cli82

github-copilot77

cursor77

claude-code75