| name | writing_puzzles_topics |
| description | How to write high-quality, page-budgeted puzzle topic files for the Puzzles & Brain Teasers book. Grade-independent; uses the discovery script to determine grade, audience, and topics. |
Writing Puzzle Topics — Math Puzzles & Brain Teasers
Overview
The Puzzles & Brain Teasers book turns math practice into play. Each topic file contains exactly 3 puzzles (core) or exactly 2 puzzles (additional/modified) that exercise a specific math skill through creative formats — mystery numbers, code breakers, logic puzzles, brain teasers, number pyramids, and more.
This is not a textbook. It does not teach concepts. Students should already know the topic from the Study Guide. The puzzles make them apply what they learned in a playful, challenging way. The answer explanations show how to arrive at the correct answer — the student learns by seeing the steps, not by being lectured.
Book Identity
| Aspect | Puzzles & Brain Teasers |
|---|
| Purpose | Engage students with math through puzzles and games |
| Teaching in puzzles | None — puzzles assume knowledge |
| Teaching in answers | No direct teaching — show the steps to reach the answer (1–2 lines) |
| Puzzles per core topic | Exactly 3 (hard limit) |
| Puzzles per additional/modified topic | Exactly 2 (hard limit) |
| Answer format | \puzzleAnswer{explanation} — collected at book's back |
| Page target per core topic | 1.5 pages (not 2, not 3) |
| Page target per additional/modified topic | 1 page |
| Color palette | Purple/teal/gold |
| Personality | Playful, challenging, surprising |
How It Differs from Other Book Types
| Aspect | Study Guide | Workbook | Quiz | Puzzles |
|---|
| Purpose | Teach + practice | Practice | Assess | Engage & challenge |
| Teaching | Extensive | Quick review | None | None — answers show steps |
| Problem type | \prob drill | \wsQ activities | \quizQ test | Puzzle environments |
| Visual variety | Moderate | Moderate | High | Very high |
| Answer system | \answer{} | \answerExplain{}{} | \answerExplain{}{} | \puzzleAnswer{} |
| Student experience | "Learn this" | "Practice this" | "Show what you know" | "Can you crack this?" |
| Tone | Encouraging teacher | Steady coach | Neutral examiner | Playful challenger |
Page Budget — THE CRITICAL CONSTRAINT
Target: 150–170 pages total. This is the single most important constraint. Every decision must serve compactness.
| Component | Pages |
|---|
| Front matter (cover, welcome, how-to-use, supplies, symbols, puzzle tracker, TOC) | ~10 |
| Chapter openers | ~5–7 |
| Core topics × ~1.5 pages each | varies |
| Additional/modified topics × ~1 page each | varies |
| Puzzle Solutions (back of book) | ~12–15 |
| Target total | 150–170 |
Hard Rules for Staying Compact
- Exactly 3 puzzles per core topic. Not 4, not 5, not 8. Three.
- Exactly 2 puzzles per additional/modified topic. Not 3.
- No puzzle exceeds ⅓ of a page. If a TikZ visual is too tall, scale it down or simplify.
- Instructions: 1–2 sentences per puzzle. Students should instantly understand what to do.
- puzzleGoals: exactly 2–3 items. Not 4–5.
- Use
\medskip not \bigskip. Let tcolorboxes provide breathing room.
- TikZ visuals: max 3.5 cm tall. Use
[scale=0.7] or [scale=0.6] when needed.
- Use
multicols{2} inside puzzles when you have side-by-side sub-problems.
- No blank lines between puzzle answer and next puzzleSep.
Quality Protocol — THINK → PLAN → WRITE → VERIFY
THINK (before writing anything)
Read the Study Guide source file. Extract:
- What concepts and vocabulary the topic covers
- What number ranges and difficulty level are appropriate
- What types of representations are used (number lines, grids, tables, models)
- What common mistakes students make with this topic
- What real-world contexts connect to this topic
PLAN (before writing a single line of LaTeX)
- Choose 3 different puzzle environments — every puzzle must use a different container. Write down which environments you'll use and why.
- Design the difficulty arc: Puzzle 1 (★1) → Puzzle 2 (★2) → Puzzle 3 (★3).
- Choose specific numbers. Work out the math on scratch paper. Confirm every answer is correct before writing LaTeX.
- Plan variety across the chapter. If Topic 1 opens with a mysteryNumberBox, Topic 2 should open with something different. Track which environments appear in which position across all topics.
WRITE (now you can write LaTeX)
- Clear, unambiguous puzzle instructions.
- Every puzzle has exactly one definite answer (or a constrained set of valid answers for open-ended puzzles).
- Age-appropriate contexts and vocabulary.
- Bold key math terms with
\textbf{}.
- All math in
$...$. Use \times for multiplication, \div for division.
VERIFY (mandatory — do not skip)
- Re-solve every puzzle independently. Work through each puzzle from scratch as if you're the student. Write down your work.
- Compare your solution to
\puzzleAnswer{}. Does the explanation match? Is the final answer correct?
- Re-read every explanation. Does it show the steps to reach the answer, or just restate the answer? Keep explanations to 1–2 lines — concise but complete.
- Check explanation matches answer. It's easy to write correct math but copy the wrong final number.
- Verify puzzle count: exactly 3 for core, exactly 2 for additional/modified.
- Check page budget: will this topic fit in ~1.5 pages?
Common error hotspots to double-check:
- Negative number operations (signs)
- Fraction arithmetic (forgetting to flip for division)
- Percent calculations (part vs whole confusion)
- Decimal placement after multiplication
- Order of operations (PEMDAS/BODMAS)
- Area/perimeter formula mix-ups
- Coordinate plane (x/y swap, quadrant signs)
Workflow
Step 0 — Discover Topics with the Script
Before writing anything, run the discovery script:
python3 scripts/get_chapter_topic_facts.py --chapter <N>
The script tells you:
- Grade level and age range — calibrate language complexity and number difficulty
- Chapter title — the mathematical domain
- Core topics — list with file paths and content summaries
- Additional topics — state-specific topics (with which states use them)
- Modified topics — state-specific variants (with which states use them)
To list all chapters:
python3 scripts/get_chapter_topic_facts.py --list-chapters
Use the output to plan: count how many files you need (core + additional + modified), read summaries to understand scope.
Step 1 — Read Study Guide Source Files
For every topic, read the corresponding Study Guide source file before writing. This is not optional.
| Script output prefix | Read from | Write to |
|---|
topics/ | topics/<filename>.tex | topics_puzzles/<filename>.tex |
topics_additional/ | topics_additional/<filename>.tex | topics_puzzles_additional/<filename>.tex |
topics_modified/ | topics_modified/<filename>.tex | topics_puzzles_modified/<filename>.tex |
The puzzle file must use the exact same filename as the Study Guide file.
Step 2 — Write Puzzles (Follow the Quality Protocol)
Apply THINK → PLAN → WRITE → VERIFY for each topic. Write all core, additional, and modified topics for the chapter before compiling.
Step 3 — Compile and Verify
After writing ALL topics for the chapter:
latexmk -xelatex -output-directory=build -interaction=nonstopmode -f tests/test_puzzles_ch<N>.tex
grep -i 'error\|undefined' build/test_puzzles_ch<N>.log | grep -v Warning | head -20
Open the PDF. Check:
Topic File Structure
Core Topic (3 puzzles, ~1.5 pages)
% ============================================================================
% Section X.Y — Topic Title — PUZZLES
% CCSS X.XXX.X.X
% ============================================================================
\section{Topic Title}
\puzzlePageTitle{Topic Puzzles}
\begin{puzzleGoals}
\begin{itemize}
\item Skill 1
\item Skill 2
\item Skill 3
\end{itemize}
\end{puzzleGoals}
% ── PUZZLE 1 ────────────────────────────────────────────────────────────
\begin{mysteryNumberBox}{Title}
\puzzleDifficulty{1}
% ... puzzle content (1–2 sentence instructions, then the puzzle) ...
\end{mysteryNumberBox}
\puzzleAnswer{Step-by-step explanation with $\mathbf{answer}$ bolded.}
\puzzleSep
% ── PUZZLE 2 ────────────────────────────────────────────────────────────
\begin{puzzleBox}{Title}
\puzzleDifficulty{2}
% ... puzzle content ...
\end{puzzleBox}
\puzzleAnswer{Step-by-step explanation with $\mathbf{answer}$ bolded.}
\puzzleSep
% ── PUZZLE 3 ────────────────────────────────────────────────────────────
\begin{brainTeaserBox}{Title}
\puzzleDifficulty{3}
% ... puzzle content ...
\end{brainTeaserBox}
\puzzleAnswer{Step-by-step explanation with $\mathbf{answer}$ bolded.}
\vspace{4mm}
\puzzleComplete
Additional/Modified Topic (2 puzzles, ~1 page)
Same structure but only 2 puzzles (★1 and ★2). Same filename as source file. Add a header comment noting Supplementary (State-specific) or Modified.
Answer System — \puzzleAnswer{}
How It Works
\puzzleAnswer{text} produces no visible output where it appears. Answers are collected during compilation and printed in the "Puzzle Solutions" chapter via \printPuzzleAnswers.
Where to Place It
Immediately after the closing \end{...} of each puzzle environment:
\end{mysteryNumberBox}
\puzzleAnswer{The number is $\mathbf{42}$. Clue 1 says it's even, ...}
\puzzleSep
How to Write Good Explanations
Answer explanations are not lectures — they show the student how to get to the correct answer in 1–2 lines. The student learns by seeing the steps. Keep it concise.
% ✗ BAD — bare answer, no steps
\puzzleAnswer{$42$}
% ✗ BAD — restates without showing work
\puzzleAnswer{The answer is $42$.}
% ✗ BAD — too long, reads like a lesson
\puzzleAnswer{The number is $\mathbf{42}$. First, let's review what
even numbers are. Even numbers are divisible by $2$. Now, from
Clue~1, we know our number is even. Next, let's think about
digit sums. A digit sum is when you add all the digits together.
From Clue~2, the digits must sum to $6$ ...}
% ✓ GOOD — concise steps to the answer (1–2 lines)
\puzzleAnswer{The number is $\mathbf{42}$. It's even (Clue~1),
between $40$–$50$ (Clue~3), and $4+2=6$ (Clue~2).}
% ✓ GOOD — multi-part, still concise
\puzzleAnswer{(1)~$A = \tfrac{1}{2} \times 8 \times 5 = \mathbf{20}$\,cm$^2$.
(2)~$A = \tfrac{1}{2} \times 16 \times 5 = \mathbf{40}$\,cm$^2$ — doubling the base doubles the area.}
% ✓ GOOD — strategy explanation, concise
\puzzleAnswer{Place $9$ in the hundreds place ($9 \times 100 = 900$) to make
the largest number: $\mathbf{987}$.}
Explanation Rules
- Every puzzle gets exactly one
\puzzleAnswer{} — placed after the environment closes.
- Bold the final answer using
$\mathbf{...}$.
- Show the steps to reach the answer in 1–2 lines. Concise but complete.
- Don't lecture. The student learns by seeing the steps, not by reading a lesson.
- Numbered sub-answers
(1), (2) when a puzzle has multiple parts.
- Open-ended puzzles (games, creative) — explain the optimal strategy or give an example valid answer.
- Never use
\answer{}, \answerExplain{}{}, or \answerMC{} in puzzle files. Only \puzzleAnswer{}.
Double-Check Your Explanations
After writing each \puzzleAnswer{}, re-read it and ask:
- Does it show the steps to reach the answer (not just restate it)?
- Is it 1–2 lines (not a paragraph)?
- Is every calculation correct?
- Does the bolded final answer match the computation?
Puzzle Container Environments
Every puzzle must be wrapped in one of these. Use a different environment for each puzzle in a topic.
Primary Environments (VMfunPuzzles.sty)
| Environment | Icon | Best For |
|---|
puzzleBox[color]{title} | Puzzle piece | Generic — pyramids, grids, any format |
mysteryNumberBox[title] | Magnifying glass | "Who Am I?" clue puzzles |
oddOneOutBox[title] | Eye | "Which doesn't belong?" |
targetNumberBox[color]{title} | Bullseye | "Build this number" games |
scrambleBox[title] | Shuffle | Digit/equation scrambles |
brainTeaserBox[title] | Lightbulb + Brain | Multi-step reasoning |
logicPuzzleBox[title] | Gear | Clue-based elimination |
mathGameBox[title] | Dice | 2-player games |
Also Available (from VMfunPractice.sty and VMfunExtras.sty)
| Environment | Best For |
|---|
codeBreaker{title} | Solve problems → decode a secret word |
riddleBox{title} | Math riddles |
sortBox{title} | Classify/sort numbers or shapes |
fillTable{title} | Pattern tables, function machines |
patternBox{title} | Pattern discovery |
mathTrail{title} | Connected trail of problems |
TikZ Visual Commands
Puzzle-Specific (VMfunPuzzles.sty)
| Command | Purpose |
|---|
\pyramidCell[color]{row}{col}{value} | Filled cell in number pyramid |
\pyramidBlank[color]{row}{col} | Blank cell for student |
\magicGrid{size}{target}{values} | Magic square grid with target sum |
\puzzleCircles[color]{list} | Numbers in circles (comma-separated) |
\numberCross[color]{center}{top}{right}{bottom}{left} | Cross-shaped puzzle |
\targetRing[color]{number} | Bullseye visual |
\digitCard[color]{digit} | Single digit card |
\scrTile{text} | Scramble tile |
Reusable Math Visuals (VMfunMath.sty)
Use these standard visuals freely with puzzle palette colors (e.g., puzzlePurple):
\fractionBar, \fractionCircle, \numberLine, \arrayGrid, \barGraph, \columnAdd, \columnSub, \baseTenBlocks, \perimeterRect, \dotGroups.
Custom TikZ — You Are Encouraged to Create
When no existing command fits, write custom TikZ directly. Keep it compact (max 3.5 cm tall, use [scale=0.7] or smaller as needed). Use the puzzle color palette: puzzlePurple, puzzleTeal, puzzleGold, puzzleMagenta.
Good candidates for custom TikZ: ratio tables, number lines with marked points, coordinate planes, geometric shapes with dimensions, function machines, bar models, percent bars.
Utility Commands
| Command | Purpose |
|---|
\puzzleHint{text} | Inline hint with magnifying glass |
\puzzleDifficulty{1|2|3} | Difficulty badge (1=easy, 3=hard) |
\puzzleSep | Decorative divider between puzzles |
\puzzleComplete | End-of-section celebration banner |
\puzzleAnswer{text} | Collect answer for Puzzle Solutions |
\mysteryClue{text} | Auto-numbered clue (inside mysteryNumberBox) |
\resetClues | Reset clue counter |
\gameSupply{text} | Game supply list item (inside mathGameBox) |
\answerBlank[width] | Underlined blank for student answer |
\resetProblems / \prob | Numbered sub-questions within a puzzle |
Puzzle Type Catalog
Use this for inspiration. You are encouraged to invent new puzzle types — creativity makes the book special. Below are proven formats organized by complexity.
★1 Warm-Up Puzzles (confidence builders)
| Type | Environment | Description |
|---|
| Mystery Number | mysteryNumberBox | 3–5 clues to deduce a number. Use \mysteryClue{} |
| Odd One Out | oddOneOutBox | 4–5 items, one doesn't belong. Use \puzzleCircles{} |
| Code Breaker | codeBreaker | Solve 4–5 problems, match answers to letters to spell a word |
| True or False | puzzleBox | 4–5 statements, circle T or F. Quick and accessible |
| Riddle | riddleBox | "I am a number..." playful math riddle |
★2 Skill Stretchers (requires thinking)
| Type | Environment | Description |
|---|
| Number Pyramid | puzzleBox | Each brick = sum of two below. Use \pyramidCell/\pyramidBlank |
| Magic Grid | puzzleBox | Rows/cols sum to target. Use \magicGrid or custom table |
| Digit Scramble | scrambleBox | Build specific numbers from digit cards. Use \digitCard{} |
| Target Number | targetNumberBox | Create a target using given values and operations |
| Pattern Fill | fillTable or patternBox | Discover and extend a number pattern |
| Function Machine | fillTable | Input → rule → output (find the rule or missing values) |
| Code Breaker (harder) | codeBreaker | Solve computation problems → decode message |
| Math Trail | mathTrail | Chain of connected problems (answer feeds next) |
| Sorting | sortBox | Classify items by mathematical property |
★3 Brain Busters (multi-step reasoning)
| Type | Environment | Description |
|---|
| Brain Teaser | brainTeaserBox | Open-ended, multi-step reasoning challenge |
| Logic Puzzle | logicPuzzleBox | Clue-based elimination (with table or grid) |
| Math Game | mathGameBox | 2-player strategy game. Use \gameSupply{} |
| Reverse Engineering | brainTeaserBox | Given the answer, find the question |
| Create Your Own | puzzleBox | Student creates a problem meeting constraints |
Inventing New Types
You have full creative freedom to design original puzzles. Crosswords, mazes, treasure maps, matching games — anything that makes a student think mathematically. When inventing:
- Ensure there's one clear correct answer (or a well-defined set of valid answers)
- Keep instructions to 1–2 sentences
- Test-solve it yourself before writing the
\puzzleAnswer{}
- Use existing container environments; create a new one only if nothing fits
Difficulty Progression
Every topic follows the same arc:
- Puzzle 1 (★1) — Confidence builder. Quick solve, builds momentum.
- Puzzle 2 (★2) — Skill stretcher. Requires more thinking but clearly doable.
- Puzzle 3 (★3) — Brain buster. Makes the student pause and think deeply.
Across a chapter, vary which puzzle types appear at each difficulty level. Don't give every topic the same "mystery → code breaker → brain teaser" formula. Surprise the reader. If Topic 1 starts with a mystery number, Topic 2 might start with an odd-one-out or a riddle.
Writing for the Target Audience
The discovery script outputs the grade level and student age range. Use those values to calibrate language complexity, number difficulty, and puzzle depth. Do not hardcode ages — the script provides them.
Universal Guidelines (All Grades)
- Short, crystal-clear instructions. A student should understand without adult help.
- No trick questions. Every puzzle has a clear, unambiguous answer.
- Kid-friendly contexts. Use diverse names (Mia, Leo, Zara, Marcus, Aiden, Priya) and relatable scenarios (games, food, sports, school, animals).
- Math in
$...$ always. Use \times for multiplication, \div for division.
- Bold key terms on first use:
\textbf{ratio}, \textbf{equivalent}.
- Visual clarity. TikZ visuals: clean, uncluttered, no tiny text.
- Emotional safety. Puzzles are fun challenges, not tests. The tone is playful.
Variety Across a Chapter
Within a single chapter, track your environment usage. No two consecutive topics should open with the same puzzle type. Aim for good variety — here's an example rotation for a 6-topic chapter:
| Topic | Puzzle 1 (★1) | Puzzle 2 (★2) | Puzzle 3 (★3) |
|---|
| 1 | mysteryNumberBox | puzzleBox (pyramid) | brainTeaserBox |
| 2 | oddOneOutBox | codeBreaker | logicPuzzleBox |
| 3 | riddleBox | scrambleBox | brainTeaserBox |
| 4 | mysteryNumberBox | targetNumberBox | mathGameBox |
| 5 | codeBreaker | fillTable | brainTeaserBox |
| 6 | oddOneOutBox | puzzleBox (magic grid) | logicPuzzleBox |
Real-World Contexts
Use contexts that match the student's age (from the discovery script). Good examples: shopping deals, cooking/recipes, sports stats, gaming, travel, science, money, school life, nature. Use diverse character names (Mia, Leo, Zara, Marcus, Aiden, Priya).
Never use: Babyish contexts, overly abstract problems with no context, or scenarios involving violence, alcohol, or inappropriate content.
Complete Example — Core Topic
Below is a complete core topic file demonstrating all conventions. Study it carefully.
% ============================================================================
% Section 2.4 — GCF and LCM — PUZZLES
% CCSS 6.NS.B.4
% ============================================================================
\section{GCF and LCM}
\puzzlePageTitle{GCF \& LCM Puzzles}
\begin{puzzleGoals}
\begin{itemize}
\item Find the greatest common factor of two numbers
\item Find the least common multiple of two numbers
\end{itemize}
\end{puzzleGoals}
% ── PUZZLE 1: Mystery Number (★1) ──────────────────────────────────────
\begin{mysteryNumberBox}{GCF Detective}
\puzzleDifficulty{1}
I am the \textbf{greatest common factor} of two numbers!
\resetClues
\mysteryClue{My two numbers are $24$ and $36$.}
\mysteryClue{I divide both numbers evenly.}
\mysteryClue{No number bigger than me divides both.}
\mysteryClue{I am greater than $10$.}
What number am I? \answerBlank[2cm]
\end{mysteryNumberBox}
\puzzleAnswer{The GCF is $\mathbf{12}$. Factors of $24$: $1,2,3,4,6,8,12,24$.
Factors of $36$: $1,2,3,4,6,9,12,18,36$. Common factors: $1,2,3,4,6,12$.
The greatest is $\mathbf{12}$.}
\puzzleSep
% ── PUZZLE 2: Code Breaker (★2) ────────────────────────────────────────
\begin{codeBreaker}{LCM Code Cracker}
\puzzleDifficulty{2}
Find the \textbf{LCM} of each pair. Arrange letters from
\textbf{smallest to largest} answer to reveal the secret word.
\resetProblems
\begin{multicols}{2}
\prob LCM($4,6$) = \answerBlank \quad $\to$ \textbf{N}
\prob LCM($3,5$) = \answerBlank \quad $\to$ \textbf{I}
\prob LCM($6,8$) = \answerBlank \quad $\to$ \textbf{E}
\prob LCM($5,7$) = \answerBlank \quad $\to$ \textbf{C}
\end{multicols}
Secret word: \answerBlank[4cm]
\end{codeBreaker}
\puzzleAnswer{(1)~LCM($4,6$)$=\mathbf{12}$$\to$N.
(2)~LCM($3,5$)$=\mathbf{15}$$\to$I.
(3)~LCM($6,8$)$=\mathbf{24}$$\to$E.
(4)~LCM($5,7$)$=\mathbf{35}$$\to$C.
Smallest to largest: $12,15,24,35$$\to$N,I,E,C.
Secret word: $\mathbf{NICE}$.}
\puzzleSep
% ── PUZZLE 3: Brain Teaser (★3) ────────────────────────────────────────
\begin{brainTeaserBox}{The Bus Stop Problem}
\puzzleDifficulty{3}
Bus~A comes every $\mathbf{8}$~min. Bus~B comes every
$\mathbf{12}$~min. Both arrive together at 9:00~AM.
\resetProblems
\prob When will they next arrive together? \answerBlank[3cm]
\prob How many times does Bus~A come before they meet again? \answerBlank
\end{brainTeaserBox}
\puzzleAnswer{Find LCM($8,12$). Multiples of $8$: $8,16,\mathbf{24},\ldots$
Multiples of $12$: $12,\mathbf{24},\ldots$ LCM$=\mathbf{24}$~min.
(1)~Next together: $9{:}00+24=\mathbf{9{:}24}$~AM.
(2)~Bus~A at min $8,16,24$ — that's $\mathbf{3}$ times.}
\vspace{4mm}
\puzzleComplete
Pre-Write Checklist
Before writing each topic file, confirm:
Post-Write Checklist
After writing each topic file, confirm:
