Prompt Study Tips | prompts.chat

Kỹ năng
Xây dựng thời khóa biểu ôn thi chi tiết từng ngày dựa trên ngày thi, trọng số môn học và mức độ tự tin của bạn. Chia nhỏ số giờ học thành các phiên tập trung, dành nhiều thời gian hơn cho các môn yếu và nặng, đan xen các môn học, chuyển sang làm câu hỏi luyện tập trong tuần cuối trước mỗi kỳ thi, xếp một bài giải đề các năm trước bấm giờ vào ngày hôm trước, đồng thời tôn trọng các ngày nghỉ ngơi và ngày bận. Cảnh báo khi có quá ít phiên học cho mỗi chủ đề và các kỳ thi diễn ra liên tiếp. Bao gồm công cụ lập kế hoạch viết bằng thư viện chuẩn Python có hỗ trợ --self-test.
---
name: exam-revision-timetable-planner
description: Xây dựng thời khóa biểu ôn thi chi tiết từng ngày dựa trên ngày thi, trọng số môn học và mức độ tự tin của bạn. Chia nhỏ số giờ học thành các phiên tập trung, dành nhiều thời gian hơn cho các môn yếu và nặng, đan xen các môn học, chuyển sang làm câu hỏi luyện tập trong tuần cuối trước mỗi kỳ thi, xếp một bài giải đề các năm trước bấm giờ vào ngày hôm trước, đồng thời tôn trọng các ngày nghỉ ngơi và ngày bận. Cảnh báo khi có quá ít phiên học cho mỗi chủ đề và các kỳ thi diễn ra liên tiếp. Bao gồm công cụ lập kế hoạch viết bằng thư viện chuẩn Python có hỗ trợ --self-test.
---

# Trình Lập Thời Khóa Biểu Ôn Thi

Bạn giúp học sinh, sinh viên biến một mùa thi căng thẳng thành một kế hoạch thực tế: cần học môn nào trong mỗi phiên, mỗi ngày, cho đến kỳ thi cuối cùng. Bạn sử dụng các phương pháp dựa trên bằng chứng khoa học (lặp lại ngắt quãng - spacing, luyện tập truy hồi - retrieval practice, học đan xen - interleaving, giải đề các năm trước - past papers), giữ cho kế hoạch nhân văn với thời gian nghỉ ngơi và giấc ngủ hợp lý, đồng thời làm rõ các sự đánh đổi khi không có đủ thời gian cho mọi thứ.

## Các tệp trong kỹ năng này

- `scripts/revision_plan.py` - đọc tệp CSV danh sách môn học và in ra bảng môn học, thời khóa biểu từng ngày cùng các phát hiện cảnh báo (chỉ dùng thư viện chuẩn Python 3)
- `references/study-techniques.md` - những việc cần làm trong một phiên học: luyện tập truy hồi, lặp lại ngắt quãng, học đan xen, giải đề các năm trước và những điều cần tránh
- `references/scheduling-rules.md` - cách kịch bản (script) gán mức độ ưu tiên, chỉ tiêu, loại phiên học và các phát hiện cảnh báo, cũng như cách tinh chỉnh nó
- `templates/revision-plan.md` - bản kế hoạch bàn giao lại: tổng quan, thời khóa biểu hàng tuần, quy trình trong phiên học, các mốc rà soát
- `examples/winter-exams.csv` - năm kỳ thi đại học từ ngày 2 đến 11 tháng 12 kèm theo số lượng chủ đề

## Quy trình làm việc

### 1. Thu thập thông tin thực tế
Hỏi thông tin cho từng kỳ thi: môn học, ngày thi, tỷ trọng điểm (số tín chỉ, phần trăm điểm tổng kết, hoặc mức độ quan trọng từ 1-5), mức độ tự tin từ 1 (mất gốc) đến 5 (nắm vững), và số lượng chủ đề hoặc chương. Sau đó hỏi về ngày bắt đầu ôn tập đầu tiên, số giờ thực tế có thể học vào các ngày trong tuần và cuối tuần (sau giờ lên lớp, làm việc, đi lại), thời lượng phiên học mong muốn (mặc định là 50/10, hoặc Pomodoro 25/5 nếu độ tập trung thấp), một ngày nghỉ ngơi hàng tuần và bất kỳ ngày nào đã có lịch bận từ trước.

### 2. Chạy công cụ lập kế hoạch
```
python3 scripts/revision_plan.py examples/winter-exams.csv --start 2026-11-16 --weekday-hours 3 --weekend-hours 5 --rest-day Sun --off 2026-11-21 --day-start 16:00
python3 scripts/revision_plan.py my-exams.csv --start 2026-05-04 --session-min 25 --break-min 5 --json
python3 scripts/revision_plan.py --self-test
```
Mã thoát (exit code) 1 có nghĩa là có phát hiện mức HIGH (số phiên học ít hơn số chủ đề), 2 có nghĩa là dữ liệu đầu vào không hợp lệ.

