name: book-documentation
description: Create and maintain technical book documentation with extreme rigor and test-driven validation
category: documentation
priority: critical
prompt: "Create professional technical book documentation following mdBook standards with EXTREME test-driven rigor.\n\n## CRITICAL DIFFERENCES: Book vs Regular Documentation\n\n**Books are NOT README.md files**:\n- Sequential learning narrative (tutorial) OR self-contained recipes (cookbook)\n- 400-1000 pages of comprehensive content\n- mdBook build system with SUMMARY.md table of contents\n- Chapter-based organization with clear progression\n- Production deployment to GitHub Pages\n- Comprehensive test suite for ALL examples\n- Professional quality standards (print-ready)\n\n## STEP 1: ANALYZE BOOK TYPE AND REQUIREMENTS\n\nDetermine book type:\n\n**Tutorial Book** (like pmat-book, ruchy-book):\n- Sequential chapters building on each other\n- Progressive concept introduction\n- Teaching methodology focus\n- 400-600 pages\n- Chapter dependencies expected\n- Linear reading progression\n\n**Cookbook** (like ruchy-cookbook):\n- Self-contained recipes (15-20 per chapter)\n- Random-access problem/solution format\n- Minimal cross-dependencies\n- 1000 pages comprehensive reference\n- Practical application focus\n- Look-up oriented\n\n**Reference Manual** (like ruchy-cli-tools-book):\n- Comprehensive API documentation\n- Tool/command reference\n- Integration guides\n- 500-800 pages\n- Searchable content\n- Quick reference oriented\n\n## STEP 2: SETUP BOOK INFRASTRUCTURE\n\n### Create mdBook Structure\n\n```bash\n# Install mdBook if needed\ncargo install mdbook\ncargo install mdbook-linkcheck\n\n# Initialize book\nmdbook init ${BOOK_TITLE}\ncd ${BOOK_TITLE}\n\n# Create directory structure\nmkdir -p src/{chapters,appendices}\nmkdir -p tests/{ch01,ch02,ch03}\nmkdir -p theme\nmkdir -p scripts\nmkdir -p .github/workflows\n```\n\n### Create book.toml Configuration\n\n```toml\n[book]\ntitle = \"${BOOK_TITLE}\"\nauthors = [\"Your Name\"]\ndescription = \"Comprehensive guide to [TOPIC]\"\nlanguage = \"en\"\nmultilingual = false\nsrc = \"src\"\n\n[build]\nbuild-dir = \"book\"\ncreate-missing = false  # Prevent accidental file creation\n\n[preprocessor.index]\n\n[preprocessor.links]\n\n[output.html]\ntheme = \"theme\"\ndefault-theme = \"rust\"\npreferred-dark-theme = \"coal\"\nsmart-punctuation = true\nmathjax-support = false\ncopy-fonts = true\nadditional-css = [\"theme/custom.css\"]\nadditional-js = []\ngit-repository-url = \"https://github.com/YOUR_ORG/${BOOK_TITLE}\"\ngit-repository-icon = \"fa-github\"\nedit-url-template = \"https://github.com/YOUR_ORG/${BOOK_TITLE}/edit/main/{path}\"\nsite-url = \"https://YOUR_ORG.github.io/${BOOK_TITLE}/\"\n\n[output.html.print]\nenable = true\npage-break = true\n\n[output.html.fold]\nenable = true\nlevel = 1\n\n[output.html.playground]\neditable = true\ncopyable = true\ncopy-js = true\nline-numbers = true\n\n[output.html.search]\nenable = true\nlimit-results = 30\nteaser-word-count = 30\nuse-boolean-and = true\nboost-title = 2\nboost-hierarchy = 1\nboost-paragraph = 1\nexpand = true\nheading-split-level = 3\ncopy-js = true\n```\n\n## STEP 3: CREATE SUMMARY.MD (TABLE OF CONTENTS)\n\n**CRITICAL**: SUMMARY.md is the source of truth for book structure.\n\n### Tutorial Book Template\n\n```markdown\n# Summary\n\n[The Book Title](title-page.md)\n[Foreword](foreword.md)\n[Introduction](introduction.md)\n\n## Part I: Getting Started\n\n- [Chapter 1: Installation and Setup](ch01-00-installation.md)\n  - [Installing Tool](ch01-01-installing.md)\n  - [First Example (TDD)](ch01-02-first-example-tdd.md)\n  - [Understanding Output](ch01-03-output.md)\n\n- [Chapter 2: Core Concepts](ch02-00-core-concepts.md)\n  - [Concept 1](ch02-01-concept1.md)\n  - [Concept 2](ch02-02-concept2.md)\n\n## Part II: Advanced Topics\n\n- [Chapter 3: Advanced Feature 1](ch03-00-advanced.md)\n- [Chapter 4: Advanced Feature 2](ch04-00-advanced2.md)\n\n## Conclusion\n\n- [Conclusion](conclusion.md)\n\n## Appendices\n\n- [Appendix A: Installation Guide](appendix-a-installation.md)\n- [Appendix B: Command Reference](appendix-b-commands.md)\n- [Appendix C: Troubleshooting](appendix-d-troubleshooting.md)\n```\n\n### Cookbook Template\n\n```markdown\n# Summary\n\n[The Cookbook Title](title-page.md)\n[Introduction](introduction.md)\n\n## Chapter 1: Basic Patterns\n- [Recipe 1.1: Basic Task](ch01-recipe-001.md)\n- [Recipe 1.2: Common Pattern](ch01-recipe-002.md)\n- [Recipe 1.3: Best Practice](ch01-recipe-003.md)\n\n## Chapter 2: Intermediate Techniques\n- [Recipe 2.1: Technique 1](ch02-recipe-001.md)\n- [Recipe 2.2: Technique 2](ch02-recipe-002.md)\n\n## Chapter 3: Advanced Recipes\n- [Recipe 3.1: Complex Pattern](ch03-recipe-001.md)\n```\n\n## STEP 4: CHAPTER STATUS TRACKING (MANDATORY)\n\n**EVERY chapter must include status block at top:**\n\n```markdown\n<!-- DOC_STATUS_START -->\n**Chapter Status**: ✅ 100% Working (5/5 examples)\n\n| Status | Count | Examples |\n|--------|-------|----------|\n| ✅ Working | 5 | Ready for production use |\n| ⚠️ Not Implemented | 0 | Planned for future versions |\n| ❌ Broken | 0 | Known issues, needs fixing |\n| 📋 Planned | 0 | Future roadmap features |\n\n*Last updated: 2025-11-16*\n*Tool version: ${BOOK_TITLE} 1.0.0*\n<!-- DOC_STATUS_END -->\n```\n\n**Update status blocks after every change!**\n\n## STEP 5: TEST-DRIVEN DOCUMENTATION (MANDATORY)\n\n**CRITICAL**: Code examples MUST be tested BEFORE documentation is written.\n\n### Create Test Directory Structure\n\n```bash\n# Chapter-based test structure\ntests/\n├── ch01/\n│   ├── test_installation.sh\n│   ├── test_first_example.sh\n│   └── test_output_format.sh\n├── ch02/\n│   ├── test_core_concepts.sh\n│   └── test_advanced_usage.sh\n└── common/\n    ├── test_utils.sh\n    └── setup.sh\n```\n\n### Test Script Template (MANDATORY FORMAT)\n\n```bash\n#!/bin/bash\n# TDD Test: Chapter X - Feature Name\n# Tests ACTUAL tool behavior, not hypothetical examples\n# EXTREME TDD with NASA-style quality verification\n\n# Note: Using manual error handling instead of set -e for better test output\n\necho \"=== Testing Chapter X: Feature Name ===\"\n\nPASS_COUNT=0\nFAIL_COUNT=0\n\ntest_pass() {\n    echo \"✅ PASS: $1\"\n    PASS_COUNT=$((PASS_COUNT + 1))\n}\n\ntest_fail() {\n    echo \"❌ FAIL: $1\"\n    FAIL_COUNT=$((FAIL_COUNT + 1))\n}\n\n# Verify tool is available\nif ! command -v tool &> /dev/null; then\n    echo \"❌ FATAL: tool binary not found in PATH\"\n    exit 1\nfi\n\necho \"Using tool version: $(tool --version)\"\n\n# Test 1: Basic functionality\necho \"Test 1: Basic functionality validation\"\nTEST_DIR=$(mktemp -d)\ncd \"$TEST_DIR\"\n\n# Create test environment\ncat > test_input.txt << 'EOF'\nTest content here\nEOF\n\n# Run actual tool command\nOUTPUT=$(tool analyze test_input.txt --format json 2>&1 | grep -A 10000 '^{')\n\n# Validate JSON output\nif echo \"$OUTPUT\" | jq -e '.summary' &> /dev/null; then\n    RESULT=$(echo \"$OUTPUT\" | jq -r '.summary.status')\n    if [ \"$RESULT\" == \"success\" ]; then\n        test_pass \"Basic functionality: Tool executed successfully\"\n    else\n        test_fail \"Basic functionality: Expected success, got: $RESULT\"\n    fi\nelse\n    test_fail \"Basic functionality: Tool failed or produced invalid JSON\"\nfi\n\n# Cleanup\ncd /\nrm -rf \"$TEST_DIR\"\n\n# Summary\necho \"\"\necho \"=== Chapter X Test Summary ===\"\necho \"Passed: $PASS_COUNT\"\necho \"Failed: $FAIL_COUNT\"\n\nif [ $FAIL_COUNT -eq 0 ]; then\n    echo \"✅ All tests passed! Chapter X VALIDATED\"\n    exit 0\nelse\n    echo \"❌ Some tests failed - STOP THE LINE\"\n    exit 1\nfi\n```\n\n## STEP 6: TDD WORKFLOW (MANDATORY PROCESS)\n\n**DO NOT SKIP THESE STEPS:**\n\n1. **Write Tests First** (RED phase):\n   ```bash\n   # Create test file for chapter\n   vim tests/ch01/test_installation.sh\n\n   # Make executable\n   chmod +x tests/ch01/test_installation.sh\n\n   # Run - MUST FAIL initially\n   bash tests/ch01/test_installation.sh\n   # Expected: ❌ Tests fail (no documentation yet)\n   ```\n\n2. **Write Documentation** (GREEN phase):\n   ```bash\n   # Write chapter content with working examples\n   vim src/ch01-01-installing.md\n\n   # Run tests - MUST PASS now\n   bash tests/ch01/test_installation.sh\n   # Expected: ✅ All tests passed\n   ```\n\n3. **Update Status Blocks**:\n   ```bash\n   # Update chapter status to reflect test results\n   # Update SUMMARY.md if needed\n   ```\n\n4. **Validate Quality**:\n   ```bash\n   # Run all chapter tests\n   make test-ch01\n\n   # Run book quality checks\n   make validate\n\n   # Build book locally\n   make build\n   ```\n\n5. **Commit Only When Tests Pass**:\n   ```bash\n   git add src/ch01-01-installing.md tests/ch01/test_installation.sh\n   git commit -m \"docs: Add Chapter 1.1 - Installation\n\n   - All examples tested and working\n   - Test coverage: 100%\n   - Pass rate: 5/5 (100%)\n   - Status: ✅ Production ready\"\n   ```\n\n## STEP 7: MAKEFILE AUTOMATION\n\n**Create comprehensive Makefile:**\n\n```makefile\n.PHONY: all build serve test clean lint validate help\n\nall: validate build\n\nhelp:\n\t@echo \"${BOOK_TITLE} Development Commands:\"\n\t@echo \"\"\n\t@echo \"📚 BOOK OPERATIONS:\"\n\t@echo \"  make build             - Build the book with mdBook\"\n\t@echo \"  make serve             - Serve the book locally (port 3000)\"\n\t@echo \"  make clean             - Remove all build artifacts\"\n\t@echo \"\"\n\t@echo \"🧪 TESTING OPERATIONS:\"\n\t@echo \"  make test              - Test all code examples\"\n\t@echo \"  make test-ch01         - Test Chapter 1 examples\"\n\t@echo \"  make test-all-chapters - Run ALL chapter tests\"\n\t@echo \"\"\n\t@echo \"🎨 CODE QUALITY:\"\n\t@echo \"  make lint              - Lint all code examples\"\n\t@echo \"  make lint-markdown     - Validate markdown links\"\n\t@echo \"  make dogfood           - Run tool analysis on book itself\"\n\t@echo \"  make quality-gate      - Check quality gates\"\n\t@echo \"  make validate          - Run ALL quality checks\"\n\t@echo \"\"\n\ninstall-deps:\n\t@command -v mdbook >/dev/null 2>&1 || cargo install mdbook\n\t@command -v mdbook-linkcheck >/dev/null 2>&1 || cargo install mdbook-linkcheck\n\nbuild: install-deps\n\t@echo \"📚 Building ${BOOK_TITLE}...\"\n\t@mdbook build\n\t@echo \"✅ Book built successfully: book/index.html\"\n\nserve: install-deps\n\t@echo \"🌐 Serving ${BOOK_TITLE} at http://localhost:3000\"\n\t@mdbook serve --port 3000\n\nclean:\n\t@rm -rf book/\n\t@echo \"✅ Build artifacts cleaned\"\n\n# Test individual chapters\ntest-ch01:\n\t@echo \"Testing Chapter 1...\"\n\t@bash tests/ch01/*.sh\n\ntest-ch02:\n\t@echo \"Testing Chapter 2...\"\n\t@bash tests/ch02/*.sh\n\n# Test all chapters\ntest-all-chapters:\n\t@echo \"Testing all chapters...\"\n\t@for dir in tests/ch*/; do \\\n\t\techo \"Testing $${dir}...\"; \\\n\t\tfor test in $${dir}*.sh; do \\\n\t\t\tbash \"$$test\" || exit 1; \\\n\t\tdone \\\n\tdone\n\ntest: test-all-chapters\n\t@echo \"✅ All tests passed!\"\n\nlint-markdown:\n\t@mdbook build\n\t@echo \"✅ Markdown links validated\"\n\ndogfood:\n\t@${QUALITY_TOOL} analyze . --min-grade B+\n\t@echo \"✅ Quality gate passed\"\n\nvalidate: test lint-markdown dogfood\n\t@echo \"✅ All quality checks passed!\"\n```\n\n## STEP 8: CODE EXAMPLE FORMAT (MANDATORY)\n\n**Every code example must follow this structure:**\n\n```markdown\n### Example: Analyzing a Repository\n\n\\`\\`\\`bash\n# CLI usage with clear comments\ntool analyze /path/to/repo --format json\n\\`\\`\\`\n\n**Expected Output:**\n\\`\\`\\`json\n{\n  \"files\": 100,\n  \"lines\": 5000,\n  \"languages\": [\"rust\", \"python\"]\n}\n\\`\\`\\`\n\n**Explanation:**\n- The `analyze` command scans the repository\n- `--format json` outputs structured data\n- Results include file count, line count, and detected languages\n\n**Common Issues:**\n- ❌ **Error**: \"Repository not found\"\n  - **Solution**: Verify path exists and is a valid repository\n- ❌ **Error**: \"Permission denied\"\n  - **Solution**: Check file permissions with `ls -la`\n```\n\n## STEP 9: CHAPTER TEMPLATE (MANDATORY FORMAT)\n\n```markdown\n# Chapter X: Chapter Title\n\n<!-- DOC_STATUS_START -->\n**Chapter Status**: ✅ 100% Working (X/X examples)\n[Status table]\n<!-- DOC_STATUS_END -->\n\n## The Problem\n\n[What problem does this chapter solve? Why should reader care?]\n\n## Core Concepts\n\n[Key ideas and terminology - define everything]\n\n## Prerequisites\n\n[What reader needs to know before reading this chapter]\n\n## Practical Examples\n\n### Example 1: Basic Usage\n\n[Working code example with output]\n\n### Example 2: Advanced Usage\n\n[Working code example with output]\n\n## Common Patterns\n\n[Best practices and idioms]\n\n## Troubleshooting\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| \"X not found\" | Missing dependency | Install with `command` |\n| \"Permission denied\" | File permissions | Run `chmod +x file` |\n\n## See Also\n\n- [Chapter Y: Related Topic](ch0Y-00-topic.md)\n- [Appendix A: Reference](appendix-a-reference.md)\n\n## Summary\n\n- Key takeaway 1\n- Key takeaway 2\n- Key takeaway 3\n\n## Exercises\n\n1. **Basic**: [Exercise description]\n2. **Intermediate**: [Exercise description]\n3. **Advanced**: [Exercise description]\n```\n\n## STEP 10: COOKBOOK-SPECIFIC RECIPE FORMAT\n\n**If writing a cookbook, use this recipe format:**\n\n```markdown\n## Recipe X.Y: Solve Specific Problem\n\n**Difficulty**: Beginner | Intermediate | Advanced | Expert\n**Time**: 5-10 minutes\n**Prerequisites**: Chapter A, Recipe B.C\n\n### Problem\n\n[Clear, specific problem statement in 1-2 sentences]\n\n### Solution\n\n\\`\\`\\`language\n// Complete, working code that solves the problem\n// Must compile and run without errors\n\\`\\`\\`\n\n### Discussion\n\n**How it works:**\n1. Step 1 explanation\n2. Step 2 explanation\n3. Step 3 explanation\n\n**Why this approach:**\n- Reason 1\n- Reason 2\n\n**Performance characteristics:**\n- Time complexity: O(n)\n- Space complexity: O(1)\n- Typical use cases: X, Y, Z\n\n### Variations\n\n**Variation 1: Alternative Approach**\n\\`\\`\\`language\n// Alternative implementation\n\\`\\`\\`\n\n**When to use:**\n- Use Case 1\n- Use Case 2\n\n**Variation 2: Optimized Version**\n\\`\\`\\`language\n// Optimized implementation\n\\`\\`\\`\n\n**Trade-offs:**\n- Pros: Faster, more efficient\n- Cons: More complex, harder to maintain\n\n### See Also\n\n- Recipe X.Y: Related Recipe\n- Chapter Z: Related Concept\n- [External Resource](https://example.com)\n\n### Tests\n\nThis recipe is fully tested. See `tests/chX/recipe-Y.sh` for test suite.\n```\n\n## STEP 11: GITHUB ACTIONS CI/CD (MANDATORY)\n\n**Create `.github/workflows/test.yml`:**\n\n```yaml\nname: Test and Deploy Book\n\non:\n  push:\n    branches: [ main ]\n  pull_request:\n    branches: [ main ]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n\n      - name: Install Dependencies\n        run: |\n          cargo install mdbook\n          cargo install mdbook-linkcheck\n\n      - name: Test All Chapters\n        run: make test-all-chapters\n\n      - name: Validate Quality\n        run: make validate\n\n      - name: Build Book\n        run: make build\n\n      - name: Upload Test Results\n        if: always()\n        uses: actions/upload-artifact@v3\n        with:\n          name: test-results\n          path: test-results/\n\n  deploy:\n    needs: test\n    runs-on: ubuntu-latest\n    if: github.ref == 'refs/heads/main'\n    steps:\n      - uses: actions/checkout@v3\n\n      - name: Install mdBook\n        run: cargo install mdbook\n\n      - name: Build Book\n        run: mdbook build\n\n      - name: Deploy to GitHub Pages\n        uses: peaceiris/actions-gh-pages@v3\n        with:\n          github_token: ${{ secrets.GITHUB_TOKEN }}\n          publish_dir: ./book\n```\n\n## STEP 12: QUALITY GATES (BLOCKING)\n\n**Before ANY commit, verify:**\n\n```bash\n# 1. All tests pass\nmake test-all-chapters\n# Expected: ✅ X/X chapters passing (100%)\n\n# 2. Minimum pass rate achieved\n# Calculate: (passing_examples / total_examples) >= ${MIN_PASS_RATE}%\n\n# 3. No broken links\nmake lint-markdown\n# Expected: ✅ All links valid\n\n# 4. No vaporware\ngrep -r \"coming soon\\|not yet implemented\\|TODO\\|FIXME\" src/\n# Expected: No matches (or only in properly marked sections)\n\n# 5. Quality tool analysis (if applicable)\nmake dogfood\n# Expected: ✅ Quality grade B+ or higher\n\n# 6. Book builds successfully\nmake build\n# Expected: ✅ Book built: book/index.html\n\n# 7. Local preview works\nmake serve\n# Expected: Book accessible at http://localhost:3000\n```\n\n## STEP 13: ZERO VAPORWARE POLICY (CRITICAL)\n\n**NEVER document features that don't exist or don't work.**\n\n❌ **WRONG** (Vaporware):\n```markdown\n### Example: Advanced Feature (Coming Soon)\n\nThis feature will allow you to...\n(Documentation for unimplemented feature)\n```\n\n✅ **CORRECT** (Documented reality):\n```markdown\n### Example: Working Feature\n\n\\`\\`\\`bash\n# This command was tested and works\ntool feature --flag value\n\\`\\`\\`\n\n**Output:**\n\\`\\`\\`\n(Actual output from running command)\n\\`\\`\\`\n```\n\n**If feature is planned but not implemented:**\n- Document in ROADMAP.md\n- Create GitHub issue\n- DO NOT include in main book content\n- Optional: Add to \"Future Features\" appendix with clear \"NOT YET AVAILABLE\" warning\n\n## STEP 14: CROSS-REFERENCING (BEST PRACTICE)\n\n**Link related content extensively:**\n\n```markdown\nAs discussed in [Chapter 2: Core Concepts](ch02-00-core-concepts.md), we can...\n\nFor more details, see:\n- [Recipe 3.5: Related Pattern](ch03-recipe-005.md)\n- [Appendix B: Command Reference](appendix-b-commands.md)\n\n**Prerequisites**: Readers should understand [Type Systems](ch01-03-types.md) before proceeding.\n```\n\n## STEP 15: DEPLOYMENT (PRODUCTION)\n\n### GitHub Pages Deployment\n\n```bash\n# Build book\nmake build\n\n# Create gh-pages branch (first time only)\ngit checkout --orphan gh-pages\ngit reset --hard\ncp -r book/* .\ngit add .\ngit commit -m \"docs: Deploy book to GitHub Pages\"\ngit push origin gh-pages --force\n\n# Return to main\ngit checkout main\n\n# Enable GitHub Pages in repository settings\n# Source: gh-pages branch, / (root)\n```\n\n### Custom Domain (Optional)\n\n```bash\n# Add CNAME file to book output\necho \"book.yourdomain.com\" > book/CNAME\n\n# Update book.toml\n# site-url = \"https://book.yourdomain.com/\"\n# cname = \"book.yourdomain.com\"\n```\n\n## STEP 16: VERSION CONSISTENCY\n\n**Track tool version in all chapters:**\n\n```markdown\n<!-- DOC_STATUS_START -->\n*Tool version: tool 1.2.3*\n<!-- DOC_STATUS_END -->\n```\n\n**Update all chapters when tool version changes:**\n\n```bash\n# Find all version references\ngrep -r \"Tool version:\" src/\n\n# Update systematically\n# Add Makefile target:\nsync-version:\n\tfind src -name \"*.md\" -exec sed -i 's/tool [0-9.]*$$/tool 1.3.0/g' {} +\n```\n\n## STEP 17: COMMON BOOK ISSUES (FIXED PATTERNS)\n\n### Issue 1: Broken Example Code\n\n**Problem**: Examples don't compile/run\n**Fix**: Test BEFORE documenting\n\n```bash\n# RED phase\nbash tests/ch01/test_example.sh  # FAILS\n\n# GREEN phase (write working code)\n# Document only after test passes\nbash tests/ch01/test_example.sh  # PASSES\n```\n\n### Issue 2: Outdated Examples\n\n**Problem**: Tool evolved, examples broke\n**Fix**: Automated testing catches regressions\n\n```yaml\n# GitHub Actions runs tests on every push\n# Catches breakage immediately\n```\n\n### Issue 3: Inconsistent Formatting\n\n**Problem**: Different example styles across chapters\n**Fix**: Use chapter template, enforce in review\n\n### Issue 4: Missing Test Coverage\n\n**Problem**: Some examples untested\n**Fix**: Calculate pass rate, enforce minimum\n\n```bash\n# Pass rate calculation in Makefile\ntest-all-chapters:\n\t@total=0; passed=0; \\\n\tfor test in tests/**/*.sh; do \\\n\t\ttotal=$$((total + 1)); \\\n\t\tif bash \"$$test\"; then passed=$$((passed + 1)); fi \\\n\tdone; \\\n\trate=$$((passed * 100 / total)); \\\n\tif [ $$rate -lt ${MIN_PASS_RATE} ]; then \\\n\t\techo \"❌ Pass rate $$rate% below minimum ${MIN_PASS_RATE}%\"; \\\n\t\texit 1; \\\n\tfi\n```\n\n### Issue 5: Broken Internal Links\n\n**Problem**: Links to non-existent chapters\n**Fix**: mdbook-linkcheck catches this\n\n```bash\nmake lint-markdown  # Validates all links\n```\n\n### Issue 6: SATD Comments in Examples\n\n**Problem**: TODO, FIXME in code examples\n**Fix**: Pre-commit hook catches SATD\n\n```bash\n# Pre-commit hook\nif grep -r \"TODO\\|FIXME\\|HACK\" src/; then\n    echo \"❌ SATD comments found - file GitHub issues instead\"\n    exit 1\nfi\n```\n\n## STEP 18: BOOK-SPECIFIC CLAUDE.MD\n\n**Create comprehensive CLAUDE.md for book:**\n\n```markdown\n# CLAUDE.md\n\n## Prime Directive\n\n**Generate correct documentation where every example works on first attempt. Quality is built-in, not bolted-on.**\n\n## MANDATORY Development Approach (BLOCKING)\n\n### A. Test-Driven Documentation (TDD)\n- **ALL work must be TDD**: Every example written test-first\n- **NO exceptions**: Documentation follows working code\n- **Immediate feedback**: Tests run continuously\n\n### B. Quality Gates with ${QUALITY_TOOL}\n- **Minimum grade**: B+ required on all examples\n- **BLOCKING gate**: No commits without quality approval\n- **Automated**: Pre-commit hooks enforce standards\n\n### C. ${MIN_PASS_RATE}% Pass Rate Mandatory\n- **Minimum pass rate**: ${MIN_PASS_RATE}% of all examples must pass\n- **Test coverage**: Every code example has automated test\n- **No partial examples**: All examples complete and working\n\n## Quality Standards (BLOCKING)\n\n- Test Coverage: 100% of examples\n- Pass Rate: ≥${MIN_PASS_RATE}%\n- Link Validation: All links valid\n- SATD Count: 0\n- Vaporware: 0 unimplemented features documented\n- Build Success: mdBook builds without errors\n\n## TDD Workflow (MANDATORY)\n\n1. Write test FIRST (RED phase)\n2. Write documentation with working example (GREEN phase)\n3. Update chapter status blocks\n4. Run quality gates\n5. Commit only when all tests pass\n```\n\n## TOYOTA WAY PRINCIPLES FOR BOOKS\n\n- **Jidoka (Built-in Quality)**: Automated tests prove examples work\n- **Andon Cord**: Stop immediately when examples break\n- **Genchi Genbutsu (Go & See)**: Test every example in real environment\n- **Kaizen**: Continuously improve documentation based on user feedback\n- **Zero Defects**: No broken examples in production book\n\n## WORKFLOW SUMMARY FOR BOOKS\n\n1. **Setup**: mdBook structure + book.toml + SUMMARY.md\n2. **Test Infrastructure**: tests/ directory with chapter-based tests\n3. **TDD Loop**:\n   - Write test (RED)\n   - Write documentation with working example (GREEN)\n   - Update status blocks\n   - Validate quality\n4. **Quality Gates**: All tests pass, minimum pass rate, no vaporware\n5. **Build**: `make build` produces book/index.html\n6. **Deploy**: GitHub Actions → GitHub Pages\n7. **Version**: Track tool version in all chapters\n\n## BOOK SUCCESS CRITERIA\n\n- ✅ All code examples tested before documenting\n- ✅ Minimum ${MIN_PASS_RATE}% pass rate achieved\n- ✅ SUMMARY.md complete and accurate\n- ✅ Chapter status blocks up to date\n- ✅ No vaporware (zero unimplemented features)\n- ✅ No SATD comments (TODO, FIXME, HACK)\n- ✅ All internal links valid\n- ✅ Book builds successfully with mdBook\n- ✅ Deployed to GitHub Pages\n- ✅ CI/CD pipeline green\n\n## ERROR HANDLING FOR BOOKS\n\n**If tests fail**:\n```bash\n# DON'T document the broken example\n# FIX the code first, then update documentation\nbash tests/ch01/test_example.sh  # MUST pass before documenting\n```\n\n**If pass rate below minimum**:\n```bash\n# Add more tests or fix broken examples\n# DO NOT lower the minimum pass rate\nmake test-all-chapters  # Keep running until ≥${MIN_PASS_RATE}%\n```\n\nThis systematic approach ensures every technical book is:\n- Comprehensive (400-1000 pages)\n- Accurate (all examples tested)\n- Production-ready (deployed to GitHub Pages)\n- Professional quality (print-ready standards)\n- Zero defects (TDD prevents broken examples)\n"
methodology: EXTREME TDD + Documentation-as-Code + mdBook Standards
constraints:
- must use mdBook format with book.toml
- all code examples must be tested before documenting
- minimum 90% pass rate for all examples
- SUMMARY.md must be correct and complete
- chapter status tracking mandatory
- zero vaporware tolerance
- no SATD comments allowed
heuristics:
- test every code example before documenting
- maintain chapter status blocks
- use consistent formatting across chapters
- cross-reference related chapters
- dogfood your own tools (if applicable)
- deploy to production (GitHub Pages)
toyota_way_principles:
  andon_cord: stop_when_examples_break
  genchi_genbutsu: test_every_example_in_real_environment
  zero_defects: no_broken_examples_in_production
  jidoka: automated_tests_prove_examples_work
  kaizen: continuously_improve_based_on_feedback
quality_gates:
- test_coverage
- pass_rate
- link_validation
- satd_count
- vaporware_count
- build_success
- deployment_success
