Managing Book Operations

Guide for book-level operations: table of contents generation, metadata validation, and conversational content exploration.

Instructions

Operation: TOC Generation

When regenerating the table of contents:

Step 1: Scan Chapter Files

Glob: chapters/**/*.md
Glob: appendices/**/*.md

Step 2: Extract Frontmatter

For each file, parse YAML frontmatter:

• •title - entry title
• •part - number
• •part_title - part name
• •chapter - number
• •section - 0 for index, 1+ for sections
• •order - sort key (part.chapter.section)

Step 3: Sort and Group

• •Sort by order field (ascending)
• •Group by part_title to create part sections
• •Within parts, group by chapter number
• •Section 0 files become chapter titles
• •Section 1+ become bulleted items under chapters

Step 4: Generate Markdown

# Table of Contents

## Part 1: Foundations

### Chapter 1: Foundations
- [Foundations](chapters/1-foundations/_index.md)
- [Twelve Leverage Points](chapters/1-foundations/1-twelve-leverage-points.md)

### Chapter 2: Prompt
- [Prompt](chapters/2-prompt/_index.md)
...

Step 5: Write Output

Write to: TABLE_OF_CONTENTS.md (overwrites existing)

Step 6: Report

### TOC Generation Complete

Generated from {file_count} files across {part_count} parts.

**Output:** TABLE_OF_CONTENTS.md
**Chapters:** {count}
**Sections:** {count}

Operation: Interactive Chat

When exploring book content conversationally:

Step 1: Parse Input

• •Topic or question being asked
• •Specific chapter/section references
• •Conversation mode (clarification, exploration, connection)

Step 2: Determine Scope

• •Direct response: Simple queries with targeted Grep + Read
• •Complex exploration: Relationship mapping across chapters
• •Hybrid: Initial answer + offer to go deeper

Step 3a: Direct Response

For straightforward questions:

1. •Search: Grep: {key concepts}
2. •Read: Load identified files
3. •Synthesize:
   • •Ground answer in book content
   • •Provide 1-2 file citations
   • •Match book's conversational voice
   • •Suggest follow-up topics

Step 3b: Complex Exploration

For relationship mapping:

1. •Find all related content across chapters
2. •Map connections between concepts
3. •Identify coverage gaps
4. •Present findings conversationally

Step 4: Format Response

The book addresses this through [concept] in Chapter X...

From `chapters/X/Y.md`:
> [relevant quote or paraphrase]

This connects to [related concept] because [explanation].

Want to explore [specific angle]? I can also map how this relates to [other topics].

Grounding Rules:

• •Stay within documented content
• •Acknowledge what's not covered
• •Reference _questions.md for planned coverage
• •Match book's practical, experience-based voice

Operation: Metadata Validation

When validating frontmatter across book:

Step 1: Define Scope

• •Path provided: Validate that chapter/section only
• •No path: Validate all chapters/ and appendices/

Step 2: Scan Files

Glob: chapters/**/*.md
Glob: appendices/**/*.md

Step 3: Check Each File

Required Fields:

• •title - present, non-empty
• •part - numeric
• •part_title - matches part number consistently
• •chapter - numeric
• •section - numeric (0 for index, 1+ for sections)
• •order - format X.Y.Z, matches part.chapter.section

Optional Fields (if present):

• •description - non-empty
• •created - YYYY-MM-DD format
• •last_updated - YYYY-MM-DD, >= created
• •tags - array, no duplicates
• •status - seedling | growing | mature | evergreen

Consistency Checks:

• •All files in part have matching part_title
• •order matches part.chapter.section pattern
• •Section 0 files named _index.md
• •No gaps in chapter/section numbering

Step 4: Categorize Issues

Critical:

• •Missing required fields
• •Invalid YAML syntax
• •Incorrect order format

Warnings:

• •Inconsistent part_title
• •Numbering gaps
• •last_updated before created

Info:

• •Missing optional fields
• •No status field

Step 5: Report

### Metadata Validation Report

**Scope:** {description}
**Files Checked:** {count}

#### Critical Issues ({count})
| File | Issue | Fix Needed |
|------|-------|------------|
| {path} | Missing 'order' | Add order: X.Y.Z |

#### Warnings ({count})
| File | Issue | Recommendation |
|------|-------|----------------|
| {path} | Part title mismatch | Standardize to "{title}" |

#### Summary
- Valid: {count} files
- Warnings: {count} files
- Critical: {count} files

Key Principles

TOC Generation Algorithm

• •Always sort by order field, never filename
• •Use relative paths from repo root
• •Part -> Chapter -> Section hierarchy
• •Overwrite existing (generated, not authored)
• •Skip files without valid frontmatter

Chat Grounding Rules

• •No speculation beyond documented content
• •Match book voice: practical, experience-based
• •Natural citations woven into response
• •Acknowledge gaps explicitly
• •Suggest captures for new insights

Validation Priority

• •Critical = blocks TOC generation
• •Warning = inconsistency, may cause confusion
• •Info = enhancement opportunity

File Naming Conventions

• •_index.md - Chapter introductions (section: 0)
• •_questions.md - Question scaffolding (skip in TOC)
• •1-topic.md - Numbered sections
• •Descriptive kebab-case names

Examples

Example 1: Generate TOC

Request: "Regenerate table of contents"

Execute:
- Glob chapters/ and appendices/
- Extract frontmatter from 45 files
- Sort by order field
- Generate markdown structure

Output:
- TABLE_OF_CONTENTS.md updated
- 4 parts, 9 chapters, 32 sections
- 2 files skipped (missing frontmatter)

Example 2: Chat about concept

Request: "How does the book cover prompt caching?"

Execute:
- Grep: "prompt caching", "cache"
- Find mentions in chapters 4 and 7
- Read relevant sections

Response:
"Chapter 4 (Context) discusses prompt caching in the strategies section...
From `chapters/4-context/2-context-strategies.md`:
> Caching system prompts reduces latency significantly...

The Practices chapter also touches on this from a cost perspective.
Want me to map all the performance-related content?"

Example 3: Validate specific chapter

Request: "Validate frontmatter for chapter 6"

Execute:
- Glob: chapters/6-patterns/*.md
- Check 4 files

Findings:
- 1 warning: inconsistent part_title
- 1 info: missing status field
- 2 valid

Report with fix recommendations

Example 4: Chat with gap acknowledgment

Request: "What does the book say about fine-tuning?"

Execute:
- Grep: "fine-tuning", "fine tuning"
- No direct coverage found
- Check _questions.md files

Response:
"The book doesn't currently cover fine-tuning in depth.
Chapter 3 (Model) has a placeholder question about when fine-tuning beats prompting.

This could be a good topic to capture. Want to explore related model behavior content instead?"