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.

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

❌ 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).

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

---

The Book Scaffolding Workflow

Phase 1: Global Structure (Book Level)

Input: User vision for the entire book (theme, chapters, learning journey) Output:

• Multi-part architecture with learning progression
• Chapter overview (titles, scope)
• Cognitive load mapping (light → heavy distribution)

Questions to Ask:

1. What is the unifying narrative across all parts?
2. What is the cognitive load of each part?
3. How do chapters connect part-to-part?
4. Where are the heavy scaffolding points?

Reference: See reference/structural-patterns.md for detailed guidance on book organization patterns.

Phase 2: Part-Level Spec (One Part at a Time)

Input: Part purpose, chapter titles, part's role in overall journey Output: Detailed part spec with:

• Part narrative (unifying theme for this part)
• Chapters fully specified (learning outcomes, key topics, success criteria)
• Pedagogical strategy (cognitive load, scaffolding, concept density)
• Connection map (how this part prepares for next)
• Hands-on exercises (for practical chapters)

Defer:

• Part-specific clarifications (agent frameworks, case studies, etc.) → resolve during chapter-planner phase
• Future part specs → create just-in-time when prior parts are in implementation

Questions to Ask:

1. What is this part's PURPOSE in the overall book?
2. What should readers KNOW by the end?
3. What's the narrative arc across chapters?
4. Which chapters need heavy scaffolding? Light?
5. What hands-on exercises would build confidence?

Reference: See reference/chapter-flow-patterns.md for different chapter sequencing approaches.

Phase 3: Chapter-Planner Phase (Invoke Subagent)

Input: Part spec (from Phase 2) Subagent: chapter-planner Output: For each chapter in the part:

• chapter-NN-plan.md (detailed lesson breakdown)
• chapter-NN-tasks.md (implementation checklist)

What Happens:

• chapter-planner reads your part spec
• Breaks each chapter into 5-7 lessons
• Defines learning objectives, code examples, exercises per lesson
• Requests clarifications if needed (JUST-IN-TIME)
• Provides timeline estimates

Reference: See reference/chapter-dependencies.md for managing prerequisites and chapter relationships.

Phase 4: Lesson-Writer Phase (Invoke Subagent)

Input: chapter-NN-plan.md (from Phase 3) Subagent: lesson-writer (iterative) Output: Complete lesson content Process: Write one lesson at a time, review, refine, approve

Phase 5: Validation Phase (Invoke Subagent)

Input: Completed chapter (from Phase 4) Subagent: technical-reviewer Output: Validation report Checks: Code correctness, pedagogical effectiveness, Constitution alignment

---

Quality Standards Checklist

All book content MUST:

• ✅ Apply all domain skills: Use learning-objectives, concept-scaffolding, code-example-generator, exercise-designer, assessment-builder, technical-clarity, book-scaffolding, ai-augmented-teaching
• ✅ Show-then-explain: Examples first, principles second, practice third
• ✅ Zero gatekeeping: No "simple", "obvious", "just". Explain every assumption.
• ✅ Type hints: All code includes type hints (language-appropriate)
• ✅ Testing: All code examples are tested before publication
• ✅ Accessibility: Alt text, high contrast, clear language, multiple reading paths
• ✅ Constitutional alignment: Align with project principles and non-negotiable rules

Acceptance Checks

• Each section/lesson tagged with complexity tier (Beginner/Intermediate/Advanced/Professional)
• Beginner-tier sections respect concept cap (≤ 5 new concepts per section)
• Dependency Index present: prerequisites and forward links with anchors
• SpecRef included at part/chapter headers

Dependency Index (example)

Prerequisites: Part 1 Ch 2 (tools), Part 3 Ch 1 (prompting)
Next: Part 4 Ch 3 (types), Part 5 Ch 1 (Spec‑Kit intro)

---

Success Metrics

For each part:

