---
name: create-clean-practice-sheets-from-filled-school-tests
description: Create clean printable practice worksheets and solution sheets from filled/photographed school tests when direct cleanup would damage readability.
---

# Create clean practice sheets from filled school tests

Use this when the user has photographed/scanned filled school tests and wants reusable practice material for a child/sibling. If removing handwriting/red corrections from the original makes the page unreadable, recreate the worksheet cleanly instead of overpainting the scan.

## Trigger conditions

- Filled school tests contain pencil/pen answers, solution paths, teacher corrections, grades, or red notes.
- The user wants a blank practice version.
- Image cleanup causes any of these problems:
  - printed task text becomes hard to read or pixelated,
  - white masks cover parts of the exercise,
  - scan quality is too low,
  - handwriting overlaps too heavily with printed material.

## Recommended workflow

1. **Locate the source PDFs, OCR/index files, and learning-book references**
   - Search by known title/subject/LZK number.
   - Prefer existing structured folders under the learning area, e.g. `family/Lernen/...`.
   - Read README/OCR files to understand page count, topic, and likely task types.
   - If the user mentions a workbook/textbook folder or photographed learning materials, inspect those too; for poor-quality photos, build contact sheets and use vision analysis rather than relying on OCR alone.
   - If the user says the first worksheet was too difficult, create a **scaffolded easier variant** instead of merely reducing numbers: start from what the child already knows, add short child-friendly explanation boxes, then introduce the next level gradually.
   - If the user provides a scored diagnostic/Standortbestimmung, archive the corrected scan/PDF plus a short `README.md`/JSON score summary before generating follow-up materials.
   - Use the score/profile and user feedback to prioritize the new practice sheet: weak or not-yet-secure areas become the main guided sections; already-strong areas become short maintenance/check sections.

2. **Extract only the task structure, not the answers**
   - Use OCR text first: Tesseract/Docling/Paddle index if available.
   - Use LLM vision sparingly on contact sheets or selected pages only when OCR is insufficient.
   - Do not transcribe child handwriting unless needed and explicitly appropriate.
   - Identify:
     - exercise numbers,
     - instructions,
     - mathematical operations/topics,
     - approximate difficulty,
     - layout needs such as grids, answer lines, multi-column tasks.

3. **Decide: cleanup vs recreation**
   - If scan cleanup harms readability, stop trying to erase handwriting.
   - Recreate a clean worksheet with same or very similar task types.
   - Keep it pedagogically equivalent, not necessarily identical.
   - Preserve the school level and topic vocabulary.

4. **Create clean PDFs**
   - Use a deterministic PDF generator such as Python `reportlab`.
   - Use A4 page size, readable fonts, clean margins.
   - Add title/header, child-neutral naming, and page numbering.
   - For math work areas, draw light grid/Häuschen lines instead of using the scan background.
   - When adapting to a child’s current level, include short “Merke/Tipp” boxes and progress in small steps: known concept → guided example → blank practice → one gentle challenge.
   - Avoid image-based text where possible; vector text keeps output sharp.
   - Name files clearly, e.g.:
     - `Mathe_Valerie_Uebungsblatt_LZK_4_12_..._neu.pdf`
     - `Mathe_Valerie_Loesungsblatt_LZK_4_12_..._neu.pdf`
     - for easier differentiated variants, add a suffix such as `_EINFACH.pdf`.

5. **Calculate and verify solutions with tools**
   - Never calculate manually in the response.
   - Use Python/terminal for arithmetic, divisions with remainder, and puzzle checks.
   - Watch for accidentally ambiguous generated tasks. If an exercise has multiple valid solutions, either fix the worksheet or clearly note it in the solution sheet.

6. **Create solution sheets**
   - Separate PDFs are better than embedding solutions in the worksheet.
   - Include stepwise decompositions where useful, especially for:
     - Rechenprotokoll,
     - written multiplication/division,
     - division with remainder,
     - inverse/word-number tasks.
   - For children with weak diagnostics, write each explanation in simple repeatable language, e.g. “Frage suchen → Rechnung schreiben → Antwortsatz mit Einheit” or “Ergebnis · Teiler + Rest = Startzahl”.

7. **Verify output before delivery**
   - Run `pdfinfo` or equivalent to verify page count, A4 size, and file existence.
   - Render a contact sheet with `pdftoppm` and inspect visually.
   - Vision check should confirm:
     - readable text,
     - no handwriting/red corrections,
     - no white masks/overlapping blocks,
     - no cut-off task instructions,
     - grids/answer spaces are usable.

8. **Deliver artifacts**
   - Send the final worksheet PDFs and solution PDFs via `MEDIA:` paths.
   - Briefly mention any known caveat, e.g. ambiguous task or deliberately similar rather than identical numbers.

