extract-book-rules

name	extract-book-rules
description	Extract source-faithful compact rules from programming or technical books supplied as PDF and/or ePUB files, then produce chapter-aligned JSON and Markdown rulesets. Use when the user asks to mine a book for explicit guidance, Clean Code-style rules, principles, recommendations, warnings, best practices, or similar rule extractions from PDF/ePUB sources.

Extract Book Rules

Core Workflow

1. Confirm inputs: book file paths, output directory, desired formats, and whether to follow book structure or reorganize later.
2. Extract source text. Prefer ePUB for chapter structure and PDF for page references.
3. Build a chapter index before extracting rules. Preserve the book's chapter order and titles.
4. Read chapter by chapter. Extract only author-backed guidance, not general model knowledge.
5. Write rules.json as the source of truth. Render Markdown from JSON using scripts/render_markdown.rb.
6. Validate JSON, Markdown, examples, code fences, duplicates, and renderer round-trip before reporting completion.
7. Do a final quality pass for usefulness: remove dump-like entries, expand why only from the book's reasoning, and add examples only when book-backed and helpful.

Omit chapters that yield no rules. Introductions, setup walkthroughs, glossaries, and similar book matter rarely produce actionable guidance; leave them out of rules.json rather than emitting empty rules: [] arrays. Preserve original chapter numbers for the chapters that remain so page references and codes still line up with the book.

Extraction Rules

• Treat advice as a rule when the author explicitly recommends, discourages, warns against, or demonstrates a preferred pattern.
• Do not require wording like "Rule:" or "Do this." Implicit guidance such as "avoid class variables" still counts.
• Split rules when they are independently actionable.
• Merge rules when they are tightly coupled and separating them would create repetition.
• Preserve the author's focus and constraints. Do not add outside opinions unless absolutely required to clarify mechanics.
• Prefer concise titles in imperative style.
• Keep examples compact and source-based. Do not invent framework-specific examples when the book did not support them.

Output Contract

Use the schema and Markdown format in references/rules-format.md.

Use the quality checklist in references/quality-checklist.md before final response.

Scripts

• scripts/extract_epub_chapters.rb EPUB_PATH OUTPUT_DIR: Extract chapter-like XHTML/HTML files from an ePUB into text files plus chapter_index.json.
• scripts/extract_pdf_pages.rb PDF_PATH OUTPUT_DIR: Extract PDF text with page files and a combined page-marked text file. Requires pdftotext.
• scripts/render_markdown.rb RULES_JSON [OUTPUT_MD]: Render Markdown from the JSON source of truth.
• scripts/validate_rules.rb RULES_JSON [RULES_MD]: Validate rule structure and, when Markdown is provided, verify it exactly matches renderer output.

Run Ruby scripts using mise when available, for example:

mise exec -- ruby scripts/validate_rules.rb rules.json rules.md

Reporting

Report the output paths, rule count, example count, validation result, and any known limitations. Do not commit, push, or create a repository unless the user explicitly asks.