### 3. Xử lý các sự đánh đổi
Đối với UNDER_COVERED hoặc TIGHT: tăng thêm giờ học, bắt đầu sớm hơn, hạ chỉ tiêu cho các môn đã vững, hoặc thống nhất xem những chủ đề ít điểm nào có thể đọc lướt (dựa vào trọng số trong đề cương hoặc tần suất xuất hiện trong đề thi các năm trước). Đối với BACK_TO_BACK: đẩy phần luyện tập của môn thứ hai lên trước ngày thi của môn thứ nhất. Kiểm tra lại kế hoạch cùng với người học: liệu kế hoạch này có khả thi vào một ngày tồi tệ không? Hãy chừa khoảng trống dự phòng thay vì nhồi nhét kín mọi buổi tối.

### 4. Bàn giao kế hoạch
Điền vào `templates/revision-plan.md`: bảng tổng quan, thời khóa biểu theo tuần, quy trình phiên học từ `references/study-techniques.md`, và hai mốc ngày rà soát để đánh giá lại mức độ tự tin và chạy lại kịch bản.

## Kết quả ví dụ
Đối với `examples/winter-exams.csv` bắt đầu từ ngày 16 tháng 11 với 3 giờ vào các ngày trong tuần, 5 giờ vào thứ Bảy, nghỉ Chủ nhật và ngày 21 tháng 11: tổng cộng 25 ngày, 57 phiên học kéo dài 50 phút (47.5 giờ). Môn Hóa Hữu cơ (trọng số 5, độ tự tin 2) và Kinh tế Vi mô (4, 2) nhận được 15 và 16 phiên, Lịch sử Châu Âu (3, 4) nhận được 6 phiên. Mỗi môn học đều kết thúc bằng việc làm câu hỏi luyện tập và giải một đề thi các năm trước có bấm giờ vào ngày trước kỳ thi của môn đó. Các phát hiện cảnh báo: Xác suất Thống kê (10 phiên cho 8 chủ đề) và Lịch sử Châu Âu (6 phiên cho 6 chủ đề) ở mức TIGHT (sát nút), còn Lịch sử Châu Âu và Kinh tế Vi mô ở trạng thái BACK_TO_BACK (thi liên tiếp) vào ngày 7 và 8 tháng 12.

## Quy tắc

- Lập kế hoạch dựa trên số giờ học sinh thực sự có, chứ không phải số giờ họ ước mình có; bảo vệ giấc ngủ (không xếp các phiên học khuya trước ngày thi).
- Mọi phiên học đều phải kết thúc bằng hoạt động truy hồi kiến thức (trả lời câu hỏi, nhớ lại trên giấy trắng, thẻ ghi nhớ flashcards), chứ không chỉ đọc lại hay tô sáng (highlight).
- Giữ ít nhất một ngày nghỉ trọn vẹn hoặc hai nửa ngày nghỉ mỗi tuần; tình trạng kiệt sức (burnout) gây thiệt hại lớn hơn nhiều so với việc mất đi một ngày học.
- Lập lại kế hoạch sau mỗi đợt rà soát hoặc sau mỗi kỳ thi thay vì cố bám theo một kế hoạch đã vỡ.
- Không làm hộ bài tập có tính điểm cho học sinh; chỉ hỗ trợ lập kế hoạch và phương pháp học tập. Nếu học sinh có dấu hiệu căng thẳng nghiêm trọng hoặc hoảng loạn, hãy khuyến khích họ trò chuyện với bộ phận hỗ trợ sinh viên hoặc bác sĩ.
FILE:references/study-techniques.md
# Các Phương Pháp Học Tập

Những việc cần làm trong mỗi phiên học. Được sắp xếp theo độ mạnh của bằng chứng khoa học (Dunlosky và cộng sự, 2013, "Improving Students' Learning With Effective Learning Techniques", đã đánh giá việc kiểm tra thực hành và thực hành phân tán có mức độ hữu ích cao).

## Luyện tập truy hồi - Retrieval practice (cao)
Khơi gợi lại thông tin từ trí nhớ thay vì đọc lại tài liệu: trả lời các câu hỏi, viết ra mọi thứ bạn nhớ được lên một tờ giấy trắng, sau đó đối chiếu với ghi chú và điền vào những chỗ còn thiếu bằng mực màu khác. Thẻ ghi nhớ (flashcards) sẽ phát huy tác dụng nếu bạn tự trả lời trước khi lật thẻ. Việc trả lời sai trước rồi mới sửa lại cũng giúp ích rất nhiều cho quá trình ghi nhớ.

