book-scaffolding

What this skill does

# Skill: Book Scaffolding and Structure Planning

**Purpose**: Plan, structure, and scaffold large educational books using cognitive load management, just-in-time specification, and pedagogical best practices.

**Constitution Alignment**: v4.0.1 emphasizing:
- **Principle 1**: Specification Primacy ("Specs Are the New Syntax")
- **Section IIa**: Panaversity 4-Layer Teaching Method (progressive lesson structure)
- **Section IIb**: AI Three Roles Framework (bidirectional co-learning partnership)
- **Nine Pillars** (Section I): AI CLI, Markdown, MCP, AI-First IDEs, Cross-Platform, TDD, SDD, Composable Skills, Cloud-Native
- **Principle 4**: Coherent Pedagogical Structure (flexible lesson counts based on concept density)

**Status**: Reusable skill (learned from 002-book-structure sprint, enhanced with structural patterns)
**Application**: Any multi-part, multi-chapter educational work

---

## Core Principles (9 Learnings from Sprint)

### 1. Just-In-Time Specification ("Specs Are the New Syntax")
❌ **DON'T**: Decide everything upfront. Block on all clarifications before moving forward.
✅ **DO**: Spec what's needed now. Defer part-specific clarifications to when that part is ready for planning.

**Why**: Unblocks work immediately. Clarifications arrive exactly when needed (during chapter-planner phase). Respects SDD loop: **Spec → Plan → Implement per part (one at a time)**.

**KEY**: Specification writing is the PRIMARY skill. Book structure scaffolds specification-first learning across all parts.

**Example**:
- Part 1 spec created with only Part 1 narrative ("Coder to Super Orchestrator")
- Agent frameworks for Part 6 deferred until Part 6 is ready for planning
- Each part planning phase triggers clarifications for that part

### 2. Minimal MVP Approach
❌ **DON'T**: Create comprehensive guides, templates, all part specs upfront, skill integration guides, validation guides
✅ **DO**: Create only essentials. Focus on: Part intros, Chapter placeholders, Part 1 spec, validation report

**Why**: Reduces redundancy. Eliminates over-engineering. Gets to writing faster.

**What Actually Needed**:
- 7 part intro files (explain what each part is about)
- 32 chapter folder structure with READMEs
- 1 Part 1 spec (detailed, ready for chapter-planner)
- Validation report (confirm structure works)
- Parts 2-7 specs deferred until needed

### 3. Narrative Continuity
❌ **DON'T**: Treat chapters as isolated units. Let each chapter wander to its own conclusion.
✅ **DO**: Use a unifying narrative arc across all chapters in a part.

**Why**: Readers stay engaged. Content cohesion improves. Readers see connections.

**Example from Part 1**:
- **Unifying narrative**: "From Coder to Super Orchestrator"
- **Chapter 1**: Sets up the mindset shift
- **Chapter 2**: Explains the 9 revolutions that enable it
- **Chapter 3**: Installs the tools you'll need as an orchestrator
- **Chapter 4**: You execute your first orchestration (spec → AI → test → deploy)
- **Chapter 5**: You debug when orchestration fails (resilience)

Each chapter reinforces the "orchestrator" identity while progressing the story.

### 4. Cognitive Load Management (CRITICAL)
❌ **DON'T**: Front-load complex concepts. Assume readers have prior knowledge.
✅ **DO**: Manage cognitive load across chapters. Light → Moderate → Advanced. Heavy scaffolding early.

**Framework**:
- **Cognitive Load Level**: Light, Moderate, Heavy (define per part)
- **Scaffolding Level**: Heavy (early), Moderate (middle), Light (late)
- **Concept Density**: 3-7 key concepts per chapter (varies by part)
- **Review Cycles**: 2-3 for new material, 1 for reinforcement

**Example from Part 1**:
- **Cognitive Load**: LIGHT (foundational orientation)
- **Scaffolding**: HEAVY (show-then-explain, guided examples, zero gatekeeping)
- **Concept Density**: 3-4 per chapter (time for absorption)
- **Result**: Beginners feel comfortable, not overwhelmed

### 5. Show-Then-Explain Pedagogy
❌ **DON'T**: Explain concepts first, then show examples
✅ **DO**: Show working examples first, then explain the principles

