PDF To Notes

PDF Book → GoodNotes Handwritten Study Notes

What This Skill Does

Given a PDF book or large text, produce:

1. <BookName>_source_normalized.txt — normalized text extraction used as the semantic source of truth
2. <BookName>_concept_inventory.json — semantic concept inventory extracted from the PDF/book + chapter map
3. <BookName>_visual_briefs.json — mandatory per-chapter semantic visual briefs used by the Art Director phase before any sketch is drawn
4. <BookName>_Flashcards.csv — mandatory active-recall export with header Front, Back, Tags
5. <BookName>_GoodNotes_detailed.md — ADHD-friendly handwritten study notes, chunked by chapter/section or micro-section when needed
6. <BookName>_GoodNotes_detailed_A4.pdf — A4 PDF for GoodNotes import
7. <BookName>_book_mindmap_clean.mm — semantic Freemind mindmap
8. <BookName>_book_mindmap_fixed.xmind — semantic XMind mindmap (concept-enriched)
9. <BookName>_narrative_manifest.json — semantic narrative manifest for v2 deck generation
10. <BookName>_pitch_deck.html — mandatory v2 cinematic Reveal.js deck generated from the narrative manifest
11. <BookName>_Teleprompter_Script_<timestamp>.md — teleprompter script generated by xmind-notes-to-deck-v2
12. assets/ folder — Excalidraw source scenes (.excalidraw) plus compiled PNG sketches for key concepts
13. assets/INDEX.md — Visual reference guide with sketch metadata
14. <BookName>_INDEX.md — Master topic index with all pages and key concepts
15. <BookName>_AI_Elaboration.json or <BookName>_AI_Elaboration.md — optional external AI synthesis for page-level elaboration used by the XMind enrichment step

All outputs go into a <BookName>/ subfolder.

Systemic Execution Contract

Execution Modes

• --standard: output clean, hierarchical, engineering-focused outlines that map the exact technical architecture.
• --adhd: prohibit introductory summaries, conversational text, and sections titled Intro; require immediate visual memory hooks (ASCII tables/diagrams), bold technical syntax anchors, and real-world-use-first ordering. Also exclude sections named Header, Active Recall Prompts, and One-Page Revision from notebook pages.

Balanced Stack Multi-Model Orchestration Pipeline

Every run must execute this strict routed backend architecture:

1. Phase 1 (Ingestion and Bulk Extraction):
   • Route raw PDF/book input to a primary mid-tier extractor model (for example GPT-5.4 or another 1M+ context model).
   • Perform comprehensive fact extraction and archetype classification before formatting.
2. Phase 2 (Markdown and Schema Formatting):
   • Route the extracted conceptual payload to a strict coding/schema model (for example Claude Sonnet 4.6).
   • This phase is solely responsible for GoodNotes markdown formatting, PNG orchestration, and flawless XML serialization for XMind.
3. Phase 3 (AI Elaboration and Lateral Analysis):
   • Fork clean conceptual outputs to an advanced reasoning model (for example GPT-5 or equivalent).
   • Generate <BookName>_AI_Elaboration.json by extrapolating edge cases and downstream implications without hallucination or source-text repetition.

Dynamic Content Archetype Classification

Classify each chapter/section into one archetype before generating markdown pages or mindmap nodes. Use only the associated mandatory node set.

• Type A: Conceptual Architecture or Frameworks
  • Core Architecture Blueprint
  • Core Components & Governance
  • Key Integration Points
  • Systemic Trade-offs
• Type B: Procedural Workflows or Pipelines
  • Execution Pipeline / Steps
  • Environment Prerequisites & Setup
  • Failure Recovery & Verification
  • Performance Optimizations
• Type C: Discrete Technical Components or Tools
  • Functional Mechanics
  • Concrete Configuration & Code Snippets
  • Edge Cases & System Constraints

ADHD-Friendly Handwritten GoodNotes Design

✓ What's Included for ADHD Brains

