writing-puzzles-topics

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

1. Exactly 3 puzzles per core topic. Not 4, not 5, not 8. Three.
2. Exactly 2 puzzles per additional/modified topic. Not 3.
3. No puzzle exceeds ⅓ of a page. If a TikZ visual is too tall, scale it down or simplify.
4. Instructions: 1–2 sentences per puzzle. Students should instantly understand what to do.
5. puzzleGoals: exactly 2–3 items. Not 4–5.
6. Use \medskip not \bigskip. Let tcolorboxes provide breathing room.
7. TikZ visuals: max 3.5 cm tall. Use [scale=0.7] or [scale=0.6] when needed.
8. Use multicols{2} inside puzzles when you have side-by-side sub-problems.
9. 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)

1. Choose 3 different puzzle environments — every puzzle must use a different container. Write down which environments you'll use and why.
2. Design the difficulty arc: Puzzle 1 (★1) → Puzzle 2 (★2) → Puzzle 3 (★3).
3. Choose specific numbers. Work out the math on scratch paper. Confirm every answer is correct before writing LaTeX.
4. 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)

1. Re-solve every puzzle independently. Work through each puzzle from scratch as if you're the student. Write down your work.
2. Compare your solution to \puzzleAnswer{}. Does the explanation match? Is the final answer correct?
3. 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.
4. Check explanation matches answer. It's easy to write correct math but copy the wrong final number.
5. Verify puzzle count: exactly 3 for core, exactly 2 for additional/modified.
6. 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:

• Every topic fits within 1.5 pages (core) or 1 page (additional/modified)
• Exactly 3 puzzles per core topic, 2 per additional/modified
• Every puzzle uses a different container environment
• All \puzzleAnswer{} entries are present
• No LaTeX errors or undefined references
• TikZ visuals render correctly and are compact

---

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

1. Every puzzle gets exactly one \puzzleAnswer{} — placed after the environment closes.
2. Bold the final answer using $\mathbf{...}$.
3. Show the steps to reach the answer in 1–2 lines. Concise but complete.
4. Don't lecture. The student learns by seeing the steps, not by reading a lesson.
5. Numbered sub-answers (1), (2) when a puzzle has multiple parts.
6. Open-ended puzzles (games, creative) — explain the optimal strategy or give an example valid answer.
7. 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:

• I ran get_chapter_topic_facts.py and know the grade/age/chapter context
• I read the corresponding Study Guide source file
• I chose 3 different puzzle environments (2 for additional/modified)
• I planned the difficulty arc: ★1 → ★2 → ★3
• I worked out all answers before writing LaTeX
• I checked variety against other topics in this chapter (no repeated openers)

Post-Write Checklist

After writing each topic file, confirm:

• Exactly 3 puzzles (core) or 2 puzzles (additional/modified)
• Every puzzle uses a different container environment
• Every puzzle has \puzzleDifficulty{N}
• Every puzzle has \puzzleAnswer{} immediately after the environment
• Every \puzzleAnswer{} shows steps to reach the answer in 1–2 lines (not just the answer)
• Every \puzzleAnswer{} bolds the final answer with $\mathbf{...}$
• I re-solved every puzzle and confirmed the answers are correct
• I re-read every explanation and confirmed it's concise and correct
• \puzzleSep between puzzles, \puzzleComplete at the end
• Topic fits in ~1.5 pages (core) or ~1 page (additional/modified)
• No \answer{}, \answerExplain{}{}, or \answerMC{} used (only \puzzleAnswer{})