## Lặp lại ngắt quãng - Spacing (cao)
Trải đều các phiên học của một môn qua nhiều ngày thay vì dồn vào một khối thời gian dài duy nhất. Một nhịp độ ôn tập đơn giản cho mỗi chủ đề: vào ngày hôm sau, sau 3 ngày, sau một tuần, và trước kỳ thi. Thời khóa biểu sẽ đan xen các môn học qua các ngày; hãy bắt đầu mỗi phiên học bằng 5 phút tự nhớ lại nội dung của phiên học trước đó thuộc cùng môn học để tích hợp sẵn hiệu ứng lặp lại ngắt quãng.

## Học đan xen - Interleaving (trung bình)
Trộn lẫn các dạng bài tập trong cùng một môn học (đối với toán và các môn khoa học: kết hợp nhiều dạng bài toán khác nhau trong một bộ đề, thay vì làm 20 bài cùng một dạng) để bạn rèn luyện kỹ năng lựa chọn phương pháp giải, điều mà kỳ thi thực tế đòi hỏi.

## Giải đề các năm trước - Past papers (cao đối với kỳ thi)
Làm ít nhất một đề thi hoàn chỉnh trong điều kiện bấm giờ trước mỗi kỳ thi, sau đó tự chấm điểm theo biểu điểm chính thức và liệt kê số điểm bị mất theo từng chủ đề. Kịch bản sẽ xếp một buổi giải đề vào ngày trước mỗi kỳ thi; hãy bổ sung thêm các buổi giải đề sớm hơn nếu có sẵn nguồn đề.

## Đào sâu và tự giải thích - Elaboration and self-explanation (trung bình)
Đặt câu hỏi "tại sao cách này lại hiệu quả?" và "điều này liên hệ với X như thế nào?", giải thích thành tiếng một khái niệm như thể đang giảng bài cho người khác, vẽ sơ đồ khái niệm (concept map) từ trí nhớ.

## Hiệu quả thấp nếu dùng đơn lẻ
Việc đọc lại, tô sáng (highlighting) và chép lại ghi chú mang lại cảm giác đang làm việc năng suất nhưng thực chất đem lại rất ít lợi ích dài hạn. Chỉ sử dụng chúng như bước đọc lướt đầu tiên trước khi thực hiện truy hồi kiến thức.

## Quy trình một phiên học (mặc định 50/10)
1. 5 phút: tự nhớ lại từ trí nhớ những gì bạn đã làm trong lần học trước của môn này.
2. 30 phút: học hoặc luyện tập một chủ đề (Learn + recall) hoặc làm câu hỏi bài tập (Practice questions).
3. 10 phút: gấp sách lại và tự kiểm tra bản thân; đánh dấu những phần bạn còn bỏ sót.
4. 5 phút: viết ra ba câu hỏi bạn chưa trả lời được để dành cho lần học tiếp theo.
5. 10 phút nghỉ giải lao rời xa màn hình: vận động, uống nước.
Đối với những người có khả năng tập trung ngắn, hãy sử dụng các phiên 25/5 (`--session-min 25 --break-min 5`) và nghỉ giải lao dài hơn sau mỗi bốn phiên.

## Giấc ngủ, dinh dưỡng và ngày trước kỳ thi
Giấc ngủ giúp củng cố trí nhớ; việc thức trắng đêm học bài sẽ làm giảm kết quả thi. Hãy dành buổi tối trước ngày thi để ôn tập nhẹ nhàng và đi ngủ. Ăn uống đầy đủ đúng bữa, vận động mỗi ngày, và để điện thoại ở phòng khác trong suốt các phiên học.
FILE:references/scheduling-rules.md
# Quy Tắc Xếp Lịch

Cách `scripts/revision_plan.py` xây dựng thời khóa biểu.

## Số phiên học mỗi ngày
Số phiên học vừa vặn trong tổng số giờ học hàng ngày: `floor((hours * 60 + break) / (session + break))`. Với các phiên 50/10: 3 giờ -> 3 phiên, 5 giờ -> 5 phiên. Các ngày nghỉ (`--rest-day`) và các ngày bận (`--off`) không xếp phiên học nào. Vào ngày có lịch thi, chỉ một nửa số phiên được lên kế hoạch (ca thi chiếm phần thời gian còn lại), và chỉ dành cho các môn thi sau đó.

## Mức độ ưu tiên và chỉ tiêu
- priority = weight x (6 - confidence). Trọng số 5, độ tự tin 2 -> 20; trọng số 3, độ tự tin 4 -> 6.
- target sessions (số phiên chỉ tiêu) = tất cả các phiên hiện có trước kỳ thi đó x priority / tổng tất cả các priority (tối thiểu là 1).
Trọng số (weight) có thể là số tín chỉ hoặc điểm đánh giá độ quan trọng từ 1-5; chỉ có tỷ lệ tương quan mới quan trọng, vì vậy hãy sử dụng cùng một thang đo cho mọi môn học.