• Micro-chunking: 3–5 min read per page (prevents hyperfocus derailment + working memory overload)
• Handwritten aesthetic: Warm, friendly fonts that feel personal and engaging
• Sepia paper background: Warm aged-paper tone with handwritten fonts for authentic GoodNotes feel
• Frequent visual breaks: Icons, ASCII diagrams, color-coded sections prevent text fatigue
• Index-first navigation: a dedicated notebook index page reduces search friction and supports non-linear study
• Progressive challenge ordering: foundational pages appear before advanced pages without adding metadata headers to every page
• Progress checkboxes: ✓ dopamine hits after each micro-section (engagement + completion feedback)
• Action-first approach: "Try This Right Now" before abstract explanation (executive scaffolding)
• Quick facts: Flashcard Q&A format forces active retrieval (combat working memory limits)
• Real-world examples first: Concrete scenarios before theory (interest-dependent attention)
• Hyperlinks + anchor navigation: Jump to topics non-linearly (supports scattered attention patterns)
• Emoji + icons: Visual cues for quick section identification (supports ADHD scanning)
• Whitespace heavy: Breathing room between concepts (reduces cognitive load)

✗ What's Avoided

• Long paragraphs (max 2–3 sentences per bullet)
• Abstract language without concrete examples
• Dense, wall-of-text sections that trigger avoidance
• Vague or open-ended learning goals
• Passive voice or hedging language ("might", "could")
• More than 1 idea per bullet point
• Review schedules that require memory ("study sometime next week")

Procedure

Mandatory Checkpoint Protocol (Fail-Fast)

Apply this protocol after each procedure step. Do not continue when a checkpoint fails.

Checkpoint format (required):

• CHECKPOINT <ID>: PASS - <brief reason>
• CHECKPOINT <ID>: FAIL - <brief reason>

Fail-fast rule (required):

• If any checkpoint is FAIL, stop immediately.
• Do not proceed to the next step.
• Do not attempt downstream regeneration until the failed step is fixed and re-validated.

Checkpoint map:

• P before Step 1: workflow plan exists and is approved before any generation starts.
• A after Step 1: chapter inventory must be present and non-empty.
• B after Step 2 preflight: each chapter/section must include mechanism, archetype, analogy, label-fusion intent, and composition intent.
• C after Step 2 generation: visuals must not be template clones across chapters.
• D after Step 2 validation: PNG count must be >= chapter count and all PNGs must pass integrity checks.
• E after Step 3: notes must be non-empty, page count >= chapter count, and required sections must be present.
• F after Step 4: .mm must parse and Level 1 chapter nodes must be >= chapter count.
• G after Step 5: .xmind must exist and be valid.
• H after Step 6.6: flashcards CSV header and minimum chapter coverage rules must pass.
• I after Step 7: index TOC row count must be >= page count minus the notebook index page.
• J after Step 8: PDF must exist and be non-trivial.
• K final: all checkpoints must be PASS.

Step 0 — Plan the Workflow Before Running

Create a short execution plan before any generation step runs.

Plan requirements:

• Include Inputs, Outputs, Dependencies, and Execution order.
• Include a per-step checkpoint expectation.
• Include rollback/retry strategy for the first failed checkpoint.
• Record the plan in <BookName>/checkpoints/workflow-plan.md.

Checkpoint P:

• PASS when workflow-plan.md exists and covers all procedure steps with checkpoint criteria.
• FAIL when planning is missing, incomplete, or execution starts before plan approval.

Step 1 — Read and Normalize the PDF/Book Source

• Extract the text from the PDF/book excerpt in full.
• Identify chapter, part, or major section boundaries.
• Note the document title, module structure, and key themes.
• Flag dense chapters that should be split into multiple micro-pages.
• Build an explicit lesson inventory table: Section, Chapter, Order.
• Write the normalized extraction to <BookName>_source_normalized.txt.

Coverage requirement:

• Use the chapter inventory as the source of truth for page counts, mindmap Level 1 nodes, flashcards, and PNG counts.

Checkpoint A:

• PASS when the chapter inventory exists and contains at least 1 detected chapter/major section.
• FAIL when boundaries are missing/ambiguous and inventory is empty.

Step 1.5 — Generate Semantic Chapter Briefs Before Any Sketching

Create <BookName>_visual_briefs.json from the extracted book text + chapter inventory.

This is the mandatory semantic bridge between source ingestion and image generation. Do not jump directly from chapter headings into sketch rendering.

Every chapter brief must include:

• chapterTitle
• chapterSlug
• archetype
• coreMechanism
• what
• how
• why
• realWorldAnchor
• mentalModel
• edgeCase
• primaryEntities
• primaryFlow
• mainConstraint
• tradeoff
• physicalAnalogy
• labelFusion
• compositionIntent
• hotPath
• secondaryPaths
• mustShow
• mustNotShow
• visualSceneType
• sceneObjects
• objectToConceptMap
• spatialLayout
• entryPoint
• exitPoint
• failureBranch
• comparisonAxis
• evidenceArtifact
• dominantMotion
• forbiddenTemplate
• objectPalette
• shapeQuota
• forbiddenGeometry
• labelBudget
• sceneTest
• silhouettePlan
• propDensity
• asymmetryPlan
• antiCardFraming
• sceneTexture
• premiumSceneTest
• diagramIntent
• formalFramework
• sceneFamilyCandidates
• selectedSceneFamily
• selectionReason
• formalCompanionSuggested
• salienceGoal
• silhouetteContrastRules
• propInventory
• textureInventory

Hard rule:

• Full final notes are not required yet.
• Strong semantic understanding is required before image generation.
• If a chapter cannot produce a strong visual brief, stop and deepen extraction before sketching.
• A title plus generic what/how/why summary is not enough; the brief must drive geometry, motion, object choice, visual salience, and scene-object diversity.
• Resolve diagramIntent, formalFramework, sceneFamilyCandidates, selectedSceneFamily, and selectionReason before finalizing visualSceneType.
• Prefer selecting visualSceneType and objectPalette from content-to-sketch/references/canonical-scene-families.md before inventing a new scene family.
• For final learner-facing visuals, also apply content-to-sketch/references/premium-sketch-language.md so the brief carries silhouette, prop-density, asymmetry, anti-card-framing, and scene-texture intent.
• When premium visuals are requested, structure the downstream render around content-to-sketch/references/premium-generation-playbook.md rather than jumping straight from brief text to final layout.
• If the concept clearly maps to a formal framework (for example C4, BPMN, sequence, state, Wardley, or service blueprint), record that choice even if the final output will be a semantic sketch.
• The final learner-facing image must not expose planning metadata such as scene names, mechanism lines, analogy lines, or must-show rules.

Checkpoint B:

• PASS only when every chapter has a complete semantic visual brief with mechanism, analogy, composition, and hot-path detail.
• FAIL when briefs are shallow, title-only, or generic.

Step 2 — Generate PNG Sketches (invoke content-to-sketch skill)

This step MUST run before notes, mindmap, or XMind generation. PNG filenames produced here are embedded directly into notes, .mm, .xmind, and the narrative manifest.

Invoke the content-to-sketch skill — do not reimplement its pipeline here. The skill owns:

• Art Director metaphor extraction preflight
• Excalidraw JSON generation with required style contract
• Headless compilation via scripts/compile-excalidraw.js → .png
• All validation gates

Brief to pass to content-to-sketch for each chapter:

• Input: the corresponding object from <BookName>_visual_briefs.json — not just the chapter title
• Output target: <BookName>/assets/<BookName>_chapter<N>_<slug>.png
• Minimum: 1 PNG per chapter
• Archetype selection must be justified by the semantic visual brief and confirmed by the Art Director phase
• The brief must explicitly carry the chapter mechanism, analogy, label-fusion plan, composition intent, hot path, main constraint, scene objects, scene type, object palette, shape quota, forbidden geometry, label budget, scene test, silhouette plan, prop density, asymmetry plan, anti-card-framing plan, scene texture, premium scene test, diagram intent, formal framework, scene-family candidates, selected scene family, selection reason, formal companion suggestion, salience goal, silhouette contrast rules, prop inventory, and texture inventory

After the skill completes:

1. Confirm assets/ folder exists with one .excalidraw and one .png per chapter.
2. Validate all PNGs with Pillow.
3. Run structural QA on .excalidraw sources (text containment + arrow hygiene):

node <path-to-copilot-skills>/skills/content-to-sketch/scripts/validate-excalidraw-quality.js \
  --dir "<BookName>/assets" \
  --report "<BookName>/assets/validation_report.txt"

4. Record the confirmed filename list — used verbatim in Steps 3, 4, 5, and 5.4.
5. assets/INDEX.md is created by the skill.

Flow integrity rule:

• Do not directly patch generated diagram files as the primary fix path.
• If visuals are weak or generic, re-run content-to-sketch with improved semantic chapter briefs.
• Treat direct, one-off diagram edits as exceptions only after the skill pipeline passes all gates.
• If a sketch could plausibly fit any random chapter with only label changes, treat that as a semantic failure and regenerate.

