book-chapter-generator

What this skill does

# Book Chapter Generator

## Overview

This skill creates a comprehensive chapter structure for intelligent textbooks by analyzing the course description, learning graph, and concept taxonomy. It designs an optimal chapter outline that ensures all concepts are covered exactly once, respects dependency relationships, and distributes content appropriately across chapters.
This task is run serially after the learning graph generation.

## When to Use This Skill

Use this skill when:
- The course description is finalized and the a learning graph has been generated (learning-graph.json exists)
- Chapter content structure needs to be designed before writing begins

**Prerequisites:**
- `/docs/course-description.md` must exist
- `/docs/learning-graph/learning-graph.json` must exist with ~200 concepts
- mkdocs.yml file must be in place for the chapter links to be generated to the nav section

**Do NOT use this skill if:**
- The learning graph hasn't been generated yet (use `learning-graph-generator` first)
- Chapter content already exists and just needs updating

## Chapter Generation Workflow

This skill follows a four-step sequential workflow with user approval before generating files.

### Step 1: Analyze Input Resources

Before designing chapters, analyze the following resources:

#### 1.1 Read Course Description

Read `/docs/course-description.md` to understand:
- Course title and target audience
- Learning objectives and outcomes
- Prerequisite knowledge
- Overall scope and goals

#### 1.2 Read Learning Graph

Read `/docs/learning-graph/learning-graph.json` to extract:
- Complete list of concepts (typically 200 concepts)
- Concept dependencies (which concepts require others as prerequisites)
- Concept groupings by taxonomy category
- Metadata about the course

!!! 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 chose 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 alternative called an **enablement graph**,
    where edges point in the opposite direction (FROM prerequisite TO the concepts it
    enables). The enablement direction is more intuitive for some teachers ("learning
    Ecology enables you to learn Ecosystems"), but it is 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
    prereqs = defaultdict(set)
    for edge in data['edges']:
        prereqs[edge['from']].add(edge['to'])  # CORRECT: dependency direction
    ```

    **NEVER use** `prereqs[edge['to']].add(edge['from'])` -- this accidentally
    converts to the enablement direction, inverting ALL dependencies and silently
    producing invalid chapter orderings. This bug wastes significant tokens and
    requires a complete redesign.

Validate that:
- The graph structure is a valid DAG (no circular dependencies)
- All concepts have unique IDs
- Dependency references are valid

#### 1.2a Validate Edge Direction (MANDATORY)

Before designing any chapters, verify the edge direction is correct:

1. Build the prerequisite map using `prereqs[edge['from']].add(edge['to'])`
2. Identify foundational concepts (those with zero entries in prereqs)
3. Verify foundational concepts are simple, introductory terms (e.g., "Ecology", "Energy", "System")
4. If advanced concepts appear as foundational, the direction is WRONG -- stop and fix

```python
# Quick validation
foundational = [n for n in data['nodes'] if n['id'] not in prereqs]
print(f"Foundational ({len(foundational)}):")
for n in foundational:
    print(f"  {n['id']}: {n['label']}")
# These should be simple/introductory. If you see "Sustainability",
# "Climate Change", etc., the edge direction is inverted.
```

**Do NOT proceed to chapter design until this check passes.**

#### 1.3 Read Concept Taxonomy

Read `/docs/learning-graph/concept-taxonomy.md` (if it exists) to understand:
- Taxonomy categories and their meanings
- How concepts are grouped conceptually
- Any suggested ordering or progression

#### 1.4 Identify Design Constraints

Analyze the data to identify:
- **Foundational concepts**: Concepts with no dependencies (should appear early)
- **Advanced concepts**: Concepts with many dependencies (should appear later)
- **Dependency chains**: Long sequences of prerequisite relationships
- **Concept clusters**: Groups of related concepts that should stay together
- **Terminal concepts**: Concepts that nothing depends on (can be placed flexibly)

### Step 2: Design Chapter Structure

Design an optimal chapter structure following these principles:

#### 2.1 Determine Chapter Count

Choose the appropriate number of chapters (6-20) based on:
- **Total concepts**: ~200 concepts typically need 10-15 chapters
- **Dependency complexity**: More complex dependencies may need more chapters
- **Taxonomy distribution**: Natural groupings suggest chapter boundaries
- **Target audience**: Introductory courses may need smaller chapters

**Guidelines:**
- Minimum 6 chapters (for very concise courses)
- Optimal range: 10-15 chapters
- Maximum 20 chapters (for comprehensive graduate-level content)
- Aim for 10-20 concepts per chapter on average

#### 2.2 Assign Concepts to Chapters

Design chapter assignments that satisfy these requirements:

**CRITICAL REQUIREMENTS:**
1. **Every concept appears in exactly one chapter** (no duplicates, no omissions)
2. **No concept appears before its dependencies** (respect the DAG structure)
3. **Balanced distribution** (avoid chapters with too many or too few concepts)

**OPTIMIZATION GOALS:**
- Keep related concepts (same taxonomy category) together when possible
- Create logical progression from foundational to advanced topics
- Balance chapter sizes (avoid chapters with <8 or >25 concepts)
- Group concepts that form natural learning units
- Consider cognitive load (mix difficulty levels within chapters)

#### 2.3 Create Chapter Titles

For each chapter, create a title that:
- Uses **Title Case** formatting
- Is **no longer than 200 characters** (to fit on one line)
- Clearly describes the chapter's main topic
- Uses standard educational terminology
- Avoids acronyms unless widely known

**Examples:**
- "Introduction to Graph Theory Fundamentals"
- "Binary Trees and Tree Traversal Algorithms"
- "Graph Coloring Problems and Applications"
- "Advanced Topics in Network Flow Optimization"

#### 2.4 Write Chapter Summaries

For each chapter, write a **single sentence** (20-40 words) that:
- Describes what the chapter covers
- Mentions key concepts or themes
- Indicates the chapter's role in the learning progression

### Step 3: Present Design to User for Approval

Before creating any files, present the chapter design to the user in this format:

```
## Proposed Chapter Structure

I've designed a [number]-chapter structure for your textbook covering [total] concepts.

### Chapters:

1. **[Chapter Title]** ([X] concepts)
   [One sentence summary]

2. **[Chapter Title]** ([X] concepts)
   [One sentence summary]

[... continue for all chapters ...]

### Design Challenges & Solutions:

[Discuss any challenges encountered and how the design addresses them, such as:]
- **Challenge**: Concept X has 15 dependencies, making placement difficult
  **Solution**: Placed in Chapter 8 after all prerequisites are covered in Ch