## Cách chọn môn cho từng phiên học
Đối với mỗi phiên học, kịch bản sẽ chọn trong số các môn có ngày thi vẫn còn ở phía trước và có số phiên học trong ngày hôm đó ít hơn `--max-same` (mặc định là 2):
1. ưu tiên các môn vẫn còn thấp hơn chỉ tiêu (target) trước;
2. sau đó chọn một môn khác với phiên ngay trước đó (học đan xen - interleaving);
3. tiếp theo là môn có nhu cầu còn lại tính trên mỗi ngày cho đến ngày thi ở mức cao nhất;
4. nếu bằng nhau thì ưu tiên môn có độ ưu tiên (priority) cao hơn, rồi đến môn thi sớm hơn.
Ngày trước kỳ thi luôn bắt đầu bằng một phiên giải đề các năm trước có bấm giờ cho môn thi đó.

## Các loại phiên học
- Learn + recall (Học + truy hồi): cho đến khi hoàn thành 60 % chỉ tiêu của môn học và cách ngày thi của môn đó hơn 7 ngày.
- Mixed review (Ôn tập tổng hợp): sau khi đạt 60 % chỉ tiêu, cách ngày thi hơn 7 ngày.
- Practice questions (Câu hỏi luyện tập): trong 7 ngày cuối cùng trước kỳ thi.
- Past paper (timed) (Giải đề bấm giờ): vào ngày ngay trước kỳ thi.

## Các phát hiện cảnh báo (Findings)
| Mã | Mức độ nghiêm trọng | Quy tắc | Cách khắc phục điển hình |
|---|---|---|---|
| UNDER_COVERED | HIGH | sessions < topics | tăng số giờ học, bắt đầu sớm hơn, đọc lướt các chủ đề ít điểm |
| TIGHT | MEDIUM | sessions < 1.5 x topics | chấp nhận ôn một lượt duy nhất, hoặc san sẻ thời gian từ các môn đã vững |
| BELOW_TARGET | MEDIUM | planned < 60 % of target | kỳ thi diễn ra sớm; hãy bắt đầu học môn đó trước tiên |
| BACK_TO_BACK | MEDIUM | các kỳ thi vào những ngày liên tiếp | đẩy sớm phần luyện tập của môn thi thứ hai lên trước |
| SAME_DAY | MEDIUM | hai kỳ thi trong cùng một ngày | coi cả hai môn như một khối chung trong tuần cuối cùng |
| NO_REST_DAY | LOW | kế hoạch > 10 ngày mà không có ngày nghỉ hay ngày bận | thêm `--rest-day` |
| LONG_DAYS | LOW | hơn 8 giờ mỗi ngày | giới hạn tối đa ở mức 5-6 giờ tập trung |

## Tinh chỉnh
- Dành thêm thời gian cho một môn học: tăng trọng số (weight) hoặc giảm độ tự tin (confidence) của môn đó rồi chạy lại.
- Giảm số lần chuyển đổi môn học: dùng `--max-same 3`.
- Giờ đồng hồ cụ thể: `--day-start 09:00` sẽ thêm thời gian bắt đầu và kết thúc, kèm theo thời gian nghỉ giải lao giữa các phiên.
- Lập lại kế hoạch: sau mỗi đợt rà soát, cập nhật lại độ tự tin và tham số `--start`, rồi chạy lại; các môn đã thi xong sẽ được loại bỏ khỏi tệp CSV.
FILE:templates/revision-plan.md
# Kế hoạch ôn thi: <tên>, <mùa thi>

**Giai đoạn:** <16 Th11 đến 11 Th12 2026>   **Số giờ:** <3 giờ ngày thường, 5 giờ thứ Bảy>   **Nghỉ ngơi:** <Chủ nhật + 21 Th11>
**Số phiên:** <57 x 50 phút (47.5 giờ)>   **Nhịp độ phiên học:** <50 phút học / 10 phút nghỉ>

## Các kỳ thi và mức độ ưu tiên
| Môn học | Ngày thi | Trọng số | Độ tự tin | Số chủ đề | Số phiên dự kiến | Ghi chú |
|---|---|---|---|---|---|---|
| <Hóa Hữu cơ> | <Thứ Tư 2 Th12> | <5> | <2> | <9> | <15> | <giải đề 1 Th12> |

## Tuần 1: <16-22 Th11>
| Ngày | Phiên 1 | Phiên 2 | Phiên 3 | Phiên 4 | Phiên 5 |
|---|---|---|---|---|---|
| <Thứ Hai 16 Th11> | <16:00 Hóa Hữu cơ: Học> | <17:00 Kinh tế Vi mô: Học> | <...> | | |

## Tuần 2: <...>
<...>

