book-scaffolding

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, Converge