| 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:
- Exam format: language, platform, duration
- Question types: single/multiple choice, T/F, short answer, essay, current affairs
- Distribution: how many questions per chapter per type
- 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:
- "Is this exam structure correct?"
- "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):
- Outline is the skeleton — every chapter section in the final doc maps to an outline topic
- PPT fills concepts — slide content populates definitions, mechanisms, diagrams
- Textbook confirms details — OCR'd textbook pages verify and supplement
- 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:
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:
- Check the exam outline → does this chapter's content cover every required topic?
- Spot-check 3 exercise answers → do they match PPT/textbook content?
- Verify structure: mind map present? source tags present? pitfall section present?
- 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, exercisesoutput_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
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
- Skipping Phase 0 verification — always confirm exam structure with user before spending time on extraction
- Wrong textbook page numbers — PDF front matter (TOC, preface) creates page offset. Use
clean_textbook.py to strip them first
- Trusting single-source answers — mark them
[*] and flag for user review
- Forgetting MiKTeX auto-install — without
AutoInstall=1, xelatex blocks on popup dialogs
- Using PyMuPDF for text-based PDFs with CIDs — use liteparse instead for CMap-encoded PDFs
- 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 packageliteparse — internal skill, invoked via liteparse Python packagemarkdown-mermaid-writing — reference for Mermaid diagram syntaxpdf — reference for PDF manipulation (merge, split, rotate)
