Summarize Textbook

Summarize Textbook

Create source-grounded textbook summaries for any subject and, when requested, maintain them in a cumulative document without overwriting the user's work.

Required companion skills

• For PDF textbooks, use the available PDF skill and read its instructions before extracting or rendering pages.
• For DOCX creation or editing, use the available documents skill and complete its render-and-inspect workflow.
• For spreadsheets, slides, or other source formats, use the matching artifact skill.

Use this skill to coordinate textbook-specific scope, source verification, writing quality, and cumulative-document safety.

Workflow

1. Resolve scope

Determine from the request and local files:

• textbook source and edition;
• requested chapters or units;
• explicit exclusions, especially exercises, labs, appendices, or named units;
• output language, depth, and audience;
• whether to return chat text, create a guide, or edit an existing guide;
• whether subject-specific or exam-style examples are requested;
• whether local question papers or mark schemes are available and should control example selection;
• whether the output is an ordinary summary or student-facing exam review notes.

Prefer discovery over clarification. Inspect the project, table of contents, existing guide headings, and recent instructions. Ask only when two plausible choices would materially change the result.

Run scripts/textbook_inventory.py --root <project-root> when several candidate PDFs or DOCX files exist.

2. Establish the authoritative chapter map

Use the textbook table of contents to record each requested chapter's printed page range and source-file page range. Verify each range against the chapter-opening page and the first exercise or review page.

Never assume file page numbers equal printed page numbers. Account for covers, front matter, and scan offsets. Recheck irregular or scanned files at multiple points.

Maintain a task-local coverage ledger with requested and excluded chapters, source ranges, exercise boundaries, completion state, and output location. Do not place it in the final artifact unless requested.

3. Extract and read bounded source chunks

Extract only relevant ranges. Include chapter goals, explanatory text, representative examples, cautions, diagrams, and the chapter summary. Stop before exercises when the user says no exercises.

Inspect representative pages visually because extraction can lose diagrams, notation, code indentation, callouts, and page boundaries. If extraction is garbled, render affected pages, use OCR only when necessary, and flag remaining uncertainty instead of guessing.

3A. Run the reusable source pipeline when examples are required

Keep generated indexes in a task-local temporary directory, never beside or over the source files. All scripts accept arbitrary absolute or relative project paths and must not be edited for a course code, folder name, or exam series.

• Run the complete reusable pipeline: python scripts/run_review_pipeline.py --root <project-root> --output-dir <temp>/review-pipeline. Add --include-exercises only when textbook exercises are allowed.
• Inventory mixed projects: python scripts/textbook_inventory.py --root <project-root> --pretty.
• Extract page-marked source text and provenance: python scripts/extract_sources.py --root <project-root> --output-dir <temp>/sources.
• Build a paired past-paper and mark-scheme bank: python scripts/build_question_bank.py --manifest <temp>/sources/sources.json --role question-paper --role mark-scheme --output exam_bank.json --markdown exam_bank.md.
• Build the textbook example bank: python scripts/build_textbook_example_bank.py --manifest <temp>/sources/sources.json --output textbook_examples.json --markdown textbook_examples.md. Add --include-exercises only when textbook exercises are allowed.
• Render a suspicious source range: python scripts/render_source_pages.py <source.pdf> --pages <page-list> --output-dir <temp>/rendered.
• Crop a source-grounded figure, question, or solution: python scripts/crop_source_region.py <source.pdf-or-image> <output.png> --page <one-based-page> --bbox <left,top,right,bottom> --units relative.
• Audit the final exam-review DOCX: python scripts/audit_exam_notes.py <notes.docx> --expected-examples <count> --require-english-examples --require-bullets --forbid-labeled-bullets --require-word-equations --forbid-script-overrun --require-subpart-line-breaks --strict.

Treat the generated banks as search indexes, not authoritative transcriptions. Visually inspect every record marked needs_visual_review and every selected question containing formulas, tables, diagrams, or uncertain reading order. If no textbook examples are found, render or OCR the relevant pages and, when necessary, pass custom label patterns instead of inventing content.

3B. Prefer source screenshots before generated visuals

• For knowledge points, first crop a clear textbook diagram, method box, summary table, or worked procedure when it directly teaches the retained point.
• Preserve the source's notation and reading order. Crop tightly enough to remain legible at final DOCX size, but include headings, labels, legends, and conditions needed to understand the image.
• Use image generation only when no suitable textbook visual exists, the source visual is incomplete or unreadable, or a new explanatory diagram materially improves understanding.
• Never generate a paraphrased infographic merely to replace a clean, accurate textbook visual.
• Give every embedded image descriptive alt text. Use Source screenshot | <source> | <purpose> for textbook, question-paper, and mark-scheme crops, and Generated visual | <topic> for generated images.

