writing-worksheet-topics

name	writing_worksheet_topics
description	How to write standalone, printable worksheet activities for the Math Worksheet book (Grades 6–8). Focuses on quality, variety, and page efficiency — exactly 3 worksheets per topic to keep the book under 200 pages.
resources	["resources/complete_example.tex","resources/activity_examples.md","resources/tikz_toolkit.md"]

Writing Worksheet Topics — Math Worksheet Activity Book

What This Book Is

A collection of standalone, printable math activities — not drill sheets. Each topic has exactly 3 worksheets, each a different activity type (error hunts, code crackers, data analysis, scenarios, graph challenges, etc.). Every worksheet is self-contained, ~1 page, classroom-ready.

No teaching content. Students should already know the concept. The answer key teaches instead.

Aspect	Value
Worksheets per topic	Exactly 3 (different activity types)
Answer format	\worksheetAnswer{} — bold final answer + teaching explanation
Page target	Under 200 pages total
Question numbering	\wsQ (auto-increments, resets per \worksheetHeader)
B&W printing	All colback=white — only title bars carry color

How It Differs from Other Books

	Study Guide	Workbook	Puzzles	Worksheet
Teaching	Extensive	Quick review	None	None (answers teach)
Problems	\prob drill	\prob drill	Puzzle envs	Activity envs + \wsQ
Answers	\answer{}	\answerExplain{}{}	\puzzleAnswer{}	\worksheetAnswer{}

---

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.

Source folder	Write to
topics/	topics_worksheet/
topics_additional/	topics_worksheet_additional/
topics_modified/	topics_worksheet_modified/

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

Activity	Items
speedDrill	4–6
matchIt	4–5 pairs
sortCut	4–6 cards, 2–3 bins
errorDetective	2–3
mathScenario	3–4 questions
inputOutput	1–2 machines, 3–4 blanks
explainIt	1–2 prompts
dataAnalysis	1 data set, 3–4 questions
graphIt	1 graph, 3–4 tasks
tableChallenge	1–2 tables, 4–6 blanks
codeCracker	4–6
circleIt	8–10 bubbles
colorByAnswer	5–6
drawSolve	2–3

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.

Environment	Icon	Color	Best for	Key helpers
speedDrill	Stopwatch	Orange	Fluency, quick computation	\timerBadge{N}
matchIt	Link	Blue	Connecting concepts	\matchRow{L}{R}
errorDetective	Magnifying glass	Red	Common mistake analysis	\errorWork{text}
sortCut	Scissors	Orange	Classification	\cutCard{}, \wsSortBin[color]{}
mathScenario	Globe	Teal	Real-world multi-step	\scenarioItem{name}{val}
inputOutput	Gears	Teal	Patterns, algebraic rules	Tables with \answerBlank
explainIt	Speech bubble	Blue	Written reasoning	\writeLines{N}
dataAnalysis	Chart bar	Indigo	Statistics, data interpretation	Data tables
graphIt	Chart line	Green	Coordinate plane, graphing	TikZ grids
tableChallenge	Table	Purple	Ratio/function tables	Tables with blanks
codeCracker	Lock	Slate	Decoding challenge	Code key + problems
drawSolve	Paintbrush	Purple	Visual/geometric	\drawSpace[height]
circleIt	Pointing hand	Pink	Identification	\numberBubbles{list}

---

Helper Commands

Command	Purpose
\worksheetHeader{title}	New-page banner with name/date fields
\wsQ	Auto-numbered question
\answerBlank[width]	Underlined blank
\worksheetAnswer{text}	Comprehensive answer (after \end{env})
\worksheetSep	Decorative divider
\worksheetDone	End-of-topic celebration banner

---

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