chapter-content-generator

What this skill does

# Chapter Content Generator

**Version:** 0.08

## Overview

This skill generates detailed educational content for individual textbook chapters, transforming chapter outlines (title, summary, concept list) into comprehensive learning material with appropriate reading level, rich visual elements, and interactive components. The skill is designed to run after the `book-chapter-generator` skill has created the chapter structure.

**Version 0.08 Features:**
- **Mascot self-introduction in Chapter 1** - When the project CLAUDE.md defines a pedagogical mascot, the FIRST mascot admonition in Chapter 1 must be a self-introduction that names the mascot and enumerates each of the six pose-roles the mascot will play across the book. This sets reader expectations for every later chapter (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

```bash
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 v0.05 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 CLAUDE.md
   - Identify any mascot or narrative elements (e.g., Delta in calculus) in the project CLAUDE.md

2. **Learning Graph** (`docs/learning-graph/learning-graph.json` and/or `learning-graph.csv`)
   - Load concept list with dependencies
   - Understand concept relationships for pedagogical ordering

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

3. **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

4. **Project CLAUDE.md** (if exists)
   - Load project-specific guidelines
   - Note any mascot specifications, tone requirements, or special formatting

5. **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

```python
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:**