4. Build a concept map

Organize the source into:

• core definitions and claims;
• formulas, syntax, structures, or processes;
• how and why the ideas work;
• relationships and contrasts;
• assumptions, boundary cases, and common errors;
• source-grounded illustrative examples;
• course or exam patterns only when requested;
• concise takeaways.

Read references/summary-quality.md before drafting.

5. Draft an original summary

Write in the requested language. Otherwise preserve the established language of an existing guide, or use the language of the latest request.

For ordinary summaries, paraphrase the textbook and do not copy long passages, exercise prompts, or answer keys. In student-facing exam-review mode, follow the source-question exception in references/exam-review-notes.md: reproduce the selected local textbook or past-paper question accurately while writing the explanation and solution independently. Preserve technical meaning, qualifiers, assumptions, exceptions, terminology, units, and valid domains.

Prefer this teaching order:

1. intuitive idea;
2. formal definition;
3. general structure, formula, or process;
4. illustrative example;
5. edge case or misconception;
6. compact takeaway.

Adapt the structure to the subject instead of forcing a programming or AP template onto every textbook.

For mathematical or statistical documents:

• Build formulas, symbolic derivations, hypotheses, integrals, fractions, roots, matrices, subscripts, and superscripts as editable Word equation objects (OMML) in DOCX output. Use rendered LaTeX only when the destination format natively supports it.
• Keep surrounding prose as ordinary text and place only the mathematical expression in the equation object.
• Apply the equation rule everywhere, including headings, captions, tables, callouts, checklists, exam tips, and mixed prose lines. A formula embedded in a sentence is still an equation object.
• Before Word BuildUp, group every subscript and superscript explicitly, including single-character scripts, and terminate the script before the next baseline term. Use boundary-safe linear input such as G_(X) (t), a^(2) Var(X), and n_(1) (N+1)/2; do not pass ambiguous input such as G_X(t), G_(X)(t), a^2Var(X), or n_(1)(N+1)/2. If a visible space would be typographically wrong, construct the OMML nodes directly instead of removing the boundary.
• After conversion, inspect the OMML structure as well as the rendered formula. A following function argument, multiplication factor, radical, fraction, equality, or right-hand side must be a sibling of m:sSub, m:sSup, or m:sSubSup, never a descendant of its m:sub or m:sup node.
• Do not leave pseudo-formulas such as sqrt(...), mu, chi-square=, +/-, >=, <=, !=, or prose such as integral from ... in the final document.
• Show concrete substituted equations and numerical working in solutions; a verbal description of the method alone is insufficient.
• After equation conversion, reapply the document font mapping, scan for unconverted formula text, and render the edited pages. Limit the conversion range exactly so a display equation cannot absorb the following paragraph.

6. Add examples using the correct source mode

For student-facing exam review notes, read references/exam-review-notes.md completely and follow it. Use one fully worked example for every retained knowledge point. When past papers are available, first rank the tested method families by frequency across independent sittings and variants, then choose a clean representative question from a high-frequency family. Do not choose a rare edge case merely because it is recent or easy to crop. Use a textbook worked example or exercise only when no suitable past-paper question exists. Prefer a legible crop of the original question and its official or textbook solution over retyping or paraphrasing them. For a past paper, pair the question-paper crop with the corresponding mark-scheme crop when available; add a concise English worked expansion when the official solution is absent or too compressed for students. Fall back to a fully typed example only when usable source crops cannot be produced. Keep any typed worked-example block fully English.

For every multi-part example, show each subpart on its own line or as its own vertically ordered crop. Label the corresponding solution and final answer with the same (a), (b) or (i), (ii) markers. Never pack multiple subparts or their answers into one paragraph.

Never apply a bullet style to a paragraph that already begins with a question or subpart label such as 1, (a), or (i). Use an ordinary paragraph for the labeled line; use bullets only for unlabeled supporting steps below it.

For ordinary summaries that are not exam-review documents:

• create original illustrative examples only when requested;
• do not imply that an original example is official;
• include explanations, traces, or derivations when they aid understanding;
• honor "no exercises" by giving illustrations rather than practice sets.

7. Update an existing guide surgically

For an existing DOCX:

