managing-book-operations

name	managing-book-operations
description	Use when generating table of contents, validating metadata, or exploring book content. Triggers on "generate TOC", "table of contents", "validate frontmatter", "book chat".

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