Checkpoints C, D:

• C PASS only when chapter visuals are not near-identical templates and visibly encode the chapter mechanism/analogy through scene-specific geometry, motion, object mapping, hot-path salience, clean connector routing, non-box object diversity, and premium sketch-language cues where required.
• C also requires structural QA with zero text-overflow errors and zero critical arrow endpoint-inside-node errors in assets/validation_report.txt.
• D PASS only when every required PNG exists and integrity validation passes.

Step 3 — Generate ADHD-Friendly GoodNotes Notebook

See handwritten-notebook-format-adhd.

The notebook must begin with a dedicated index page, then continue with chapter pages. If a chapter is dense, split it into 2-3 micro-pages. Use the same notebook structure contract as transcript-to-notes, adapted for chapters.

Required page sections:

• ## Real-World Anchor
• ## What You'll Learn
• ## Deep Dive Explanation
• ## Mental Model / Analogy
• ## Visual Summary
• ## Visual Sketch
• ## Real-World Use First
• ## Process Flow / Steps
• ## Key Concepts
• ## Try This Right Now

Formatting rules mirror transcript-to-notes:

• Keep bullets short and concrete.
• Put the real-world example before deeper explanation.
• Prefer one idea per bullet.
• Ensure every Level 1 and Level 2 concept passes the Triad Test (What, How, Why).
• Do not create sections titled Intro, Introduction, Core Idea, Quick Facts, or Common Mistakes.
• In --adhd mode, every page must start with an immediate visual memory hook.
• Embed the real PNG path from assets/ — never write a placeholder.
• In --adhd mode, do not include sections named Header, Active Recall Prompts, or One-Page Revision.
• Export all cards directly into <BookName>_Flashcards.csv from page content anchors.

Checkpoint E:

• PASS only when notes are non-empty, include required sections, and pages >= detected chapter count.
• FAIL if notes are placeholder-only or under-covered.

Step 4 — Create Freemind Mindmap (.mm)

See mindmap format reference.

Build a hierarchical XML Freemind file:

• Root node: book title
• Level 1: page/chapter titles
• Level 2: use only the mandatory node set for the assigned archetype
• Level 3+: elaborative subnodes from page content

Archetype requirements match transcript-to-notes exactly.

Do not include Flashcards as mindmap nodes. Never include nodes titled or themed as Flashcards, Q/A, Questions & Answers, Interesting Talking Points, Pitfalls & Clarifications, Narrative Flow, In This Section, or What You'll Learn. Never include instructional/meta coaching text as node content. Do not add One-Page Revision nodes. Make Level 3+ child nodes complete, context-rich phrases.

Critical: escape ALL & as & in node TEXT attributes.

Checkpoint F:

• PASS only when .mm parses and Level 1 chapter nodes >= chapter count.
• FAIL on XML parse errors or coverage mismatch.

Step 5 — Convert .mm → .xmind

Run the converter script (uses Python venv):

source .venv/bin/activate
python scripts/generate_valid_xmind.py <BookName>/<file>.mm <BookName>/<file>.xmind <BookName>/<BookName>_GoodNotes_detailed.md

Checkpoint G:

• PASS only when .xmind opens as a valid archive and conversion succeeds.
• FAIL on conversion error or invalid package.

Step 5.4 — Build Narrative Manifest for V2

Create <BookName>/<BookName>_narrative_manifest.json from:

• the final notes markdown
• the finalized .xmind blueprint
• generated PNGs in <BookName>/assets/

Use the shared extraction prompt template and JSON skeleton from xmind-notes-to-deck-v2.

Step 5.5 — Generate Pitch Deck (V2 Only)

After .xmind is produced and narrative manifest JSON is available, use v2 only.

Required (v2 manifest-first, mandatory invocation of xmind-notes-to-deck-v2):

cd skills/xmind-notes-to-deck-v2
npm run build
npm run deck -- \
  --input "<BookName>/<BookName>_narrative_manifest.json" \
  --out "<BookName>/<BookName>_pitch_deck.html" \
  --script-out "<BookName>/<BookName>_Teleprompter_Script.md"

Hard rule:

• pdf-to-notes must invoke xmind-notes-to-deck-v2; manifest generation alone is not considered complete.
• No fallback deck workflow is allowed.
• If v2 prerequisites, deck HTML, or teleprompter script are missing, fail the run.