• preserve manual edits, cover, styles, headers, footers, and unrelated chapters;
• make a task-named backup before editing;
• identify replacement boundaries by exact heading text, never paragraph indexes;
• replace only the requested range;
• append new chapters in source order unless the document requires insertion;
• reuse existing heading, body, list, formula, and code styles;
• update an existing coverage note when useful;
• verify the operation did not duplicate a chapter.

Read references/docx-workflow.md before cumulative DOCX edits.

8. Verify content and layout

Content checks:

• requested chapters appear exactly once;
• excluded chapters and exercises are absent;
• headings match the source or the user's naming system;
• formulas, code, examples, and claims are internally consistent;
• exam-review examples follow the required past-paper-first, textbook-second source rule and retain accurate question data;
• clean textbook visuals are reused before generated substitutes, and generated visuals are used only when the source lacks a suitable visual;
• examples use original question-and-solution screenshots when usable, with typed reconstruction only as a documented internal fallback;
• past-paper examples come from frequently tested method families, with duplicate or near-identical variants counted as one family rather than mistaken for independent evidence;
• multi-part questions, solutions, and answers are vertically separated and carry matching subpart labels;
• no question or subpart label is combined with a bullet marker;
• mathematical notation is stored as equation objects or native rendered LaTeX, with no residual pseudo-formula text;
• every subscript and superscript ends at the intended character or group; later baseline terms remain outside the script node;
• every retained exam-review knowledge point has one fully worked English example;
• statements remain grounded in the requested edition.

Document checks:

• the DOCX is valid OOXML;
• headings, lists, formulas, tables, and code use appropriate styles;
• no orphan heading, lone bullet, split short code block, clipping, or overlap appears;
• page numbers, headers, and footers remain correct;
• every page in the latest render is visually inspected.

If the standard DOCX renderer fails for an environment reason and Microsoft Word is available, export with Word to PDF, rasterize, and inspect the pages. Do not claim visual QA without inspecting a render.

9. Deliver clearly

Return only the requested artifact, not source extractions, backups, PNGs, or temporary PDFs. State what was added or replaced, what was intentionally excluded, whether exercises were omitted, the final file location, and whether visual verification passed.

Follow the documents skill's page-citation rules for edited DOCX files.

Guardrails

• Never summarize from memory when the source is available.
• Never silently switch editions or treat an old textbook requirement as current policy.
• Browse only when the user requests current external standards or a time-sensitive claim is required.
• Never overwrite the only user-edited guide without a backup.
• Never rebuild an entire DOCX to change one section.
• Never apply one subject's summary structure to every discipline.
• In exam-review mode, never invent an example when a relevant local past-paper or textbook example is available.
• Never retype a clean source question or solution when a legible source crop can be embedded.
• Never use image generation before checking the textbook for a suitable knowledge-point visual.
• Never leave multi-part questions or corresponding answers packed into one paragraph.
• Never combine a source question number or subpart label with a bullet marker.
• Never leave mathematical working as ASCII pseudo-notation when the output supports equation objects or rendered LaTeX.
• Never trust garbled PDF equation extraction when the source page can be rendered and inspected.
• Never deliver a cumulative guide without checking for duplicated or skipped headings.

Resources

• scripts/run_review_pipeline.py: one-command, course-independent orchestration of extraction and all available example banks.
• scripts/textbook_inventory.py: read-only discovery of textbook files and existing DOCX guides.
• scripts/extract_sources.py: page-marked PDF, DOCX, and text extraction with role classification, provenance, optional OCR, and visual-review flags.
• scripts/build_question_bank.py: past-paper and mark-scheme parsing, source pairing, page provenance, and extraction-risk flags.
• scripts/build_textbook_example_bank.py: textbook worked-example indexing and optional exercise-question indexing.
• scripts/render_source_pages.py: exact PDF page or page-range rendering for notation and layout verification.
• scripts/crop_source_region.py: crop a reusable, high-resolution source screenshot from a PDF page or image using pixel or relative coordinates.
• scripts/audit_exam_notes.py: structural DOCX audit for example count, English-only example blocks, bullets, fonts, headings, images, Word equations, residual pseudo-formulas, suspicious subscript/superscript scope overruns, and multi-part layout.
• scripts/requirements.txt: portable Python dependencies and optional OCR requirements.
• references/summary-quality.md: content architecture and subject-specific adaptations.
• references/docx-workflow.md: safe cumulative Word editing and pagination verification.
• references/exam-review-notes.md: mandatory source, language, typography, list, image, and QA contract for student-facing exam revision notes.