dmccreary/claude-skills/chapter-content-generator

Chapter Content Generator

Version: 1.11

Version 1.11 Features:

• Precise, objective-first MicroSim specifications - Every specification block now states what the learner must learn and prove, and the complete content the sim needs, instead of how to build the sim. New structured fields (Bloom Level, Bloom Verb, Learning Objective, Evidence of Mastery, Misconceptions, Instructional Rationale, Content, Provenance, Rules, Learner Activity, Feedback, Starting State, Chapter Anchors) and a self-check are defined in the new references/microsim-specification-rules.md. Layout, pixel sizes, colors, control placement and library calls are left to the microsim-generator. The rules come from a 112-MicroSim batch run in which agents reported 450 missing specification details and 49% of the sims had to depart from their spec.
• Bloom fields the batch tools can parse - **Bloom Level:** and **Bloom Verb:** are separate header lines. The previous inline form, Learning objective (Bloom level: X; verb: Y):, could not be parsed, and the tools labeled 109 of 112 sims "Create".
• Fixed impossible or conflicting instructions in `content-element-types.md` - the Bloom list named only four of the six levels, Mermaid edges were required to be clickable (Mermaid cannot do this), a graph example asked for mouse-wheel zoom inside an embedded page, examples hard-coded 500 px iframe placeholders, and an unclosed code block swallowed the MicroSim example.

Version 1.10 Features:

• Mascot placement rules single-sourced - Step 2.4 principle 4 no longer carries its own copy of the Chapter 1 self-introduction pattern or the mascot frequency numbers. Both now live in the canonical $BK_HOME/skills/book-installer/references/mascot-placement-rules.md, which every skill in the library references instead of restating. This ends the drift that had left conflicting per-chapter counts in two different placement tables.
• Version tracked in frontmatter - as metadata.ibook.version, under metadata: rather than a bare version: key, which strict packaging validation would reject.

Version 1.09 Features:

• BREAKING: CIS-driven elaboration budget - Per-concept word count and non-text-element requirements are no longer a flat chapter-wide target ("3000-5000 words, 4-6 non-text elements"). Each concept now gets its own word-count range and minimum non-text-element requirement computed from its Concept Impact Score (CIS), read from the CIS Score column that book-chapter-generator v1.0.0+ writes into each chapter's "Concepts Covered" table. Foundational, high-impact concepts get real elaboration (worked examples, diagrams); narrow, low-impact concepts get efficient, brief treatment. See "Elaboration Budget" (Step 2.3b) below. Requires chapters generated by book-chapter-generator v1.0.0+ (table format) and a learning-graph.json from learning-graph-generator v1.06+ (has node.cis).

Version 0.09 Features:

• Mascot self-introduction in Chapter 1 - When the project CONTENT-GENERATION-GUIDE.md defines a pedagogical mascot, the FIRST mascot admonition in Chapter 1 must be a self-introduction that names the mascot and enumerates each pose-role it will play across the book. The pattern is defined once for the whole library in mascot-placement-rules.md (see Step 2.4, principle 4)

Version 0.07 Features:

• Instructional scaffolding - Define-before-display rules ensure terms are explained before diagrams use them, code parameters are explained before code examples, and tables reinforce rather than introduce concepts (see Step 2.4, principle 3)
• Sequential execution - Generate content one chapter at a time to avoid excessive token usage. A user may override this with the phrase "use parallel execution" but the skill will warn them that a 38% additional tokens will be used
• Edge direction validation - Mandatory check to prevent inverted dependency bugs (see Step 1.3a)

When to Use This Skill

Use this skill when:

• The book-chapter-generator skill has created chapter directories with index.md files
• A chapter index.md contains: title, summary, and concepts covered list
• Detailed chapter content needs to be generated
• Content should be adapted to a specific reading level (junior high, senior high, college, graduate)
• Rich non-text elements (diagrams, MicroSims, infographics) are desired

Do NOT use this skill when:

• Chapter structure hasn't been created yet (use book-chapter-generator first)
• Content already exists and just needs editing (use Edit tool directly)
• Generating other types of content (prompts, glossaries, etc.)
• The user is almost out of tokens (over 95% of used in a 5-hour window)

Execution Modes

Sequential Mode (Default for all use-cases)

• Always only do one chapter at a time due to large overhead of parallel mode
• Wait for a chapter to totally finish and log the session before you begin the next chapter
• Clearly indicate to the user when each chapter is finished

Parallel Mode (Only on request)

Parallel mode should ONLY be used when the user specifically request parallel execution. Warn the user that there will be a substantial token penalty to pay for parallel execution.

Single Chapter Mode

Use for:

• Updating one chapter after outline revision
• Testing content format before batch generation

Workflow

Phase 1: Setup (Sequential)

This phase runs once before any content generation, reading shared context that all agents will need.

Step 1.1: Capture Start Time for Logging

date "+%Y-%m-%d %H:%M:%S" >>logs/ch-{NN}-content-generation.md

Where {NN} is the two digit chapter number with zero padding.

Log the start time for the session report.

Step 1.2: Indicate Skill Running

Notify the user: "Chapter Content Generator Skill v1.11 running in [parallel/sequential] mode."

