past-paper-knowledge-point-analysis

Category: Development & Coding | Uploader: OctavianYimingZhang | Downloads: 0 | Version: v1.0（Latest）

Analyze lecture slide decks, lecture-note PDFs, MCQ past-paper PDFs, and optional image-based DOCX answer keys into reusable lecture/topic maps, question-to-knowledge-point mappings, hotness tables, and fixed-threshold retention bands. Use when Codex needs to identify high-frequency exam topics, recurring year-to-year topics, or review-gated knowledge-point mappings from course materials where slides plus past papers are the minimum available input.

Changelog: Source: GitHub https://github.com/OctavianYimingZhang/Past-Paper-Analysis-Skill

Directory Structure

Current level: Root

📁 agents/
- 📄 openai.yaml 313 B
📁 past_paper_analysis_v2/
- 📄 __init__.py 2.1 KB
- 📄 adapters.py 2.0 KB
- 📄 aggregate.py 5.9 KB
- 📄 cli.py 3.1 KB
- 📄 exporters.py 11.4 KB
- 📄 ingest.py 9.2 KB
- 📄 mapping.py 8.6 KB
- 📄 models.py 3.1 KB
- 📄 ocr_backends.py 7.4 KB
- 📄 ontology.py 12.5 KB
- 📄 pipeline.py 4.2 KB
- 📄 segment.py 13.7 KB
- 📄 utils.py 3.0 KB
- 📄 validate.py 7.9 KB
📁 past_paper_knowledge_point_analysis_v2/
- 📄 __init__.py 156 B
📁 references/
- 📁 specs/
  - 📄 example-notes-and-papers.json 1.2 KB
  - 📄 example-slides-and-papers.json 1.0 KB
- 📄 course-spec-schema.json 9.5 KB
- 📄 course-spec-schema.md 5.5 KB
- 📄 migration-v2.md 1.7 KB
- 📄 presets.md 790 B
📁 scripts/
- 📄 analyze_past_papers.py 328 B
- 📄 generate_local_specs.py 16.7 KB
- 📄 install_local_skill.py 1.2 KB
- 📄 run_current_course_regression.py 7.7 KB
- 📄 vision_ocr.swift 4.7 KB
📁 tests/
- 📁 fixtures/
  - 📄 v2_course_spec.json 1.2 KB
  - 📄 v2_run_payload.json 4.6 KB
- 📄 conftest.py 7.0 KB
- 📄 test_v2_adapter_contract.py 1.0 KB
- 📄 test_v2_aggregation_contract.py 1.1 KB
- 📄 test_v2_ontology_contract.py 1.7 KB
- 📄 test_v2_pipeline_smoke.py 3.9 KB
- 📄 test_v2_spec_contract.py 1.1 KB
📄 .gitignore 57 B
📄 LICENSE 1.1 KB
📄 pyproject.toml 417 B
📄 README.md 2.4 KB
📄 SKILL.md 5.7 KB

SKILL.md

---
name: past-paper-knowledge-point-analysis
description: Analyze lecture slide decks, lecture-note PDFs, MCQ past-paper PDFs, and optional image-based DOCX answer keys into reusable lecture/topic maps, question-to-knowledge-point mappings, hotness tables, and fixed-threshold retention bands. Use when Codex needs to identify high-frequency exam topics, recurring year-to-year topics, or review-gated knowledge-point mappings from course materials where slides plus past papers are the minimum available input.
---

# Past Paper Knowledge Point Analysis

## Overview

Use this skill to turn one course's lecture materials and past papers into an exam-analysis package with:

- lecture extraction from slide decks or note PDFs
- one primary canonical topic per question
- hotness and retention reported separately
- topic-level uncertainty reporting, including mapping coverage and stability flags
- fixed retention bands with explicit `meets_50` and `meets_75`
- English-only workbook, JSON, and Markdown outputs
- review queues for weak OCR, weak parsing, or weak mappings

This repo-local directory is the open-source source of truth. The installed copy under `$CODEX_HOME/skills/` should be treated as a synced runtime copy, not the canonical source.

## Quick Start

1. Generate private local specs outside the public skill tree:

```bash
python3 <repo-root>/skills/past-paper-knowledge-point-analysis/scripts/generate_local_specs.py
```

2. Sync the repo-local skill into the local Codex skills directory:

