Transcript To Notes

Transcript → GoodNotes Notes + XMind Mindmap

What This Skill Does

Given a raw course transcript file, produce:

1. <CourseName>_transcript_normalized.txt — normalized transcript copy used as the semantic source of truth
2. <CourseName>_concept_inventory.json — semantic concept inventory extracted from transcript + lesson map
3. <CourseName>_visual_briefs.json — mandatory per-lesson semantic visual briefs used by the Art Director phase before any sketch is drawn
4. <CourseName>_Flashcards.csv — mandatory active-recall export with header Front, Back, Tags (generated semantically from transcript + concepts)
5. <CourseName>_GoodNotes_detailed.md — ADHD-friendly handwritten study notes, chunked by video/lesson or micro-lesson when needed
6. <CourseName>_GoodNotes_detailed_A4.pdf — A4 PDF for GoodNotes import
7. <CourseName>_course_videos_clean.mm — semantic Freemind mindmap
8. <CourseName>_course_videos_fixed.xmind — semantic XMind mindmap (concept-enriched)
9. <CourseName>_narrative_manifest.json — semantic narrative manifest for v2 deck generation
10. <CourseName>_pitch_deck.html — mandatory v2 cinematic Reveal.js deck generated from the narrative manifest
11. <CourseName>_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 (auto-generated via content-to-sketch + compiler)
13. assets/INDEX.md — Visual reference guide with sketch metadata
14. <CourseName>_INDEX.md — Master topic index with all pages and key concepts
15. <CourseName>_AI_Elaboration.json or <CourseName>_AI_Elaboration.md — optional external AI synthesis for page-level elaboration used by the XMind enrichment step

All outputs go into a <CourseName>/ subfolder alongside the source transcript.

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.

Balanced Stack Multi-Model Orchestration Pipeline

Every run must execute this strict routed backend architecture:

1. Phase 1 (Ingestion and Bulk Extraction):
   • Route raw transcript 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 without context loss.
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, Excalidraw scene orchestration, PNG compilation linkage, flashcard CSV compilation, and flawless XML serialization for XMind.
   • Run the Semantic Depth Quality Gate on every Level 1 and Level 2 concept before finalizing output.
3. Phase 3 (AI Elaboration and Lateral Analysis):
   • Fork clean conceptual outputs to an advanced reasoning model (for example GPT-5 or equivalent).
   • Generate <CourseName>_AI_Elaboration.json by extrapolating edge cases and downstream implications without hallucination or source-text repetition.

Semantic Depth Quality Gate (Validation Step)

Apply this gate inside Phase 2 for all Level 1 and Level 2 concepts.

Triad Test (mandatory):

• What: clear definition of the concept.
• How: functional mechanism or execution behavior.
• Why: rationale, trade-off, or impact.

If any concept contains only definition-level content and misses mechanism or rationale, the gate fails. When the gate fails, re-process transcript extraction for that concept and regenerate until all three triad dimensions are explicitly present.

Full-Course Coverage Gate (Hard Stop)

Never ship a partial smoke output.

Mandatory minimums before completion:

• Detect total lesson count from transcript markers (for example --- Lesson ---).
• Notes page count must be greater than or equal to detected lesson count.
• Mindmap Level 1 lesson nodes must be greater than or equal to detected lesson count.
• Flashcards must include at least one card per lesson.
• PNG coverage must be at least one visual per lesson by default.

If lesson boundaries are ambiguous:

• Use section-level chunks, and explicitly document the reason.
• Still generate a minimum of 12 PNGs for medium/large courses.

Completion must fail if:

• Page count is materially below lesson count.
• Output only covers intro/first module while transcript includes additional modules.
• PNG count is trivially low relative to detected course breadth.

Universal Cognitive Hooks (Required In All Modes)

Apply these hooks in both --standard and --adhd modes, regardless of archetype.

1. Real-World Anchoring:
   • Every core concept must start with a concrete 1-2 sentence industry scenario before abstract theory.
2. Mental Models and Analogies:
   • Complex architectural or procedural concepts must include a short, relatable analogy.
