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?"