final-exam-review

name	final-exam-review
description	Use when the user has course materials (PPT, textbook PDF, exam outline, exercise answers) in a directory and needs to compile a structured final exam review document. Triggers on "期末复习", "整理复习资料", "考试重点", "复习资料", or when user points to a directory with .pptx and .pdf course files and asks to organize study materials.

Final Exam Review Compilation

Overview

Converts scattered course materials into a structured, multi-format review package: Markdown document with traceable sources, Mermaid mind maps per chapter, professionally formatted PDF via Pandoc + XeLaTeX, and optional mock exam papers generated from verified exercise banks.

When to Use

digraph when_final_review {
    "User mentions review/exam prep?" [shape=diamond];
    "Directory has .pptx + .pdf files?" [shape=diamond];
    "Use this skill" [shape=box];
    "Ask user to clarify" [shape=box];
    "Not a review task" [shape=box];

    "User mentions review/exam prep?" -> "Directory has .pptx + .pdf files?" [label="yes"];
    "User mentions review/exam prep?" -> "Ask user to clarify" [label="no materials"];
    "Directory has .pptx + .pdf files?" -> "Use this skill" [label="yes"];
    "Directory has .pptx + .pdf files?" -> "Not a review task" [label="no"];
}

Trigger conditions:

• User says "期末复习", "整理复习资料", "考试重点", "出模拟卷"
• User has a directory with PPT courseware (.pptx) and/or textbook (.pdf)
• User provides exam outline or review scope documents

When NOT to use:

• Creating general study notes (not exam-focused)
• Single-file conversion tasks (just use markitdown directly)
• Research paper compilation (use scientific-writing)

5-Phase Workflow

Phase 0: SCAN    →  Detect exam structure from outline
Phase 1: EXTRACT →  PPT + PDF + DOCX → structured text via multi-engine pipeline
Phase 2: FUSE    →  Outline skeleton + PPT + textbook + exercises → verified document
Phase 2.5: REVIEW →  Critic scores each chapter (≥80/100 gate) → Reviser fixes low scores
Phase 3: ENHANCE →  Add mnemonics, analogies, drill problems to strengthen retention
Phase 4: OUTPUT  →  MD review doc + Mermaid mind maps + PDF + optional mock exam

Phase 0: Exam Structure Detection

Scan the directory for exam outline (复习题纲) and review scope documents. Extract:

1. Exam format: language, platform, duration
2. Question types: single/multiple choice, T/F, short answer, essay, current affairs
3. Distribution: how many questions per chapter per type
4. Key topics per chapter: page references from outline

Use the scanner script:

python3 scripts/scanner.py "<course_directory>"

This outputs config/exam-format.yaml and prints a summary table. If the outline PDF has garbled text (CMap encoding), the script falls back to image rendering + OCR.

Confirm with user before proceeding to Phase 1. Ask:

1. "Is this exam structure correct?"
2. "Any chapters or topics to prioritize/skip?"

Phase 1: Multi-Engine Material Extraction

Extract all materials into structured text files per chapter.

python3 scripts/extract_all.py "<course_directory>"

Extraction engine selection:

File Type	Engine	Why
.pptx	markitdown	Preserves tables, formatting, slide structure
.docx	markitdown	Handles encoding, tables, comments
PDF (text-based)	liteparse	Handles CMap encoding issues that PyMuPDF can't
PDF (scanned)	liteparse OCR	Bbox-preserving OCR, page screenshots
Images (.png/.jpg)	liteparse OCR	For review scope screenshots
.txt/.md	Direct read	No conversion needed

Output: course_dir/__extracted__/chN.txt per chapter, with format:

## Slide 3 (原PPT页码)
[content]

## Slide 4
[content]

Prerequisites: markitdown and liteparse installed.

python3 -m pip install "markitdown[all]" liteparse

Phase 2: Knowledge Fusion

Build the review document by fusing all sources onto the outline skeleton.

python3 scripts/fuse_knowledge.py "<course_directory>"

Fusion rules (in priority order):

1. Outline is the skeleton — every chapter section in the final doc maps to an outline topic
2. PPT fills concepts — slide content populates definitions, mechanisms, diagrams
3. Textbook confirms details — OCR'd textbook pages verify and supplement
4. Exercises map to topics — each question tagged to the concept it tests

Markdown quality rules (enforced before Phase 3 build):

• Tables MUST have a blank line before them — text immediately followed by | without a blank line causes Pandoc to skip table parsing (renders as plain text, not formatted table)
• Consistent column alignment — all tables use |------|:---:|:---:| format with explicit alignment markers
• No trailing whitespace in table cells
• Code blocks marked as plaintext in table cells where needed

After writing the MD document, run a validation pass:

# Find tables missing blank lines before them
python3 -c "
lines = open('review.md').readlines()
for i, line in enumerate(lines):
    if line.strip().startswith('|') and i > 0:
        prev = lines[i-1].rstrip()
        if prev and not prev.startswith('|'):
            print(f'Line {i+1}: table needs blank line before it')
