managing-book-operations

# 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** ```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** ```markdown ### 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** ```markdown 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** ```markdown ### 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?" ```