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:
- Show: "Here's a working spec, generated code, test results"
- Explain: "Here's why this works. Here are the principles."
- Practice: "Now you try with a different domain"
- 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:
- Task: Real but constrained (e.g., "build email validator")
- Your Role: Write spec / set up tools / identify bug
- AI/System Role: Generate code / install / fix
- Your Role Again: Test / verify / understand
- 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:
- 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