3. Visual Memory Hooks:
   • Do not rely only on ASCII.
   • Generate rich descriptive image prompts optimized for image generation models (for example Gemini or Midjourney) or map directly to the content-to-sketch PNG pipeline.
   • Embed the visual placeholder inline with the concept flow in markdown.

Dynamic Content Archetype Classification

Classify each lesson 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

Never mix node sets across archetypes for the same lesson.

ADHD-Friendly Handwritten GoodNotes Design

What's Included for ADHD Brains

• Micro-chunking: Keep each page to a 3-5 minute read; split long lessons into multiple micro-pages
• Handwritten aesthetic: GoodNotes-style notes that feel personal and approachable
• Sepia paper background: Warm aged-paper tone with handwritten fonts for authentic GoodNotes import
• Frequent visual breaks: ASCII diagrams, tables, icons, and sketches instead of dense prose
• Index-first navigation: begin the notebook with a quick index page so readers can jump directly to the needed lesson
• Progressive challenge ordering: group foundational pages before advanced pages to reduce overwhelm without adding metadata headers to every page
• Action-first structure: Put practical use before abstract explanation
• Active recall built in: Quick recall questions on every lesson, exported to CSV
• Whitespace heavy formatting: Keep pages breathable and scannable
• Concrete examples first: Use real scenarios before theory
• Progress signals: Checkboxes and small completion markers for momentum

What's Avoided

• Long paragraphs or lecture-style dumps
• Multiple new ideas packed into one bullet
• Abstract wording without examples
• Open-ended review advice like "revise later"
• Large blocks of uninterrupted text
• Passive explanations that hide the point

Visual Style Default

• Use clean whiteboard-style visual backgrounds for generated sketches (no grid).
• Generated sketch visuals embedded in markdown/PDF should not include grid backgrounds.

Workspace Layout

smart-study-notes/
├── <CourseName>/
│   ├── <source_transcript>.txt       ← input
│   ├── <CourseName>_Flashcards.csv
│   ├── <CourseName>_GoodNotes_detailed.md
│   ├── <CourseName>_GoodNotes_detailed_A4.pdf
│   ├── <CourseName>_course_videos.mm
│   ├── <CourseName>_course_videos_clean.mm
│   ├── <CourseName>_course_videos_fixed.xmind
│   ├── <CourseName>_INDEX.md         ← master topic index
│   └── assets/                          ← auto-generated sketches
│       ├── <CourseName>_ProcessFlow_sketch.png
│       ├── <CourseName>_KeyConcept1_sketch.png
│       ├── <CourseName>_KeyConcept2_sketch.png
│       ├── INDEX.md                  ← visual reference guide
│       ├── validate_pngs.ps1          ← validation script
│       └── validation_report.txt     ← quality report
├── scripts/
│   ├── md_to_pdf_a4.py               ← reusable: Markdown → A4 PDF
│   └── generate_valid_xmind.py       ← semantic .mm → .xmind converter
└── copilot-skills/skills/transcript-to-notes/

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: lesson inventory must be present and non-empty.
• B after Step 2 preflight: each lesson must include mechanism, archetype, analogy, label-fusion intent, and composition intent.
• C after Step 2 generation: visuals must not be template clones across lessons (concept-specific variation required).
• D after Step 2 validation: PNG count must be >= lesson count and all PNGs must pass integrity checks.
• E after Step 3: notes must be non-empty, page count >= lesson count, and required sections must be present.
• F after Step 4: .mm must parse and Level 1 lesson nodes must be >= lesson count.
• G after Step 5: .xmind must exist and be valid.
• H after Step 6.6: flashcards CSV header and minimum lesson coverage rules must pass.
• I after Step 7: index TOC row count must be >= lesson count.
• J after Step 8: PDF must exist and be non-trivial (not blank output).
• 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 (what constitutes PASS/FAIL).
• Include rollback/retry strategy for the first failed checkpoint.
• Record the plan in <CourseName>/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.

Fail-fast enforcement for Step 0:

• If P fails, do not run Step 1.
• Stop immediately and fix the plan first.

Step 1 — Read the Transcript