Metric	Success Measure	Target
Narrative Clarity	Readers articulate the part's purpose	90%+ can explain
Cognitive Load	No overwhelming chapters; scaffolding appropriate	85%+ find it well-paced
Learning Outcomes	Readers achieve measurable outcomes	80%+ achieve all outcomes
Hands-On Completion	Readers complete exercises	80%+ complete exercises
Confidence	Readers feel ready for next part	85%+ agree
Code Quality	All examples run correctly	100% pass testing
Accessibility	All readers can navigate (varied reading styles)	95%+ accessibility

---

Anti-Patterns (What NOT to Do)

❌ Over-Planning: Creating all part specs upfront (deferring decision-making, blocking work) ❌ Isolated Chapters: No connection mapping; readers don't see the journey ❌ Concept Overload: 10+ concepts per chapter; beginners overwhelmed ❌ Explain-Then-Show: Principles first, examples second (harder to learn) ❌ Gatekeeping Language: "Simple", "obvious", "just"; alienates learners ❌ No Exercises: Passive reading; no confidence building ❌ Inconsistent Scaffolding: Heavy in middle, light at start (backwards) ❌ Missing Success Criteria: "They'll understand it"—no measurable target ❌ Redundant Artifacts: Multiple versions of same template, guide, spec ❌ Part Specs Too Early: Creating Part 5 spec before Part 1 is implemented (wasted effort)

---

How to Use This Skill

When Planning a New Part

Use the book-scaffolding skill to:
1. Define the part's purpose in the overall book
2. Create the part narrative (unifying theme)
3. Specify chapters (learning outcomes, key topics, success criteria)
4. Map pedagogical strategy (cognitive load, scaffolding, concept density)
5. Define connection map (how this part prepares for next)
6. Identify hands-on exercises for practical chapters

When Creating a Chapter Spec

Use the book-scaffolding skill to:
1. Define chapter purpose (within part's narrative)
2. List learning outcomes (Bloom's taxonomy aligned)
3. Identify key topics to cover
4. Define success criteria (measurable, observable)
5. Plan pedagogical approach (show-then-explain, concept density)
6. Identify hands-on exercise (if practical chapter)

When Reviewing Completed Content

Use the book-scaffolding skill to:
1. Verify all domain skills applied
2. Check for show-then-explain pattern
3. Confirm zero gatekeeping language
4. Validate accessibility standards
5. Verify type hints and testing in code
6. Check Constitutional alignment

---

References

For deeper guidance on specific aspects of book structure:

• Directory Structure (Project-Specific): specs/book/directory-structure.md

  • THE authoritative source for file paths and folder organization
  • 3-level hierarchy (Part → Chapter → Lesson)
  • Naming conventions (capitalized parts, lowercase chapters)
  • Required files and validation rules

• Chapter Index (Project-Specific): specs/book/chapter-index.md

  • All 32 chapter titles, numbers, and topics
  • Mapping chapters to parts
  • Chapter-specific content guidance

• Chapter Flow Patterns: reference/chapter-flow-patterns.md

  • Linear, spiral, modular, hybrid, and project-based flow patterns
  • Decision framework for choosing the right pattern

• Structural Patterns: reference/structural-patterns.md

  • Tutorial vs. reference balance
  • Chapter internal structure (IBS, MCA, Cookbook, EEE)
  • Part and section organization strategies

• Content Organization: reference/content-organization.md

  • Chunking strategies (micro, mini, standard, macro)
  • Hierarchical organization best practices
  • Cross-referencing techniques

• Chapter Dependencies: reference/chapter-dependencies.md

  • Dependency types and patterns
  • Core vs. optional chapters
  • Managing circular dependencies

---

Version History

v1.0 (2025-10-29): Created from 002-book-structure sprint learning

• 9 core principles
• Workflow (Phase 1-5)
• Quality standards
• Success metrics

v2.0 (2025-10-29): Enhanced with structural patterns

• Integrated reference materials from book-architecture skill
• Added comprehensive flow patterns and organization strategies
• Consolidated as one of the 8 CoLearning Domain Skills

---

Status: Ready for use on all multi-part educational books. Proven on CoLearning Python & Agentic AI project.