## Quy trình phiên học
1. 5 phút tự nhớ lại phiên học trước (trên giấy trắng)
2. 30 phút học hoặc luyện tập một chủ đề
3. 10 phút tự kiểm tra, đánh dấu những chỗ còn thiếu sót
4. 5 phút: ghi lại ba câu hỏi còn bỏ ngỏ cho lần học tới
5. 10 phút nghỉ giải lao rời xa màn hình

## Các sự đánh đổi đã thống nhất
- <Xác suất Thống kê đang ở mức TIGHT: ôn toàn diện một lượt, lượt thứ hai chỉ tập trung vào các chủ đề 5-8 (chiếm nhiều điểm nhất trong đề thi các năm trước)>
- <Lịch sử Châu Âu / Kinh tế Vi mô thi liên tiếp: hoàn thành phần luyện tập Kinh tế Vi mô trước ngày 5 Th12>

## Các mốc rà soát (Check-ins)
- <Chủ nhật 22 Th11>: đánh giá lại độ tự tin từ 1-5 cho từng môn, chạy lại công cụ lập kế hoạch
- <Chủ nhật 29 Th11>: tương tự, điều chỉnh lại 10 ngày cuối cùng

## Sức khỏe tinh thần và thể chất
- Giấc ngủ: <lên giường trước 23:30, không học sau 22:00 vào buổi tối trước ngày thi>
- Vận động hàng ngày: <đi bộ 30 phút>
- Nếu cảm thấy quá tải: <trò chuyện với ... / liên hệ bộ phận hỗ trợ sinh viên>
FILE:examples/winter-exams.csv
subject,exam_date,weight,confidence,topics
Organic Chemistry,2026-12-02,5,2,9
Statistics,2026-12-04,4,3,8
European History,2026-12-07,3,4,6
Microeconomics,2026-12-08,4,2,7
Academic English,2026-12-11,2,4,4
FILE:scripts/revision_plan.py
#!/usr/bin/env python3
"""Exam revision timetable planner (Python 3 standard library only).

Reads a CSV of subjects with exam dates, weight and confidence, splits the
available study time into focused sessions, and builds a day-by-day timetable
that gives weak, heavy subjects more time, interleaves subjects, stops new work
on a subject after its exam, moves from learning to practice questions in the
last week before each exam and puts a timed past paper on the day before.

CSV columns (header required; ; or , separated):
  subject, exam_date (YYYY-MM-DD), weight (1-5 or credits), confidence (1-5), topics (optional)

Usage:
  python3 revision_plan.py exams.csv --start 2026-11-16 --weekday-hours 3 --weekend-hours 5
  python3 revision_plan.py exams.csv --start 2026-11-16 --rest-day Sun --off 2026-11-28,2026-11-29 --day-start 16:00
  python3 revision_plan.py --self-test
Exit codes: 0 = plan fits, 1 = HIGH findings (not enough sessions), 2 = bad input.
"""
import argparse, csv, datetime as dt, io, json, sys

DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
SEV = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}


class InputError(Exception):
    pass


def parse_date(s, what):
    try:
        return dt.date.fromisoformat(s.strip())
    except ValueError:
        raise InputError(f"{what} '{s}' must be YYYY-MM-DD")


def read_subjects(text):
    sample = text[:2000]
    delim = ";" if sample.count(";") > sample.count(",") else ","
    rd = csv.DictReader(io.StringIO(text), delimiter=delim)
    if not rd.fieldnames:
        raise InputError("empty CSV")
    fields = [f.strip().lower() for f in rd.fieldnames]
    missing = [c for c in ("subject", "exam_date", "weight", "confidence") if c not in fields]
    if missing:
        raise InputError("missing columns: " + ", ".join(missing))
    subs = []
    for i, raw in enumerate(rd, start=2):
        r = {k.strip().lower(): (v or "").strip() for k, v in raw.items() if k}
        if not any(r.values()):
            continue
        try:
            w = float(r["weight"].replace(",", "."))
            c = int(r["confidence"])
            t = int(r["topics"]) if r.get("topics") else None
        except ValueError:
            raise InputError(f"row {i}: weight, confidence and topics must be numbers")
        if w <= 0:
            raise InputError(f"row {i}: weight must be positive")
        if not 1 <= c <= 5:
            raise InputError(f"row {i}: confidence must be 1 (weak) to 5 (strong)")
        if not r["subject"]:
            raise InputError(f"row {i}: subject is empty")
        subs.append({"subject": r["subject"], "exam": parse_date(r["exam_date"], f"row {i}: exam_date"),
                     "weight": w, "confidence": c, "topics": t})
    if not subs:
        raise InputError("no subjects in CSV")
    return subs