• Read the .txt file in full
• Identify video/lesson boundaries (look for "Video N:", timestamps, or heading markers)
• Note course name, module structure, and key themes
• Flag dense lessons that should be split into multiple micro-pages instead of one long page
• Identify practical examples, repeated terms, and likely memory bottlenecks

Coverage requirement:

• Build an explicit lesson inventory table during ingestion: Section, Lesson, Order.
• Use this inventory as the source of truth for page counts, mindmap Level 1 nodes, flashcards, and PNG counts.

Checkpoint A:

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

Step 1.5 — Generate Semantic Lesson Briefs Before Any Sketching

Create <CourseName>_visual_briefs.json from the transcript + lesson inventory.

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

Every lesson brief must include:

• lessonTitle
• lessonSlug
• 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:

• Final notebook pages are not required yet.
• Full semantic understanding is required before image generation.
• If a lesson 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 lesson 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 (Step 3), .mm (Step 4), .xmind (Step 5), and the narrative manifest (Step 5.5).

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

• Art Director metaphor extraction preflight (mandatory before any diagram is drawn)
• Excalidraw JSON generation with required style contract (roughness, hachure, Virgil, palette)
• Headless compilation via scripts/compile-excalidraw.js → .png
• All validation gates

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

• Input: the corresponding object from <CourseName>_visual_briefs.json — not just the lesson title
• Output target: <CourseName>/assets/<CourseName>_lesson<N>_<slug>.png
• Minimum: 1 PNG per lesson
• Archetype selection must be justified by the semantic visual brief and confirmed by the Art Director phase
• The brief must explicitly carry the lesson 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 source and one compiled .png per lesson.
2. Validate all PNGs:

for f in <CourseName>/assets/*.png; do python -c "from PIL import Image; import sys; Image.open(sys.argv[1]).verify()" "$f" && echo "✓ $f"; done

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 "<CourseName>/assets" \
  --report "<CourseName>/assets/validation_report.txt"

4. Record the confirmed filename list — used verbatim in Steps 3, 4, 5, and 5.5.
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 lesson briefs and let it regenerate the entire affected lesson set.
• Treat direct, one-off diagram edits as exceptions only after the skill pipeline passes all gates.
• If a sketch could plausibly fit any random lesson with only label changes, treat that as a semantic failure and regenerate.

Gate: Do not proceed to Step 3 until the content-to-sketch skill has completed and every lesson has at least one validated PNG in assets/.

Checkpoints C, D:

• C PASS only when lesson visuals are not near-identical templates and visibly encode the lesson 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 lesson pages. If a lesson is dense, split it into 2-3 micro-pages. Use this exact structure:

-- Page 1: Course Index

## Course Map
| Page | Lesson | Core Focus |
|---|---|---|
| 2 | <Lesson 1> | <Core concept> |

## How to Use This Notebook
- Start with the lesson that matches your immediate problem.
- Use the visual sketch first, then the deep dive, then the try-this block.
- Use `<CourseName>_INDEX.md` for the full cross-reference and glossary.

## Fast Lanes
- Core architecture pages
- Process-heavy pages
- Comparison or trade-off pages

-- Page N: <Video Title or Micro-Lesson>

## Real-World Anchor
Scenario: <1-2 sentence industry scenario>

## What You'll Learn
(1 sentence on why this matters to the learner right now)

## Deep Dive Explanation
- Explain the mechanism in 2-4 concrete bullets
- Add at least one cause-and-effect relationship
- Include one concrete example tied to the lesson

## Mental Model / Analogy
Think of this like: <short relatable analogy>

## Visual Summary
(ASCII diagram, compact table, flowchart, and inline visual placeholder)

## Visual Sketch
![Sketch](./assets/<CourseName>_lesson<N>_<slug>.png)

## Real-World Use First
Scenario: ...
Why it matters: ...

## Process Flow / Steps
1. Step one
2. Step two

## Key Concepts
- **Term**: definition in simple words
- **Term**: definition in simple words

## Try This Right Now
- 30-second action
- Observable result

Separate pages with -- on a line by itself (used as page delimiter by the PDF script).

Formatting rules for every page:

• Keep bullets short and concrete
• Put the real-world example before deeper explanation
• Use icons and whitespace for quick scanning
• Keep jargon paired with plain-English meaning
• Prefer one idea per bullet
• Make remaining sections elaborative with mechanism, rationale, and impact details
• 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/ (generated in Step 2) — never write a placeholder.
• In --adhd mode, do not include sections named Header, Active Recall Prompts, or One-Page Revision.
• Do not include markdown flashcard tables in the notebook schema.
• Export all cards directly into <CourseName>_Flashcards.csv from page content anchors.

Checkpoint E:

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

Step 4 — Create Freemind Mindmap (.mm)

See mindmap format reference.

Build a hierarchical XML Freemind file:

• Root node: course name
• Level 1: page/lesson titles
• Level 2: use only the mandatory node set for the assigned archetype (Type A, Type B, or Type C)
• Level 3+: elaborative subnodes from page content

Archetype requirements:

• Type A must contain exactly:
  • Core Architecture Blueprint
  • Core Components & Governance
  • Key Integration Points
  • Systemic Trade-offs
• Type B must contain exactly:
  • Execution Pipeline / Steps
  • Environment Prerequisites & Setup
  • Failure Recovery & Verification
  • Performance Optimizations
• Type C must contain exactly:
  • Functional Mechanics
  • Concrete Configuration & Code Snippets
  • Edge Cases & System Constraints

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 (for example: "What you'll learn", "Why it matters", "In summary, you'll learn", presenter instructions, or audience prompts). Do not add One-Page Revision nodes to the mindmap. Make Level 3+ child nodes complete, context-rich phrases (not terse labels).

Critical: escape ALL & as & in node TEXT attributes. No bare & allowed.

Checkpoint F:

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

Step 5 — Convert .mm → .xmind

Run the converter script (uses Python venv):

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

Or use the inline procedure in xmind-conversion reference.

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 <CourseName>/<CourseName>_narrative_manifest.json from:

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

Use the shared extraction prompt template:

• skills/xmind-notes-to-deck-v2/templates/narrative_manifest_prompt_template.md

Use the shared JSON skeleton:

• skills/xmind-notes-to-deck-v2/templates/narrative_manifest.template.json

Strict JSON contract (must be exact):

• deckTitle (string)
• deckSubtitle (string)
• slides (array)
  • slideId (string slug)
  • visualArchetype (one of: split-screen-analogy, hero-metric, execution-pipeline, technical-deep-dive)
  • pacingSeconds (integer speaking estimate)
  • speakerProtocol object:
    • hook
    • teleprompterVO
    • stageDirections
    • theDelta
  • blocks (array of { title, bodyText, items })
  • visuals (array of local assets/image paths)

Scriptwriter mandate for speakerProtocol:

• teleprompterVO: write for the ear, short punchy sentences, add narrative context, do not read slide bullets verbatim.
• hook: first 3 seconds must bridge from the previous slide.
• theDelta: explicitly state the architectural Why not written on screen.
• stageDirections: include when to trigger GSAP fragment clicks.

PNG mapping mandate:

• For core concept slides, map local sketch paths into visuals, for example:
  • "./assets/ConceptName_sketch.png"

Cognitive load guardrail:

• Never create wall-of-text slides.
• If a concept needs more than 3 bullet points or more than 40 words of text, split it into two consecutive slide objects.

Quick starter template:

cat > "<CourseName>/<CourseName>_narrative_manifest.json" <<'JSON'
{
   "deckTitle": "<CourseName>",
   "deckSubtitle": "AI-Narrative Deck",
   "slides": [
      {
         "slideId": "intro-01",
         "visualArchetype": "split-screen-analogy",
         "pacingSeconds": 40,
         "speakerProtocol": {
            "hook": "Bridge from prior slide in the first sentence.",
            "teleprompterVO": "Short spoken narrative that explains context without reading bullets.",
            "stageDirections": "Click next fragment after key contrast line.",
            "theDelta": "State the architectural why that is not on the screen."
         },
         "blocks": [
            {
               "title": "Core Concept",
               "bodyText": "Summarize one concept using source-faithful language.",
               "items": ["Signal 1", "Signal 2", "Signal 3"]
            }
         ],
         "visuals": ["./assets/CoreConcept_sketch.png"]
      }
   ]
}
JSON

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 "<CourseName>/<CourseName>_narrative_manifest.json" \
  --out "<CourseName>/<CourseName>_pitch_deck.html" \
  --script-out "<CourseName>/<CourseName>_Teleprompter_Script.md"

Hard rule:

• transcript-to-notes must invoke xmind-notes-to-deck-v2; manifest generation alone is not considered complete.
• No fallback deck workflow is allowed.
• If v2 skill folder, manifest, deck HTML, or teleprompter script is missing, fail the run and regenerate missing semantic artifacts.

Step 6 — PNG Generation Reference (Delegated)

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

Rules:

• Do not duplicate, fork, or partially reimplement the sketch-generation logic in this skill.
• Use the confirmed artifact list from Step 2 (assets/INDEX.md + validated PNG list) as the only source for embeddings.
• If quality fails, return to Step 2 and regenerate through content-to-sketch instead of editing local diagram files directly.

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 GoodNotes markdown text.

This can be done for all notes in the course, not just a subset. The goal is to produce a page-by-page elaboration layer that complements every lesson page.

Suggested AI prompt to use:

You are generating highly targeted, page-level AI elaboration for a student course notes package.

Input Sources:
- GoodNotes markdown pages (containing handwritten/typed course notes)
- assets/index metadata when available
- Optional chapter/page index

Task:
For every page in the course, analyze the core academic concept and synthesize 1 to 10 highly specific elaboration lines. Your objective is to deepen the user's understanding of the concept without echoing what is already written.

Strict Formatting Rules:
1. JSON Output (Default): Output a single valid MINIFIED JSON object (no extra whitespace/newlines beyond what JSON requires) following this exact structural taxonomy per page:
{
   "pages": {
      "1": {
         "Concept Focus": ["Define the core underlying theory or mechanism in 1 sentence"],
         "Connecting Dots": ["Cross-reference this concept to a prior page or related course theme"],
         "Same Idea, Applied Elsewhere": ["Provide a concrete, real-world industry or academic application"],
         "Implications": ["Explain the downstream effect, practical outcome, or why this matters"],
         "Edge Case": ["Detail a specific scenario where this concept breaks down or behaves differently"]
      }
   }
}
2. Markdown Output (Only if explicitly requested): Keep the same structural taxonomy using a heading per page (e.g., "## Page 1") followed by prefix-led bullets that map to the same dimensions.
3. Universal Scope: Include every single page from the input source in the output. If a page contains low information density or simple diagrams, output exactly one line using the "Concept Focus:" prefix.

Strict Content Constraints:
- Zero Verbatim Repetition: Never reuse strings, phrases, or explicit definitions from the source notes.
- Ban Meta-Headings: Never restate or mirror structural headings from the input (e.g., "Scenario", "Why it matters", "In summary").
- Anchor to Evidence: Every elaboration line must be heavily anchored in the specific page content. Do not use generic filler, broad definitions, or introductory phrases.
- Zero Schema Deviation: Do not invent new prefixes. Stick exclusively to the five specified structural anchors: Concept Focus, Connecting Dots, Same Idea (Applied Elsewhere/Different Layer), Implications, and Edge Case.
- Do NOT include empty arrays for dimensions that have no insights on a given page; omit the dimension key entirely to keep the payload clean.

Synthesis Criteria and Labels:
- Every dimension key must map to an array of strings.
- If a specific dimension has multiple distinct points, include each point as its own array item under that same dimension.

Example Dimension Formatting:
- "Implications": ["Main downstream impact point"]
- "Implications": ["First distinct downstream impact", "Second distinct downstream impact"]

Output Format:
```json
{
   "pages": {
     "1": {
        "Concept Focus": ["Core technical anchor of the page"],
        "Implications": [
           "Increased memory usage during high-concurrency states",
           "Higher CPU overhead due to constant cache misses"
        ],
        "Edge Case": ["Fails silently when system clock drifts by >50ms"]
     },
     "2": {
        "Concept Focus": ["Core technical anchor of the page"],
        "Connecting Dots": ["Links local variables to global state mutations"]
     }
   }
}

Recommended format:
- **JSON**: `<CourseName>_AI_Elaboration.json`
- **Markdown**: `<CourseName>_AI_Elaboration.md`

Recommended page-scoped structure:
```json
{
   "pages": {
      "1": {
         "Concept Focus": ["..."],
         "Connecting Dots": ["..."],
         "Same Idea, Applied Elsewhere": ["..."],
         "Implications": ["...", "..."],
         "Edge Case": ["..."]
      },
      "2": {
         "Concept Focus": ["..."],
         "Same Idea, Different Layer": ["..."],
         "Implications": ["..."]
      }
   }
}

Rules:

• Keep the elaboration separate from the main GoodNotes markdown.
• Use concise, page-specific synthesis instead of repeating the note text.
• Prefer JSON if the content is generated by another tool or model.
• The XMind converter will auto-detect this file when it sits beside the course files.
• If you generate it for the whole course, include an entry for every page, even if some pages only need a short Concept Focus line.

Common PNG issues to fix:

• Escape & as & in text
• Use XML entities for special characters
• Ensure all tags are properly closed

Step 6.6 — Extract Flashcards CSV (Mandatory)

Create a raw CSV file named <CourseName>_Flashcards.csv semantically from transcript + concept inventory + mindmap relationships. Do not derive flashcards from ADHD notes formatting.

Generation method (AI-authored, no script):

• Use the lesson inventory + mindmap concept graph to draft active-recall cards directly.
• Keep flashcard generation independent of ADHD note formatting sections.

Density-driven generation policy (recommended default):

• Generate flashcards grouped by transcript section markers (=== Section ===) and lesson markers (--- Lesson ---).
• Card volume must be lesson-density driven, not fixed per section.
• Default density targets:
  • low-density lesson: 3-5 cards
  • medium-density lesson: 10-25 cards
  • high-density lesson: 25-30 cards (soft cap)
• For very dense lessons, add +10 cards for each additional density layer above the soft cap threshold.
• Ensure each lesson includes mixed recall types:
  • concept/purpose
  • mechanism/process
  • scenario application
  • comparison/trade-off
  • sequencing/order
  • exam-style best-next-action and distractor elimination
• For TOGAF practitioner preparation, bias at least 2 cards per lesson toward Part 2 scenario judgment.
• Add both tags to each card:
  • section:<section-slug>
  • lesson:<lesson-slug>

CSV schema rules:

• Exact header must be: Front, Back, Tags
• Include one row per active-recall card across all pages
• Keep tags concise and reusable (for example: agent-loop, tool-calls, architecture)

Formatting rule (mandatory):

• If Front or Back contains commas, wrap that field in double quotes.
• Escape internal double quotes in CSV fields by doubling them.

Card quality rules (mandatory):

• Do not use a single repeated question stem for all rows.
• Rotate at least 4 recall types across the deck, such as:
  • definition/purpose
  • sequence/order
  • application/scenario
  • comparison/trade-off
  • artifact/output identification
• Keep each Back answer anchored to the corresponding lesson content; avoid generic boilerplate reused across many cards.
• Add one lesson-specific anchor phrase in each answer (for example a phase name, artifact, technique, exam rule, or explicit term from that lesson).
• Do not write vague stems such as what does this section or what does this section reduce without lesson context.
• Every question must include at least one explicit lesson anchor (lesson title, phase name, technique name, or architecture artifact term).
• Add lesson tags in the form lesson:<lesson-slug> in addition to section:<section-slug>.
• Use a density-layer:<n> tag when adaptive layering is used for card expansion.
• Hard fail if more than 25% of cards share the exact same question pattern or near-identical answer body.
• Hard fail if any parsed lesson has fewer than 3 cards.

Checkpoint H:

• PASS only when CSV header is exact and per-lesson minimum card rules pass.
• FAIL on header mismatch, weak coverage, or repeated boilerplate patterns.

Example:

Front,Back,Tags
"What is the role of a planner in an agent loop?","It sequences tasks, validates prerequisites, and prevents out-of-order execution.","agent-loop,planning"
"Why use schema validation, even when outputs look correct?","Validation catches structural drift, improves import reliability, and reduces downstream repair work.","validation,reliability"

Step 7 — Generate Topic Index

Create <CourseName>_INDEX.md inside the course folder. This file is a master index of everything in the notebook.

Structure:

# <CourseName> — Topic Index

> Quick-navigation index for all pages, concepts, and review items.

## Table of Contents
| # | Page Title | Difficulty | Topics Covered |
|---|-----------|-----------|----------------|
| 1 | Page 1 title | Easy | topic A, topic B |
| 2 | Page 2 title | Medium | topic C |
...

## All Key Concepts (A–Z)
Alphabetically sorted master glossary:
- **ConceptName** — one-line plain-English definition *(Page N)*
- **ConceptName** — ... *(Page N)*

## Flashcard Export
Use `<CourseName>_Flashcards.csv` as the canonical active-recall source.
Recommended quick summary in index:
- Total cards: <count>
- Tag groups: <tag1>, <tag2>, <tag3>

## Quick-Find by Topic
Group-by-theme cross-reference (manually assigned to broad themes):
### <Theme 1>
- Page N: page title — key concept
- Page N: page title — key concept
### <Theme 2>
- ...

Rules:

• Table of Contents must list every page (1 row per page)
• Key Concepts A–Z: collect all bolded terms from all pages, de-duplicate, sort alphabetically
• Flashcard export: reference <CourseName>_Flashcards.csv and include total card count + top tag groups
• Quick-Find groups: assign pages to 3-6 broad themes based on content

Checkpoint I:

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

Step 8 — Export A4 PDF

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

The PDF will include embedded PNG sketches from the markdown.

Checkpoint J:

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

Step 9 — Move Files Into Course Folder

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

Python Environment

• Virtualenv: .venv at workspace root
• Required packages: reportlab, markdown, xmind-sdk
• 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) — no [Visual Placeholder] lines in final notes
• Every lesson has at least one compiled PNG in assets/ with a validated path
• PNG paths embedded in notes, .mm nodes, XMind attachments, and narrative manifest visuals[] all resolve to real files
• Notebook begins with a dedicated index page before lesson pages
• Each short lesson is 1 page; long lessons are split into 2-3 micro-pages
• Every page has: Real-World Anchor, What You'll Learn, Deep Dive Explanation, Mental Model/Analogy, Visual Summary
• No ADHD page includes sections named Header, Active Recall Prompts, or One-Page Revision
• Bullets are short, concrete, and one idea each
• Real-world example appears before abstract explanation
• ASCII diagrams or tables appear on the core concept pages
• Visual prompt/placeholder is embedded inline for each core concept page
• GoodNotes visual style uses sepia tone background with handwritten fonts
• All Level 1 and Level 2 concepts pass the Triad Test (What, How, Why)
• Mindmap .mm passes python -c "from PIL import Image; import sys; Image.open(sys.argv[1]).verify()" without errors
• .xmind opens in XMind without "not a valid XMind File" error
• PDF page count matches Markdown page count
• No page exceeds roughly 5 minutes of reading time
• <CourseName>_INDEX.md exists in course folder
• Index Table of Contents has one row per note page
• Key Concepts A–Z covers all bolded terms from all pages
• <CourseName>_Flashcards.csv exists with exact header Front, Back, Tags
• CSV escaping rules are correctly applied for commas and quotes
• Flashcards use at least 4 distinct question patterns
• Flashcard answers are lesson-anchored, not repeated boilerplate
• Section tags exist in the form section:<section-slug>
• Lesson tags exist in the form lesson:<lesson-slug>
• Every parsed lesson has at least 3 cards
• Dense lessons show increased card counts via density layers (density-layer:<n>)

PNG Sketch Quality (content-to-sketch integration)

• PNG

…(truncated)