Step 6 — PNG Generation Reference (Delegated)

PNG generation is fully delegated to content-to-sketch in Step 2.

Step 6.5 — Generate External AI Elaboration Artifact

Create a separate AI synthesis file when you want richer XMind elaboration that is not limited to the notebook markdown text.

Recommended format:

• JSON: <BookName>_AI_Elaboration.json
• Markdown: <BookName>_AI_Elaboration.md

Rules mirror transcript-to-notes.

Step 6.6 — Extract Flashcards CSV (Mandatory)

Create a CSV file named <BookName>_Flashcards.csv semantically from extracted book content + concept inventory + mindmap relationships.

Generation method and rules:

• Use the chapter inventory + mindmap concept graph to draft active-recall cards directly.
• Keep generation independent of notebook formatting sections.
• Exact header must be Front, Back, Tags.
• Add section:<section-slug> and chapter:<chapter-slug> tags.
• Hard fail if any parsed chapter has fewer than 3 cards.

Checkpoint H:

• PASS only when CSV header is exact and per-chapter minimum card rules pass.
• FAIL on header mismatch or weak coverage.

Step 7 — Generate Topic Index

Create <BookName>_INDEX.md inside the book folder.

Structure:

• title
• table of contents with one row per note page after the notebook index page
• All Key Concepts (A–Z)
• Flashcard export summary
• Quick-Find by Topic

Checkpoint I:

• PASS only when index TOC rows >= content page count.
• FAIL when index is incomplete.

Step 8 — Export A4 PDF

source .venv/bin/activate
python scripts/md_to_pdf_a4.py <BookName>/<file>.md <BookName>/<file_A4>.pdf

Checkpoint J:

• PASS only when PDF generation succeeds and output is non-empty.
• FAIL on blank/near-empty output.

Step 9 — Move Files Into Book Folder

Ensure all outputs are inside <BookName>/ and scripts remain in scripts/.

Python Environment

• Virtualenv: .venv at workspace root
• Required packages: reportlab, markdown, xmind-sdk, svglib, pypdf
• Install once: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
• Use the venv Python at .venv/bin/python — not the system Python

Quality Checklist

• Step 2 (PNG) runs before Step 3 (notes)
• Every chapter has at least one compiled PNG in assets/
• PNG paths embedded in notes, .mm, .xmind, and narrative manifest visuals[] all resolve to real files
• Notebook begins with a dedicated index page before chapter pages
• No per-page time/difficulty metadata header is emitted
• Every content page has: Real-World Anchor, What You'll Learn, Deep Dive Explanation, Mental Model / Analogy, Visual Summary
• <BookName>_INDEX.md exists in the book folder
• <BookName>_Flashcards.csv exists with exact header Front, Back, Tags
• <BookName>_pitch_deck.html exists
• teleprompter script exists for the generated deck

PNG Sketch Quality (content-to-sketch integration)

• PNG count is explicit or derived from topic count
• Every topic/chapter has at least one PNG
• All PNGs in assets/ with INDEX.md
• All PNGs pass structural image validation
• Each sketch has 15+ text labels
• Text labels stay inside intended containers (no overflow errors)
• Arrow endpoints attach to shape edges (no endpoint-inside-node errors)
• validation_report.txt shows 0 errors (warnings should be reviewed and reduced)

Completion and Validation Gate

Do not mark any run successful until all gates pass:

1. All generated PNG files pass strict image integrity checking.
2. All bare ampersands in .mm are escaped to &.
3. Semantic Depth Quality Gate passes for all Level 1 and Level 2 concepts.
4. <BookName>_Flashcards.csv is present with valid header and import-safe escaping.
5. Notes page count is greater than or equal to detected chapter count.
6. Mindmap Level 1 chapter nodes are greater than or equal to detected chapter count.
7. PNG count is greater than or equal to detected chapter count.
8. <BookName>_pitch_deck.html exists and is generated via xmind-notes-to-deck-v2.
9. A teleprompter script exists for the generated deck.
10. Checkpoints P through J are all PASS.
11. Final checkpoint K is PASS.

Related Skills

• content-to-sketch — Generates the PNG sketches (auto-invoked in Step 2)
• transcript-to-notes — Source of the canonical end-to-end step contract
• md-to-notes — Alternative for markdown input