```bash
python3 <repo-root>/skills/past-paper-knowledge-point-analysis/scripts/install_local_skill.py
```

3. Run the analyzer on a local spec:

```bash
python3 <repo-root>/skills/past-paper-knowledge-point-analysis/scripts/analyze_past_papers.py \
  --spec <repo-root>/tmp/past-paper-knowledge-point-analysis/local-specs/biochemistry.json
```

## Public vs Local Specs

- Public example specs live in:
  - [references/specs/example-slides-and-papers.json](./references/specs/example-slides-and-papers.json)
  - [references/specs/example-notes-and-papers.json](./references/specs/example-notes-and-papers.json)
- The v2 public schema is documented in [references/course-spec-schema.md](./references/course-spec-schema.md).
- The v2 migration notes are documented in [references/migration-v2.md](./references/migration-v2.md).
- Do not commit private absolute-path specs into the public skill tree.
- Generate local runnable specs under `tmp/past-paper-knowledge-point-analysis/local-specs/`.

## Input Rules

- Minimum usable input: `slides_dir + papers[]`
- Preferred input: `slides_dir + papers[] + answer_keys[]`
- Fallback input: `notes_pdf + papers[]`
- At least one of `slides_dir` or `notes_pdf` is required.
- `answer_keys[]` are optional but strongly preferred.
- `papers[].role` controls retention:
  - `formal` counts toward default retention
  - `auxiliary` can be analyzed but is excluded from default retention unless the spec says otherwise

## Workflow

1. Resolve the course spec and preset.
2. Prefer preset-backed slide extraction when a known preset exists and `slides_dir` is available.
3. Fall back to notes when slides are absent or unusable.
4. Segment paper questions using the configured/default parser strategy.
5. If answer keys are present, OCR them and use them to validate question segmentation and strengthen mapping confidence.
6. Merge candidate slide/note lines into ontology clusters and canonical topics.
7. Map each question to one primary canonical topic, with optional secondary context-only topics.
8. Compute:
  - hotness: formal-only and all-material views, each with raw and confidence-weighted counts
  - retention: lower and upper bounds, `mapping_coverage`, `topic_stability_flag`, and the existing banding fields
9. Emit review-queue rows instead of silently suppressing low-confidence failures.

## Preset-First Mode

Current preset IDs are documented in [references/presets.md](./references/presets.md).

Preset-first mode should be used for known courses such as:

- Biochemistry
- From Molecules to Cells
- Drugs
- Excitable Cells

For known courses, the local-spec generator can inject explicit slide manifests and paper numbering hints so the analyzer does not have to guess from filenames alone.

## Analyzer Rules

- Keep all outputs in English only.
- Count hotness and retention from the primary mapped canonical topic only.
- In v2, the primary mapping target is the canonical topic ID, not the raw lecture candidate.
- In v2, topic-level statistics must preserve uncertainty instead of collapsing to a single hard count.
- In v2, `question_archetype` is a separate axis from topic mapping.
- Do not convert retention into quartile stars.
- Use fixed retention labels:
  - `Anchor`: `>=75%`
  - `Core`: `>=50%` and `<75%`
  - `Recurring`: more than one formal year but `<50%`
  - `One-off`: exactly one formal year
  - `Not tested`: zero mapped hits
- Keep review issues visible. Do not hide them to make outputs look cleaner.

## Outputs

Each run writes:

- Excel workbook with:
  - `Run_Metadata`
  - `Evidence_Clusters`
  - `Canonical_Topics`
  - `Topic_Groups`
  - `Ontology_Lineage`
  - `Question_Mapping`
  - `Hotness_Formal`
  - `Hotness_All_Material`
  - `Retention_Formal`
  - `Coverage_Stability`
  - `Review_Queue`
- JSON analysis payload using the v2 run contract
- Markdown summary

## Regression

Run the full regression after meaningful changes:

```bash
python3 <repo-root>/skills/past-paper-knowledge-point-analysis/scripts/run_current_course_regression.py
```

The regression:

- generates private local specs
- validates answer/explanation parser variants
- validates retention-band thresholds
- hard-gates question-count recovery
- compares preset-backed runs against local benchmark artifacts where available
- checks that outputs remain English-only

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

past-paper-knowledge-point-analysis

Directory Structure

SKILL.md

Report

Notice