"

Every知识点 receives a source tag:

> Source: PPT-Ch1-Slide7 | Textbook P3-4 | Exercise Q3, Q14

Answer verification (3-tier confidence):

Tier	Mark	Rule
Confirmed	(no mark)	Exercise answer matches PPT + textbook content
Single-source	[*]	Only exercise answer, no direct PPT/textbook confirmation
Contested	[!]	Exercise answer conflicts with PPT or textbook — textbook wins

Cross-chapter links are added at the end of each section:

See also: Ch4 Trilemma, Ch7 Capital Flows (linked via Financial Account)

Content classification (semantic understanding, NOT keyword matching):

When writing each概念/理论/公式, assign ONE type and ONE priority level:

Type	Assign when...	PDF style
定义	Explains what a concept IS	Blue bordered box
理论	Named theory/model/condition/rule	Deep red bordered box
公式	Calculation method or mathematical expression	Green bordered box
易错	Common mistake confirmed by exercise error data	Pink bordered box
关联	Cross-chapter concept link	Gray dashed box

Priority	Derived from	PDF style
Critical	Outline marks with ★★★ or "重中之重"	Bold title + dark border
Key	Outline page reference + ≥2 exercise questions	Flag icon + orange border
Standard	Present in PPT but not flagged above	No special box, normal text

Priority and type are independent — a formula can be Critical, a definition can be Key, etc. The AI writing the document decides classification by understanding content, never by regex keyword matching.

Markdown convention for classification:

::: {.criticalbox}
### 重中之重：Meade Conflict

**类型**：理论 | **来源**：题纲★★★ | **课本**：P21-25

Meade Conflict refers to...
:::

::: {.keybox}
### 远期汇率计算

**类型**：公式 | **来源**：题纲P43-53 | **习题**：Ch2计算题7道

Forward rate = Spot rate ± Forward margin
:::

Mermaid mind maps are generated per chapter:

python3 scripts/generate_mindmap.py <chapter_file>

Example output for Ch1:

mindmap
  root((Ch1 BOP))
    Concept
      Flow vs Stock
      Residents vs Non-Residents
      Economic Transactions
    BOP Statement
      Current Account
        Goods and Services
        Primary Income
        Secondary Income
      Capital Account
      Financial Account
        Direct Investment
        Portfolio Investment
        Reserve Assets
      Net Errors and Omissions
    Analysis
      Trade Balance
      Current Account Balance
      Overall Balance
    Adjustment
      Automatic Mechanisms
        Price-Specie-Flow (Gold)
        Interest/Income/Price (Fixed)
        Exchange Rate (Floating)
      Policy Tools
        FX Buffering
        Expenditure Shifting
        Expenditure Switching
    Key Theories
      Meade Conflict
      Tinbergen Rule
      Mundell Policy Assignment

Phase 2.5: Quality Review (Critic + Reviser)

Before committing the review document to PDF, every chapter MUST pass a quality gate (score ≥ 80/100).

Fused MD → Critic scores each chapter → Score ≥ 80? → YES → Phase 3 PDF
                                        → NO  → Reviser rewrites → back to Critic

Critic scoring rubric (per chapter):

Dimension	Weight	What to check
Outline coverage	40%	Every topic from the exam outline with ★★★ or page reference is covered. Chapter question distribution matches the outline table.
Answer accuracy	30%	Exercise answers are cross-checked against PPT and textbook. Contested answers are marked [!]. No single-source answers without [*] tag.
Structural completeness	20%	Chapter has all four elements: concepts → key points → exercises → pitfalls. Mind map is generated. Source tags are present.
Readability	10%	English terminology is correct. Tables have blank lines before them. Special characters render. No markdown syntax errors.

Scoring guide:

• 90-100: Ready, no revisions needed
• 80-89: Minor issues, fix inline then pass
• 60-79: Significant gaps, send to Reviser for that chapter only
• <60: Major rewrite needed, flag for user review

Critic execution (AI-driven, not automated script): Run the Critic review as part of the same session. For each chapter:

1. Check the exam outline → does this chapter's content cover every required topic?
2. Spot-check 3 exercise answers → do they match PPT/textbook content?
3. Verify structure: mind map present? source tags present? pitfall section present?
4. Scan for obvious errors: broken tables, missing characters, wrong terminology.

Output a scorecard:

### Quality Scorecard

| Chapter | Coverage (40) | Accuracy (30) | Structure (20) | Readability (10) | Total | Status |
|---------|:------------:|:------------:|:-------------:|:----------------:|:-----:|:------:|
| Ch1 BOP | 38 | 28 | 19 | 9 | 94 | PASS |
| Ch2 Exchange Rate | 35 | 28 | 18 | 8 | 89 | PASS |
| Ch3 FX Market | 30 | 24 | 16 | 8 | 78 | REVISE |

Reviser rules:

• ONLY rewrite chapters scored < 80
• Do NOT touch chapters that passed
• For coverage gaps: search PPT extracted text and textbook OCR for the missing content
• For accuracy issues: cross-reference with textbook, use textbook as authority
• For structure issues: add missing elements (mind map, source tags, pitfall section)
• After revision, re-run Critic on revised chapters only

Max 2 revision cycles per chapter. If still < 80 after 2 cycles, flag for user with specific issues listed.

Phase 3: Output Generation

3a. Review Document (MD + PDF)

bash scripts/build.sh "<course_directory>" "<output_name>"

Generates:

• output_name.md — Complete review document with mind maps, source tags, exercises
• output_name.pdf — Professionally formatted via Pandoc + XeLaTeX

PDF generation uses Pandoc with XeLaTeX for Chinese support:

pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="SimHei" \
  -V monofont="SimHei" \
  -V geometry:margin=2cm \
  -V colorlinks=true \
  --toc --toc-depth=2 -N

Prerequisites: pandoc and MiKTeX installed.

winget install JohnMacFarlane.Pandoc
winget install MiKTeX.MiKTeX
# Configure MiKTeX auto-install to avoid popups:
initexmf --set-config-value "[MPM]AutoInstall=1"

Font note: Special characters (★, ⚠, Greek letters, math symbols) may not render with basic CJK fonts. The build script handles this by replacing problematic characters with LaTeX equivalents where possible. For full Unicode support, install a font like Noto Sans CJK.

3b. Mock Exam (Optional)

python3 scripts/generate_mock.py "<course_directory>" \
  --difficulty mixed \
  --chapters all \
  --output mock_exam

Generates mock_exam.md and mock_exam_answers.md.

Question selection strategy:

• Sources: Chaoxing exercises (priority) + PPT in-class questions + AI-generated from key concepts
• Distribution: matches Phase 0 exam structure exactly
• Coverage: each concept gets at most 1 question; no duplicates
• Difficulty: 60% basic (verbatim from exercises), 30% medium (variations), 10% advanced (cross-chapter synthesis)

Configurable options (ask user):

• --difficulty: basic | medium | mixed | advanced
• --chapters: all | weak (user-specified weak chapters) | custom
• --types: all | objective-only | subjective-only
• --source: real-only | mixed | new-only
• --count: full | half | custom=N

Quick Reference

Task	Command
Detect exam structure	python3 scripts/scanner.py "<dir>"
Extract all materials	python3 scripts/extract_all.py "<dir>"
Fuse into review doc	python3 scripts/fuse_knowledge.py "<dir>"
Generate mind maps	python3 scripts/generate_mindmap.py "<file>"
Build final PDF	bash scripts/build.sh "<dir>" "<name>"
Generate mock exam	python3 scripts/generate_mock.py "<dir>"

Tool Inventory

Tool	Install	Purpose
markitdown	pip install "markitdown[all]"	PPTX/DOCX → Markdown
liteparse	pip install liteparse	PDF OCR + text extraction
PyMuPDF	pip install pymupdf	PDF page rendering
python-docx	pip install python-docx	DOCX fallback
Pandoc	winget install JohnMacFarlane.Pandoc	MD → PDF conversion
MiKTeX	winget install MiKTeX.MiKTeX	XeLaTeX engine
mermaid-cli	npm install -g @mermaid-js/mermaid-cli	Mind map rendering

Setup check:

python3 scripts/check_deps.py

Common Mistakes

1. Skipping Phase 0 verification — always confirm exam structure with user before spending time on extraction
2. Wrong textbook page numbers — PDF front matter (TOC, preface) creates page offset. Use clean_textbook.py to strip them first
3. Trusting single-source answers — mark them [*] and flag for user review
4. Forgetting MiKTeX auto-install — without AutoInstall=1, xelatex blocks on popup dialogs
5. Using PyMuPDF for text-based PDFs with CIDs — use liteparse instead for CMap-encoded PDFs
6. Tables rendering as plain text in PDF — missing blank line before table causes Pandoc to skip parsing. Always validate with the table-check script before building PDF. The -H templates/table-style.tex flag in build.sh provides booktabs + colortbl styling for professional table appearance.

Red Flags

• "I'll just use PyMuPDF for everything" — CMap/embedded font PDFs produce garbled text
• "The page numbers in the file names are correct" — always verify against actual textbook content
• "I'll skip the mock exam generation" — offer it, let user decide
• "One tool handles all extraction" — different file types need different engines
• "The table looks fine in markdown preview" — PDF rendering via Pandoc has different rules; always validate with blank-line check before tables

Skill Dependencies

REQUIRED SUB-SKILLS: None required. This skill is self-contained.

RELATED SKILLS (may be useful for specific steps):

• markitdown — internal skill, invoked via markitdown Python package
• liteparse — internal skill, invoked via liteparse Python package
• markdown-mermaid-writing — reference for Mermaid diagram syntax
• pdf — reference for PDF manipulation (merge, split, rotate)