**Why**: Cognitive science: People learn better when they see concrete examples before abstract rules.

**Pattern**:
1. **Show**: "Here's a working spec, generated code, test results"
2. **Explain**: "Here's why this works. Here are the principles."
3. **Practice**: "Now you try with a different domain"
4. **Assess**: "Can you do this independently?"

### 6. Zero Gatekeeping Language
❌ **DON'T**: "It's simple...", "Obviously...", "Just...", "Anyone can..."
✅ **DO**: Explain every assumption. Honor the reader's learning journey.

**Why**: Gatekeeping language alienates readers who don't find it simple. Inclusive language respects all learners.

**Example Rewrites**:
- ❌ "Simply write a spec and Claude Code generates code"
- ✅ "Write a spec with clear requirements. Claude Code reads your spec and generates code that meets those requirements."

- ❌ "Debugging is easy—just read the error message"
- ✅ "When code fails, read the error message to understand what happened. Here's how to interpret common errors..."

### 7. Connection Mapping (Part-to-Part)
❌ **DON'T**: Treat each part as isolated. Readers wonder "Why am I learning this?"
✅ **DO**: Explicitly map how each part prepares for subsequent parts.

**Pattern**:
```
Part 1 → Mindset shift (orchestration)
  ↓ prepares you for Part 2 (tools)
  ↓ which prepares you for Part 3 (prompting)
  ↓ which prepares you for Part 4 (Python)
  ↓ which prepares you for Part 5 (Spec-Kit)
  ↓ which prepares you for Part 6 (agents)
  ↓ which prepares you for Part 7 (MCP)
```

**Example from Part 1 Spec**:
- Chapter 1 prepares for: Part 2 (tools matter), Part 3 (specs), Part 4 (orchestration is code)
- Chapter 2 prepares for: Part 5 (Spec-Kit), Part 6 (agents), Part 7 (MCP integration)
- Chapter 3 prepares for: Chapter 4 (hands-on), Parts 2-7 (tools assumed working)

### 8. Success Criteria Definition
❌ **DON'T**: Vague acceptance criteria ("students will understand...")
✅ **DO**: Measurable, observable success criteria for each chapter

**Pattern per Chapter**:
```
Learning Outcome: "Understand why orchestration beats coding"
Success Criteria: "Reader can articulate in their own words why orchestration > coding"
Measurable Target: "90%+ of readers can explain (in own words) without prompting"
```

**Example from Part 1, Chapter 1**:
- Readers can name 3 mechanisms of vertical intelligence (subagents, skills, MCP)
- Readers see real ARR numbers and feel motivated (not threatened)
- Readers are ready for "Understanding 9 Revolutions" (Chapter 2)

### 9. Hands-On Exercises (Practical Chapters)
❌ **DON'T**: Teach only concepts. No practice.
✅ **DO**: Include real exercises for practical chapters (tool setup, first program, debugging)

**Exercise Pattern**:
1. **Task**: Real but constrained (e.g., "build email validator")
2. **Your Role**: Write spec / set up tools / identify bug
3. **AI/System Role**: Generate code / install / fix
4. **Your Role Again**: Test / verify / understand
5. **Reflection**: "Why did this work? What did you learn?"

**Example from Part 1**:
- **Chapter 3**: Install all 3 tools, verify end-to-end
- **Chapter 4**: Write spec for email validator → Claude Code generates → Test
- **Chapter 5**: Debug deliberately broken code, iterate to fix

### 10. Nine Pillars Alignment (NEW - Constitution v3.1.2)
❌ **DON'T**: Structure book without Nine Pillars framework
✅ **DO**: Scaffold content to progressively introduce and apply Nine Pillars

**The Nine Pillars of AI-Native Development:**
1. AI-First Mindset, 2. Specification-First Development, 3. Evals-Driven Validation, 4. Iterative Convergence, 5. Context Engineering, 6. Output Validation, 7. Strategic Orchestration, 8. Continuous Learning, 9. Ethical Responsibility

**Scaffolding Strategy:**
- **Part 1**: Introduce Pillars 1, 2, 8 (AI-First Mindset, Specs-First, Continuous Learning)
- **Parts 2-5**: Apply Pillars 2-6 in practice (Spec-First, Evals, Converg