def slots_for(hours, session, brk):
    """Number of sessions that fit in `hours` with a break between sessions."""
    mins = hours * 60
    if mins < session:
        return 0
    return int((mins + brk) // (session + brk))


def plan(subs, start, weekday_hours=3.0, weekend_hours=5.0, session=50, brk=10, rest_day=None,
         off=(), max_same=2, day_start=None):
    if session < 15 or brk < 0:
        raise InputError("session must be at least 15 minutes and break not negative")
    for s in subs:
        if s["exam"] <= start:
            raise InputError(f"{s['subject']}: exam {s['exam']} is not after the start date {start}")
    last = max(s["exam"] for s in subs)
    exam_days = {}
    for s in subs:
        exam_days.setdefault(s["exam"], []).append(s["subject"])
    for s in subs:
        s["priority"] = s["weight"] * (6 - s["confidence"])
    days = []
    d = start
    while d < last:
        if d in off or (rest_day is not None and d.weekday() == rest_day):
            n = 0
        else:
            n = slots_for(weekend_hours if d.weekday() >= 5 else weekday_hours, session, brk)
            if d in exam_days:
                n //= 2  # the exam takes half the day
        days.append((d, n))
        d += dt.timedelta(days=1)
    # target sessions: share of the slots available before each exam, by priority
    total_p = sum(s["priority"] for s in subs)
    for s in subs:
        before = sum(n for day, n in days if day < s["exam"])
        s["target"] = max(1, round(before * s["priority"] / total_p))
        s["planned"] = 0
    timetable = []
    for day, n in days:
        today, used = [], {}
        live = [s for s in subs if s["exam"] > day]
        # the day before an exam: a timed past paper first
        for s in live:
            if (s["exam"] - day).days == 1 and len(today) < n:
                today.append((s["subject"], "Past paper (timed)")); used[s["subject"]] = 1; s["planned"] += 1
        while len(today) < n:
            cands = [s for s in live if used.get(s["subject"], 0) < max_same]
            if not cands:
                break
            prev = today[-1][0] if today else None

            def score(s):
                days_left = max(1, (s["exam"] - day).days)
                need = (s["target"] - s["planned"]) / days_left
                # subjects still below target first, then interleave (avoid repeating the previous subject)
                return (s["planned"] < s["target"], s["subject"] != prev, need, s["priority"], -s["exam"].toordinal())
            s = max(cands, key=score)
            left = (s["exam"] - day).days
            kind = "Practice questions" if left <= 7 else ("Learn + recall" if s["planned"] < s["target"] * 0.6 else "Mixed review")
            today.append((s["subject"], kind)); used[s["subject"]] = used.get(s["subject"], 0) + 1; s["planned"] += 1
        timed = []
        t = day_start
        for subj, kind in today:
            if t is not None:
                end = t + session
                timed.append({"subject": subj, "kind": kind, "time": f"{t // 60:02d}:{t % 60:02d}-{end // 60:02d}:{end % 60:02d}"})
                t = end + brk
            else:
                timed.append({"subject": subj, "kind": kind})
        timetable.append({"date": day.isoformat(), "dow": DAYS[day.weekday()], "exams": exam_days.get(day, []), "sessions": timed})
    findings = []
    for s in subs:
        if s["topics"]:
            if s["planned"] < s["topics"]:
                findings.append(("HIGH", "UNDER_COVERED", f"{s['subject']}: {s['planned']} sessions for {s['topics']} topics; add hours, drop low-yield topics or start earlier"))
            elif s["planned"] < 1.5 * s["topics"]:
                findings.append(("MEDIUM", "TIGHT", f"{s['subject']}: {s['planned']} sessions for {s['topics']} topics leaves little time for a second pass"))
        if s["planned"] < 0.6 * s["target"]:
            findings.append(("MEDIUM", "BELOW_TARGET", f"{s['subject']}: {s['planned']} of {s['target']} target sessions fit before the exam"))
    dates = sorted(exam_days)
    for a, b in zip(dates, dates[1:]):
        if (b - a).days <= 1:
            findings.append(("MEDIUM", "BACK_TO_BACK", f"exams on {a} ({', '.join(exam_days[a])}) and {b} ({', '.join(exam_days[b])}); finish the second subject's practice before the first exam"))
    for day, subjects in exam_days.items():
        if len(subjects) > 1:
            findings.append(("MEDIUM", "SAME_DAY", f"{len(subjects)} exams on {day}: {', '.join(subjects)}"))
    if rest_day is None and len(days) > 10 and not off:
        findings.append(("LOW", "NO_REST_DAY", "no rest day in a plan longer than 10 days; take at least half a day off each week"))
    if max(weekday_hours, weekend_hours) > 8:
        findings.append(("LOW", "LONG_DAYS", "more than 8 hours of revision a day rarely stays productive; keep 5-6 focused hours"))
    findings.sort(key=lambda f: SEV[f[0]])
    total_sessions = sum(len(t["sessions"]) for t in timetable)
    return {
        "subjects": [{"subject": s["subject"], "exam": s["exam"].isoformat(), "weight": s["weight"], "confidence": s["confidence"],
                      "priority": s["priority"], "topics": s["topics"], "target": s["target"], "planned": s["planned"],
                      "hours": round(s["planned"] * session / 60, 1)} for s in sorted(subs, key=lambda x: x["exam"])],
        "summary": {"start": start.isoformat(), "last_exam": last.isoformat(), "days": len(days), "sessions": total_sessions,
                    "study_hours": round(total_sessions * session / 60, 1), "session_min": session, "break_min": brk},
        "timetable": timetable,
        "findings": [{"severity": a, "code": b, "message": c} for a, b, c in findings],
    }


def to_markdown(p):
    s = p["summary"]
    out = ["# Revision timetable", "",
           f"{s['start']} to {s['last_exam']}: {s['days']} days, {s['sessions']} sessions of {s['session_min']} min ({s['study_hours']} h of focused study), {s['break_min']} min breaks",
           "", "| Subject | Exam | Weight | Confidence | Priority | Topics | Target | Planned | Hours |", "|---|---|---|---|---|---|---|---|---|"]
    for x in p["subjects"]:
        out.append(f"| {x['subject']} | {x['exam']} | {x['weight']:g} | {x['confidence']} | {x['priority']:g} | {x['topics'] or '-'} | {x['target']} | {x['planned']} | {x['hours']} |")
    out += ["", "## Day by day", ""]
    for t in p["timetable"]:
        head = f"- **{t['dow']} {t['date']}**" + (f" (EXAM: {', '.join(t['exams'])})" if t["exams"] else "")
        if not t["sessions"]:
            out.append(head + ": rest")
            continue
        parts = [(f"{x['time']} " if "time" in x else "") + f"{x['subject']} ({x['kind']})" for x in t["sessions"]]
        out.append(head + ": " + "; ".join(parts))
    out += ["", "## Findings"]
    out += [f"- {f['severity']} {f['code']}: {f['message']}" for f in p["findings"]] or ["- none"]
    out += ["", "Start each session with 5 minutes of recall from memory on the previous session of that subject, and end with 3 questions you could not answer."]
    return "\n".join(out)


def self_test():
    res = []

    def check(name, cond):
        res.append(cond)
        print(("PASS " if cond else "FAIL ") + name)

    D = dt.date
    S = lambda name, exam, w=1, c=3, t=None: {"subject": name, "exam": exam, "weight": w, "confidence": c, "topics": t}
    check("slots: 3 h of 50+10 = 3", slots_for(3, 50, 10) == 3)
    check("slots: 50 min fits exactly 1", slots_for(50 / 60, 50, 10) == 1)
    check("slots: under one session = 0", slots_for(0.5, 50, 10) == 0)
    check("slots: 25+5 in 2 h = 4", slots_for(2, 25, 5) == 4)
    p = plan([S("A", D(2026, 1, 8))], D(2026, 1, 5), weekday_hours=2, weekend_hours=2, session=50, brk=10)
    check("no sessions on or after exam day", all(t["date"] < "2026-01-08" for t in p["timetable"]))
    check("day before exam starts with past paper", p["timetable"][-1]["sessions"][0]["kind"] == "Past paper (timed)")
    check("practice questions in last 7 days", all(x["kind"] != "Learn + recall" for t in p["timetable"] for x in t["sessions"]))
    subs = [S("Weak", D(2026, 3, 1), w=3, c=1), S("Strong", D(2026, 3, 1), w=3, c=5)]
    p = plan(subs, D(2026, 2, 1), weekday_hours=3, weekend_hours=3, max_same=3)
    pl = {x["subject"]: x["planned"] for x in p["subjects"]}
    check("weak subject gets more sessions", pl["Weak"] > 3 * pl["Strong"])
    check("priority = weight x (6 - confidence)", p["subjects"][0]["priority"] in (15, 3))
    p = plan([S("A", D(2026, 3, 1)), S("B", D(2026, 3, 1))], D(2026, 2, 1), weekday_hours=3, weekend_hours=3)
    check("max 2 sessions of one subject per day", all(
        sum(1 for x in t["sessions"] if x["subject"] == subj) <= 2 for t in p["timetable"] for subj in "AB"))
    check("subjects interleaved while both need time", all(t["sessions"][i]["subject"] != t["sessions"][i + 1]["subject"]
                                      for t in p["timetable"][:10] for i in range(len(t["sessions"]) - 1)))
    p = plan([S("A", D(2026, 2, 16))], D(2026, 2, 2), rest_day=6)
    check("rest day empty", all(not t["sessions"] for t in p["timetable"] if t["dow"] == "Sun"))
    p = plan([S("A", D(2026, 2, 6))], D(2026, 2, 2), off={D(2026, 2, 3)})
    check("off day empty", not [t for t in p["timetable"] if t["date"] == "2026-02-03"][0]["sessions"])
    p = plan([S("A", D(2026, 2, 5)), S("B", D(2026, 2, 9))], D(2026, 2, 2), weekday_hours=4)
    day5 = [t for t in p["timetable"] if t["date"] == "2026-02-05"][0]
    check("exam day: half the slots, other subject only", len(day5["sessions"]) == 2 and all(x["subject"] == "B" for x in day5["sessions"]))
    p = plan([S("A", D(2026, 2, 5), t=20)], D(2026, 2, 2))
    check("UNDER_COVERED HIGH", p["findings"][0]["code"] == "UNDER_COVERED")
    p = plan([S("A", D(2026, 2, 20), t=11)], D(2026, 2, 2), weekday_hours=1, weekend_hours=1, rest_day=6)
    check("TIGHT", any(f["code"] == "TIGHT" for f in p["findings"]))
    p = plan([S("A", D(2026, 2, 9)), S("B", D(2026, 2, 10)), S("C", D(2026, 2, 10))], D(2026, 2, 2))
    codes = [f["code"] for f in p["findings"]]
    check("BACK_TO_BACK and SAME_DAY", "BACK_TO_BACK" in codes and "SAME_DAY" in codes)
    check("NO_REST_DAY", "NO_REST_DAY" in [f["code"] for f in plan([S("A", D(2026, 3, 1))], D(2026, 2, 1))["findings"]])
    check("LONG_DAYS", "LONG_DAYS" in [f["code"] for f in plan([S("A", D(2026, 2, 5))], D(2026, 2, 2), weekend_hours=10)["findings"]])
    p = plan([S("A", D(2026, 2, 5))], D(2026, 2, 2), day_start=9 * 60)
    check("clock times with --day-start", p["timetable"][0]["sessions"][1]["time"] == "10:00-10:50")
    subs = read_subjects("subject;exam_date;weight;confidence;topics\nMaths;2026-12-03;4,5;2;9\n")
    check("semicolon CSV + decimal comma", subs[0]["weight"] == 4.5 and subs[0]["topics"] == 9)
    for bad, why in [("subject,exam_date\nA,2026-01-01\n", "missing columns"),
                     ("subject,exam_date,weight,confidence\nA,2026-13-01,1,3\n", "bad date"),
                     ("subject,exam_date,weight,confidence\nA,2026-01-01,1,9\n", "confidence out of range"),
                     ("subject,exam_date,weight,confidence\nA,2026-01-01,x,3\n", "non-number")]:
        try:
            read_subjects(bad); check("rejects " + why, False)
        except InputError:
            check("rejects " + why, True)
    try:
        plan([S("A", D(2026, 1, 1))], D(2026, 1, 1)); check("rejects exam not after start", False)
    except InputError:
        check("rejects exam not after start", True)
    passed = sum(res)
    print(f"{passed}/{len(res)} passed")
    return 0 if passed == len(res) else 1


def main():
    ap = argparse.ArgumentParser(description="Exam revision timetable planner")
    ap.add_argument("csv", nargs="?", help="subjects CSV")
    ap.add_argument("--start", help="first revision day YYYY-MM-DD (default today)")
    ap.add_argument("--weekday-hours", type=float, default=3.0)
    ap.add_argument("--weekend-hours", type=float, default=5.0)
    ap.add_argument("--session-min", type=int, default=50, help="focused session length (default 50)")
    ap.add_argument("--break-min", type=int, default=10, help="break between sessions (default 10)")
    ap.add_argument("--rest-day", choices=DAYS, help="weekly day off")
    ap.add_argument("--off", default="", help="comma-separated dates with no revision (YYYY-MM-DD)")
    ap.add_argument("--max-same", type=int, default=2, help="max sessions of one subject per day (default 2)")
    ap.add_argument("--day-start", help="clock time of the first session HH:MM (adds times to the timetable)")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args()
    if a.self_test:
        return self_test()
    if not a.csv:
        ap.error("give a CSV, or --self-test")
    try:
        with open(a.csv, encoding="utf-8-sig") as fh:
            subs = read_subjects(fh.read())
        start = parse_date(a.start, "--start") if a.start else dt.date.today()
        off = {parse_date(x, "--off") for x in a.off.split(",") if x.strip()}
        ds = None
        if a.day_start:
            try:
                h, m = map(int, a.day_start.split(":")); assert 0 <= h < 24 and 0 <= m < 60
            except Exception:
                raise InputError("--day-start must be HH:MM")
            ds = h * 60 + m
        p = plan(subs, start, a.weekday_hours, a.weekend_hours, a.session_min, a.break_min,
                 DAYS.index(a.rest_day) if a.rest_day else None, off, a.max_same, ds)
    except (OSError, InputError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(p, indent=2) if a.json else to_markdown(p))
    return 1 if any(f["severity"] == "HIGH" for f in p["findings"]) else 0


if __name__ == "__main__":
    sys.exit(main())
Python Students Education+2
F@f