This skill generates a structured chapter outline for intelligent textbooks by analyzing course descriptions, learning graphs, and concept dependencies. Use this skill after the learning graph has been created and before generating chapter content, to design an optimal chapter structure that respects concept dependencies and distributes content evenly across all of the chapter in a book.
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.
Use this skill when:
Prerequisites:
/docs/course-description.md must exist/docs/learning-graph/learning-graph.json must exist with ~200 conceptsDo NOT use this skill if:
learning-graph-generator first)This skill follows a four-step sequential workflow with user approval before generating files.
Before designing chapters, analyze the following resources:
Read /docs/course-description.md to understand:
Read /docs/learning-graph/learning-graph.json to extract:
!!! 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:
Before designing any chapters, verify the edge direction is correct:
prereqs[edge['from']].add(edge['to'])# 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.
Read /docs/learning-graph/concept-taxonomy.md (if it exists) to understand:
Analyze the data to identify:
Design an optimal chapter structure following these principles:
Choose the appropriate number of chapters (6-20) based on:
Guidelines:
Design chapter assignments that satisfy these requirements:
CRITICAL REQUIREMENTS:
OPTIMIZATION GOALS:
For each chapter, create a title that:
Examples:
For each chapter, write a single sentence (20-40 words) that:
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 Chapters 1-7
- **Challenge**: Taxonomy category Y contains 45 concepts
**Solution**: Split across Chapters 3, 6, and 9 to maintain logical flow
[... other challenges ...]
### Statistics:
- Total chapters: [X]
- Average concepts per chapter: [X.X]
- Range: [min]-[max] concepts per chapter
- All [total] concepts covered: ✓
- All dependencies respected: ✓
After presenting the design, ask:
Do you approve this chapter structure? (y/n)
If no, please specify what changes you'd like:
- Different number of chapters?
- Specific concepts moved to different chapters?
- Chapter titles revised?
- Different grouping strategy?
If the user says "no" or requests changes:
If the user says "yes":
Once the user approves the design, create the chapter structure:
For each chapter, create a URL-friendly path name:
Rules:
Examples:
"Introduction to Graph Theory Fundamentals" → "intro-to-graph-theory"
"Binary Trees and Tree Traversal Algorithms" → "binary-trees-traversal"
"Advanced Topics in Network Flow Optimization" → "advanced-network-flow"
Create the following directory structure:
/docs/chapters/
├── index.md
├── 01-[url-path-name]/
│ └── index.md
├── 02-[url-path-name]/
│ └── index.md
├── 03-[url-path-name]/
│ └── index.md
[... continue for all chapters ...]
Implementation:
mkdir -p /docs/chapters
mkdir -p /docs/chapters/01-[url-path-name]
mkdir -p /docs/chapters/02-[url-path-name]
# ... continue for all chapters
Create /docs/chapters/index.md with:
# Chapters
This textbook is organized into [X] chapters covering [Y] concepts.
## Chapter Overview
1. [Chapter 1 Title](01-[url-path-name]/index.md) - [One sentence summary]
2. [Chapter 2 Title](02-[url-path-name]/index.md) - [One sentence summary]
[... continue for all chapters ...]
## How to Use This Textbook
[Add 2-3 sentences about how readers should progress through the chapters, noting that dependencies are respected and concepts build on each other]
---
**Note:** Each chapter includes a list of concepts covered. Make sure to complete prerequisites before moving to advanced chapters.
For each chapter, create /docs/chapters/[XX]-[url-path-name]/index.md with this structure:
# [Chapter Title]
## Summary
[Write a 2-4 sentence summary of what the chapter covers, expanding on the one-sentence version from the design. Include:]
- Main topics and themes
- How this chapter fits in the learning progression
- What students will be able to do after completing this chapter
## Concepts Covered
This chapter covers the following [X] concepts from the learning graph:
1. [Concept Name 1]
2. [Concept Name 2]
3. [Concept Name 3]
[... continue for all concepts in this chapter ...]
## Prerequisites
[If this is not the first chapter, list which previous chapters should be completed first:]
This chapter builds on concepts from:
- [Chapter X: Chapter Title](../[XX]-[url-path-name]/index.md)
- [Chapter Y: Chapter Title](../[YY]-[url-path-name]/index.md)
[If this is the first chapter or has no prerequisites within the book:]
This chapter assumes only the prerequisites listed in the [course description](../../course-description.md).
---
TODO: Generate Chapter Content
Important formatting notes:
After creating all chapter files, update mkdocs.yml to include the chapters in navigation.
Note that the navigation bar is not very wide, so we don't spell out the name "Chapter X" in the nav bar.
We only need to put the number since the "Chapters:" label is above the list of chapters.