Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
jwynia avatar

Non Fiction Revision

  • 298 installs
  • 133 repo stars
  • Updated February 24, 2026
  • jwynia/agent-skills

non-fiction-revision is a Claude Code skill at version 1.0 that diagnoses and guides revisions in non-fiction books, articles, essays, reports, and documentation for clarity, structure, tone, and factual flow.

About

non-fiction-revision is a diagnostic writing skill (version 1.0, MIT license) for improving non-fiction drafts without changing core arguments. Author jwynia built it for business, self-help, academic, popular science, memoir, and technical documentation where thesis, structure, evidence, and reader confusion must be addressed simultaneously. Developers writing long-form docs, internal reports, or published articles invoke it when arguments feel weak, evidence is outdated, readers report confusion, or book-level structure has problems. The skill operates in diagnostic plus assistive mode, separating structural issues from line-level clarity so revisions target the right layer of the manuscript or document.

  • Structural edits
  • Clarity passes
  • Tone alignment
  • Argument flow
  • Draft polishing

Non Fiction Revision by the numbers

  • 298 all-time installs (skills.sh)
  • +4 installs in the week ending Aug 2, 2026 (Skillselion tracking)
  • Ranked #189 of 688 Office & Documents skills by installs in the Skillselion catalog
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/jwynia/agent-skills --skill non-fiction-revision

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs298
repo stars133
Last updatedFebruary 24, 2026
Repositoryjwynia/agent-skills

How do you revise non-fiction structure and arguments?

Revise non-fiction drafts for clarity, structure, tone, and factual flow—improving articles, essays, reports, and documentation without changing core arguments.

Who is it for?

Developers and technical authors revising long-form documentation, reports, or books when structure, evidence, or thesis clarity blocks readers.

Skip if: Fiction manuscripts, marketing copy needing brand voice only, or code refactoring tasks unrelated to written argument structure.

When should I use this skill?

A developer revises non-fiction books, articles, reports, or documentation with weak arguments, outdated evidence, or structural confusion.

What you get

Revision plan addressing thesis, structure, evidence, tone, and clarity without altering core arguments.

By the numbers

  • Skill version 1.0
  • Diagnostic and assistive revision modes

Files

SKILL.mdMarkdownGitHub ↗

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

StateSignalCore Issue
NR1Thesis feels unclear or weakConceptual level problem
NR2Arguments don't build logicallyStructural problem
NR3Claims lack adequate supportEvidence problem
NR4Readers report confusionPedagogical problem
NR5Sources outdated or weakCredibility problem
NR6Changes causing new problemsCascade 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

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

Related skills

How it compares

Use non-fiction-revision for structural non-fiction editing rather than code review or API documentation generators.

FAQ

What genres does non-fiction-revision cover?

non-fiction-revision covers business, self-help, academic, popular science, memoir, and technical documentation. Version 1.0 uses diagnostic and assistive modes to fix thesis, structure, evidence, and tone without changing core arguments.

Is non-fiction-revision for fiction or marketing copy?

non-fiction-revision targets non-fiction books, articles, reports, and documentation with structural or evidentiary problems. Fiction manuscripts and short brand copy are outside its diagnostic scope.

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.