Step 1.3: Read Shared Context

Read and cache these files for all agents:

1. Course Description (docs/course-description.md)

• Extract target audience and reading level
• Note course objectives and tone guidelines in the project CONTENT-GENERATION-GUIDE.md
• Identify any mascot or narrative elements (e.g., Delta in calculus) in the project CONTENT-GENERATION-GUIDE.md

1. Learning Graph (docs/learning-graph/learning-graph.json and/or learning-graph.csv)

• Load concept list with dependencies
• Understand concept relationships for pedagogical ordering
• Compute `cis_max` = the maximum cis value across all nodes in the

book (max(n.get('cis', 1) for n in data['nodes'])). This one number is reused for every chapter in the session -- Elaboration Budget normalization (Step 2.3b) is always global (against the whole book), never local to one chapter, since a concept's importance is a book-wide claim, not a chapter-local one. If every node's cis is 1, the learning graph predates learning-graph-generator v1.06 -- report this to the user and suggest regenerating learning-graph.json before proceeding, rather than silently falling back to flat word counts.

!!! info "Learning Graph = Concept Dependency Graph (a DAG)" A learning graph is a Concept Dependency Graph -- a directed acyclic graph (DAG) where each edge represents a "depends on" relationship. We use the dependency direction (edges point FROM a concept TO the concepts it depends on) because this aligns with standard graph theory algorithms for topological sorting, cycle detection, and transitive reduction.

Some learning management systems use an enablement graph where edges point the opposite way (FROM prerequisite TO enabled concept). That direction is more intuitive for some teachers but less natural for graph algorithms. This project uses the dependency direction exclusively.

!!! danger "CRITICAL: Edge Direction in learning-graph.json" In the vis-network JSON format, edges point FROM dependent TO prerequisite (the dependency direction).

• Edge {from: 5, to: 1} means "Biodiversity (5) depends on Ecology (1)"
• It does NOT mean "Ecology leads to Biodiversity" (that would be the enablement direction)

To build a prerequisite map: ``python # CORRECT: dependency direction -- from=dependent, to=prerequisite prereqs[edge['from']].add(edge['to']) ``

NEVER use: ``python # WRONG: accidentally converts to enablement direction, inverting ALL dependencies prereqs[edge['to']].add(edge['from']) ``

Getting this wrong produces hundreds of false violations and wastes significant tokens on invalid chapter designs. Always validate with Step 1.3a before proceeding.

1. Glossary (docs/glossary.md)

• Load term definitions for consistent terminology if they exist
• In most cases the glossary is created after the content is generated
• Note which concepts have glossary entries

1. Project CONTENT-GENERATION-GUIDE.md (if exists)

• Load project-specific guidelines
• Note any reading level, mascot specifications, tone requirements, or special formatting

1. Chapter List (scan docs/chapters/ directory)

• Enumerate all chapter directories
• Identify which chapters need content generation (have outline but no content)

Step 1.3a: Validate Edge Direction (MANDATORY)

Before using any dependency data, verify the edge direction is correct. This step prevents the most common and expensive bug in chapter generation -- an inverted dependency map that silently produces invalid chapter orderings.

Validation procedure:

1. Identify foundational concepts -- those with empty Dependencies in the CSV, or with zero prerequisites in the JSON
2. Build the prerequisite map using prereqs[edge['from']].add(edge['to'])
3. Check that foundational concepts have ZERO entries in the prereqs map

import json
from collections import defaultdict
with open('docs/learning-graph/learning-graph.json') as f:
    data = json.load(f)
# Build prereqs: from=dependent, to=prerequisite
prereqs = defaultdict(set)
for e in data['edges']:
    prereqs[e['from']].add(e['to'])
# Find concepts with zero prerequisites (foundational)
all_ids = {n['id'] for n in data['nodes']}
foundational = all_ids - set(prereqs.keys())
print(f"Foundational concepts (no prerequisites): {len(foundational)}")
for fid in sorted(foundational):
    node = next(n for n in data['nodes'] if n['id'] == fid)
    print(f"  {fid}: {node['label']}")
# SANITY CHECK: foundational concepts should be simple/introductory
# If you see advanced concepts here, the edge direction is WRONG

Pass criteria:

• Foundational concepts should be simple, introductory terms (e.g., "Ecology", "Energy", "System")
• If advanced concepts appear as foundational (e.g., "Sustainability", "Climate Change", "Tipping Points"), the edge direction is inverted -- STOP and fix before proceeding
• The number of foundational concepts should be small (typically 3-10 for a 200-400 concept graph)
• If you see 50+ "foundational" concepts, the direction is likely inverted

If validation fails: Do NOT proceed with content generation. Report the issue to the user and suggest re-running with the correct edge direction.

Step 1.3b: Verify Chapter Dependency Order (MANDATORY)

After validating edge direction, verify that every chapter's concept prerequisites have already been covered in earlier chapters. This ensures content can reference prior material without forward references.

# Build chapter_map: concept_id -> chapter_index
chapter_map = {}
for i, (title, cids) in enumerate(chapters):
    for cid in cids:
        chapter_map[cid] = i