Writing Worksheet Topics

How It Differs from Other Books

Page Budget — Non-Negotiable

~44 topics × 3.5 pp = 154 pp content + 40 pp overhead = ~194 pp ✅

Stay compact: 3 worksheets/topic, \wsQ + \dotfill inline format, no tables inside activity environments, TikZ max 4cm tall, \drawSpace[3cm] not [5cm], \writeLines{3} not [6], 4–5 match pairs not 6–8.

Quality Protocol — THINK → PLAN → WRITE → VERIFY

THINK

Read the Study Guide source file. Identify 2–4 core skills, vocabulary, number ranges, common mistakes, and real-world contexts.

PLAN

Choose 3 different activity environments before writing. Target cognitive mix:

• 1 fluency (speedDrill, codeCracker, matchIt, circleIt)
• 1 analysis (errorDetective, dataAnalysis, inputOutput)
• 1 application (mathScenario, graphIt, explainIt, tableChallenge, drawSolve, sortCut)

Plan specific numbers and scenarios. Do the math before writing.

WRITE

Clear, unambiguous questions. Every question has a definite answer. Age-appropriate contexts. Bold key terms with \textbf{}. Use \wsQ for questions.

VERIFY — Mandatory

1. Re-compute every numerical answer independently. Watch for: sign errors, fraction reciprocals, percent part/whole confusion, coordinate x/y mix-ups, order of operations, area formula errors.
2. Re-read every explanation. Does it teach, or just restate the answer?
3. Check explanation matches answer. Easy to write correct math but wrong explanation.
4. Verify item counts match the targets below.

Workflow

Step 0 — Discover Topics

python3 scripts/get_chapter_topic_facts.py --chapter <N>

Returns: grade level, age range, chapter title, core/additional/modified topics, summaries.

Step 1 — Read Study Guide Source

Read each source file before writing. Extract concepts, vocabulary, difficulty, common mistakes.

Step 2 — Write 3 Activities Per Topic

Follow the Quality Protocol. Same filename as the source file.

Step 3 — Compile and Verify

latexmk -xelatex -output-directory=build -interaction=nonstopmode -f tests/test_worksheet_ch<N>.tex
grep -i 'error\|undefined' build/test_worksheet_ch<N>.log | grep -v Warning | head -20

Topic File Structure

See resources/complete_example.tex for a full example. The skeleton:

\section{Topic Title}
\setcounter{wsNumber}{0}

\begin{worksheetSkills}
\begin{itemize}
    \item Skill 1
    \item Skill 2
\end{itemize}
\end{worksheetSkills}

\worksheetHeader{Catchy Title 1}
\begin{activityEnv}{Title}
\wsQ Question \dotfill \answerBlank[5cm]
\end{activityEnv}
\worksheetAnswer{1.~$\mathbf{answer}$. Teaching explanation.}

\worksheetHeader{Catchy Title 2}
\begin{differentEnv}{Title}
% ...
\end{differentEnv}
\worksheetAnswer{...}

\worksheetHeader{Catchy Title 3}
\begin{thirdEnv}{Title}
% ...
\end{thirdEnv}
\worksheetAnswer{...}

\worksheetDone

Critical Rules

1. Exactly 3 Worksheets Per Topic

All 3 must use different activity environments. This keeps the book under 200 pages.

2. \worksheetAnswer{} Placement

One per worksheet, placed immediately after \end{environment} (outside, not inside).

3. Answer Format: Bold Answer + Teaching Explanation

The student has just learned this topic — the answer key is a teaching moment.

Format: 1.~$\mathbf{answer}$. Method name, intermediate steps, reasoning.

• Start with bold final answer
• Name the method/rule (e.g., "Keep-Change-Flip", "inverse operations")
• Show intermediate steps
• Include a check where appropriate (\checkmark)
• Number items 1.~, 2.~ to match \wsQ

4. No \prob, \answer{}, or \answerExplain{}{}

Use only \wsQ and \worksheetAnswer{}. No \resetProblems.

5. Item Count Targets

6. No Tables Inside Activity Environments

Use \wsQ + \dotfill + \answerBlank instead. Tables are OK inside tableChallenge/dataAnalysis where the table IS the content.

7. White Backgrounds

All colback=white. No \rowcolor{} on table rows.

8. Math in $...$

Use \times, \div. Bold key terms with \textbf{}.

Activity Environment Catalog

See resources/activity_examples.md for LaTeX patterns for each environment.

Helper Commands

Writing for the Target Audience

Get grade level and age range from the script. Never hard-code grade assumptions.

OFF-LIMITS for Grades 6–8: simple coloring pages, base-ten blocks, tracing, baby cut-and-paste, counting activities.

Works well: error analysis, code crackers, data with real-world sets, multi-step scenarios, function machines, graph interpretation, sorting with justification, explain-your-reasoning, table patterns.

Good contexts: shopping, phone plans, sports stats, recipes, travel, budgeting, science data, gaming. Avoid: counting toys, sharing stickers.

Creative Freedom

• Choose activity types that best fit the topic — no rigid template
• Invent new activity formats when the catalog doesn't fit (add to VM_packages/VMfunWorksheet.sty)
• Use diverse character names (Mia, Leo, Zara, Marcus, Priya, Jordan, Kai, Aisha…)
• Create custom TikZ visuals (see resources/tikz_toolkit.md)
• New environments must: colback=white, use ws* colors, include Font Awesome icon, be tcolorbox-based + breakable, match 8pt arc + 1.5pt boxrule

What to Omit

Never use in worksheet files: \begin{conceptBox}, \begin{stepsBox}, \begin{vocabBox}, \begin{workedExample}, \begin{learningGoals}, \topicTitle{}, \begin{quickReview}, \puzzleAnswer{}, \prob, \answer{}, \answerExplain{}{}, \resetProblems, \rowcolor{}, \writeAnsQuiz.

Final Checklist

• Ran discovery script, read all Study Guide source files
• File in correct folder with matching filename
• \section{} + \setcounter{wsNumber}{0} + \begin{worksheetSkills}
• Exactly 3 worksheets with 3 different environments
• Each has \worksheetAnswer{} outside \end{env} with bold answer + teaching explanation
• Every answer verified by independent computation
• Every explanation re-read for accuracy and teaching value
• Uses \wsQ, no \prob/\answer{}/\answerExplain{}{}
• \worksheetDone at end
• White backgrounds, math in $...$, age-appropriate content
• Compiled successfully