## Tool notes from successful run

- `reportlab` worked well for sharp, clean PDFs.
- `pdftoppm` can render PDFs to PNGs for contact-sheet verification.
- A contact sheet is efficient for a sparse vision check: render all pages at moderate DPI, thumbnail them into one image, then ask vision to check layout/readability.
- For 4th-grade math sheets, use light blue grid lines and clear headings; avoid recreating noisy scan backgrounds.
- For place-value/Stellenwert worksheets, a successful scaffold is: `Einer/Zehner/Hunderter/Tausender` table first, then “Tausender-Lücke” reading (e.g. `12345 → 12 345`), then decomposition into place-value addends, then gentle `Zehntausender` extension. Use workbook-style language such as “Die Stelle zeigt, was eine Ziffer wert ist” and “10 gleiche Stücke werden zu einer neuen Einheit gebündelt.”
- Saved Valerie quality reference: `/home/agent/family/Lernen/Valerie/Mathe_Uebungsblaetter_Stellenwert_Zahlenstrahl_2026-07-05/_beispiele/Valerie_Uebung_Stellenwert_Zahlenstrahl_Aufbau_v2_ChatGPT_UI_Beispiel.pdf` plus README in the same folder. Use it as a style/didactic benchmark for future Valerie place-value/number-line sheets: 8-page A4 structure with `Aufbau → Grundlagen → Mini-LZK`, yellow/green vertical bands, header with name/time, right points column, large writing spaces, Merke/Tipp boxes before exercises, progression `Merke → Beispiel → guided task → blank task → Mini-LZK`, and gentle difficulty ramp.
- Valerie-specific Stellenwert/Zahlenstrahl reference: see `references/valerie-stellenwert-zahlenstrahl-reference.md`. Key correction: do **not** keep future sheets only at the already-known `E/Z/H/T` level. For summer prep, use a primary-teacher scaffold that briefly activates known content and then advances into `Zehntausender` and `Hunderttausender` with explanations, examples, guided practice, and a Mini-LZK.
- Valerie math curriculum reference: see `references/valerie-math-lp21-grade4-5.md` and local `/home/agent/family/Lernen/Lehrplan/README_Mathematik_Primar_4_5_LP21.md`. Use it to sequence future worksheets according to Swiss LP21/Lehrmittel topics for Primar 4–5, especially the grade-4 chain `Mehr als 1000 → 1000 Tausender → Stellenwert → Ziffern und Zahlen → Zahlenstrahl → Zahlen ordnen → Zahlen untersuchen` and grade-5 transition into fractions/decimals/proportionality.
- Emilia MATHE FiT 5 reference: see `references/emilia-mathe-fit-5-reference.md`, local `/home/agent/family/Lernen/Emilia/Mathe_5_Klasse/MATHE_FiT_5/README_MATHE_FiT_5_Uebersicht.md`, and tracker `/home/agent/family/Lernen/00_Lerntracking/Emilia_Mathe_5_Lerntracking.csv`. For Emilia uploads/tests, map topic to MATHE LZK 5 sequence and update concrete learning gaps/next steps separately from Valerie.

## Pitfalls

- Do not keep overpainting original scans if text becomes pixelated or masks hide parts of tasks.
- OCR of filled worksheets may mix printed text with handwriting; treat it as a guide, not ground truth.
- When recreating math tests, distinguish **given example values** from **solution values**. A blank practice sheet must not accidentally prefill step-by-step answers in tables, number lines, or result boxes; render and visually inspect for unintended answers before delivery.
- Long exercise headings may overlap the points column or value-table labels; wrap titles before PDF generation or inspect with a contact sheet. For `M HT ZT T H Z E` tables, leave extra vertical spacing above the grid so labels do not collide with task text.
- Contact sheets often reveal page-break problems that `pdfinfo` cannot: tables split after one row, a heading stranded at page bottom, answer spaces pushed to the next page, answer fields too close to instructions, or insufficient work space for solution paths. Move the page break/spacing or wrap the section with `KeepTogether` and render again before delivery.
- If a visual QA pass finds issues, patch the generator and rerender all PDFs before sending; do not handwave minor layout defects in school worksheets because print legibility is the deliverable.
- Some generated missing-digit, card-ordering, or point-moving puzzles can have more than one solution; brute-force verify them before finalizing and either choose tasks with a clear expected answer or note acceptable alternatives in the solution sheet.
- Avoid sending child test images to external APIs unless the user explicitly approves the privacy implications.

## Example verification commands

```bash
pdfinfo worksheet.pdf | grep -E 'Pages|Page size|File size'
pdftoppm -r 110 -png worksheet.pdf /tmp/render_prefix
```

Then build a contact sheet with PIL and inspect it using vision.