| name | writing_quiz_topics |
| description | How to write standalone, high-quality quiz topic files for math — grade independent. Each quiz is a timed assessment with 6 questions + 1 bonus, strictly 2 pages, with answer explanations that teach. |
Writing Quiz Topics — Math Quiz Book
What This Book Is
A collection of standalone, timed assessments (15 minutes each) mapped 1-to-1 to curriculum topics. Each quiz tests understanding of one topic with 6 questions + 1 bonus challenge. Quizzes are designed to be torn out or photocopied — each stands alone.
No teaching content. The answer explanations teach instead — that's the trick.
| Aspect | Value |
|---|
| Purpose | Assess understanding of a single topic |
| Time per quiz | ~15 minutes |
| Questions per quiz | 6 regular + 1 bonus challenge |
| Teaching content | None — answer explanations teach |
| Visual elements | At least 3 different visual question types per quiz |
| Answers | \answerExplain{answer}{explanation} for every question |
| Page length | Strictly 2 pages per quiz (non-negotiable) |
| Color palette | Indigo/gold (distinct from other book types) |
Page Budget — Non-Negotiable
The quiz book must stay under 180 pages. Every quiz must fit in exactly 2 pages.
Page math: ~45 core topics × 2 pp = 90 pp content + ~40 pp overhead (cover, welcome, TOC, tracker, formula sheet, answer key, back matter) ≈ 130 pp core. State-specific additional topics add ~10–20 more quizzes ≈ 150–170 pp total. This leaves room.
Compactness strategies:
- Use 6 questions (not 7) — this is the default
- Keep TikZ illustrations compact — max 3 cm tall for inline visuals
- Use
\quizWorkSpace[1.5cm] not [3cm] — just enough room
- Prefer
\quizCircle or \quizMC (compact) over \quizMatch (tall)
- Bonus challenge: 2–4 lines of instructions max
- No blank lines between elements beyond what LaTeX commands insert
- If a topic needs large visuals (coordinate grids, data plots), drop to 5 questions + bonus
Quality Protocol — THINK → PLAN → WRITE → VERIFY
This is the most important section. Do not skip any step.
THINK
Read the source topic file. Extract:
- Core skills (2–4 per topic) — what exactly must the student demonstrate?
- Vocabulary — key terms the student should know
- Number ranges — what size numbers, what operations, what complexity?
- Common mistakes — what do students typically get wrong?
- Visual opportunities — what can be drawn, graphed, modeled?
- Real-world contexts — what scenarios resonate with the target age group?
PLAN
Before writing a single line of LaTeX, plan the 6 questions + bonus:
- Choose at least 3 different visual question types (see Question Type Catalog below)
- Plan a difficulty progression — start easy, build up, bonus is hardest
- Plan specific numbers, scenarios, and contexts
- Do the math first. Compute every answer before writing the question.
- Plan which question types to use (multiple choice, true/false, fill-in, comparison, matching, etc.)
Cognitive mix target:
- 1–2 visual-to-symbolic (read a diagram → write the math)
- 1 graph/model interpretation (read a plot, table, or number line)
- 1 comparison, true/false, or error identification
- 1 word problem with illustration or diagram
- 1 fill-in, matching, or table completion
- 1 bonus — multi-step, puzzle-like, or open-ended
WRITE
Write clear, unambiguous questions. Every question has exactly one correct answer (or a clearly defined set). Use age-appropriate real-world contexts. Bold key terms with \textbf{}.
Creative freedom: You have full latitude in question design. Invent engaging scenarios, draw custom TikZ illustrations, use real-world contexts that resonate with the target age group. The catalogs below are a toolbox — not a template. Mix, match, and create new visual types when a topic calls for it.
VERIFY — Mandatory (Do NOT Skip)
-
Re-compute every numerical answer independently. Work backward from your answer to the question. Watch for:
- Sign errors with negatives
- Fraction operations (forgetting to flip the divisor, wrong common denominator)
- Percent calculations (part vs whole confusion)
- Coordinate plane (mixing up x and y, quadrant signs)
- Area/volume formulas (wrong formula, forgetting ½ for triangles)
- Order of operations (PEMDAS/BODMAS)
- Decimal placement
-
Re-read every explanation. Does it teach, or just restate the answer? Every explanation should help a student who got it wrong understand why the correct answer is correct and where they likely went wrong.
-
Check explanation matches answer. It's easy to write correct math but a mismatched explanation.
-
Verify visual accuracy. If you drew a TikZ diagram, do the numbers in the diagram match the question and answer?
-
Count your questions. Exactly 6 regular + 1 bonus. Not 5, not 7, not 8.
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 with file paths and YAML summaries. Use this to know what topics exist before writing.
Step 1 — Read Source Topic Files
Before writing any quiz, you MUST read the corresponding topic file:
| Source folder | Write quiz to |
|---|
topics/ | topics_quiz/ |
topics_additional/ | topics_quiz_additional/ |
topics_modified/ | topics_quiz_modified/ |
Read the source file to understand concepts, vocabulary, skill level, and depth. Do NOT guess — read.
Step 2 — Apply Quality Protocol
THINK → PLAN → WRITE → VERIFY (see above). No shortcuts.
Step 3 — Place the File
Same filename as the source: ch<CC>-<SS>-<slug>.tex
Examples:
topics/ch01-01-what-is-a-ratio.tex → topics_quiz/ch01-01-what-is-a-ratio.textopics_additional/ch03-02-integer-addition.tex → topics_quiz_additional/ch03-02-integer-addition.tex
Quiz File Structure (Mandatory)
Every quiz topic file must follow this exact sequence:
% ============================================================================
% Quiz — Topic Title
% CCSS X.XX.X.X
% ============================================================================
\quizPage{Topic Title}
\quizInfo
\quizInstructions
% --- Question 1 ---
\quizQ Question text...
% visual element here
\answerExplain{answer}{explanation}
% --- Question 2 ---
\quizQ ...
\answerExplain{answer}{explanation}
% --- Questions 3–6 ---
% ...
\quizDivider
% --- Bonus Challenge ---
\begin{bonusChallenge}
\bonusNote
\quizQ Bonus question...
\answerExplain{answer}{explanation}
\end{bonusChallenge}
\quizScoreBox
Required elements (in order):
\quizPage{Title} — banner with auto-numbered quiz and chapter\quizInfo — name/date/score strip (defaults to 7 points; use \quizInfo[N] for custom)\quizInstructions — instruction bar (or \quizInstructions[custom text])- 6 questions using
\quizQ with at least 3 different visual types
\quizDivider — separator before bonusbonusChallenge environment with \bonusNote and 1 question\quizScoreBox — "How did you do?" self-assessment
Answer Explanations — The Heart of Quality
The answer explanation is where learning happens. The student just took a quiz, got some wrong, and now reads the answer key. This is a teaching moment. Make it count.
Format
\answerExplain{short answer}{explanation}
- Short answer: Printed in the Answer Key. Usually one number, word, or symbol. Always wrap math in
$...$.
- Explanation: Stays in source, helps the student understand. Must explain reasoning, not just restate.
Good vs Bad Explanations
% BAD — restates the answer
\answerExplain{$\frac{3}{5}$}{The ratio is $\frac{3}{5}$.}
% GOOD — teaches the reasoning
\answerExplain{$\frac{3}{5}$}{There are $3$ cats and $2$ dogs, so $3 + 2 = 5$
pets total. The part-to-whole ratio of cats is $\frac{3}{5}$.}
% BAD — no method shown
\answerExplain{$x = 12$}{$x = 12$.}
% GOOD — shows method + check
\answerExplain{$x = 12$}{Start with $x + 7 = 19$. Subtract $7$ from both
sides: $x = 19 - 7 = 12$. Check: $12 + 7 = 19$. \checkmark}
% GOOD — explains why wrong answers fail
\answerExplain{B ($14.4$)}{Multiply as whole numbers: $24 \times 6 = 144$.
Count decimal places: $2.4$ has $1$ decimal place, so place the decimal
$1$ spot from the right: $14.4$. Common mistake: writing $1.44$ (too
many decimal places) or $144$ (forgetting the decimal).}
% GOOD — addresses common error
\answerExplain{$-3$}{$5 + (-8) = 5 - 8 = -3$. When adding a negative,
think of it as subtraction. Since $8 > 5$, the result is negative.
Common mistake: writing $13$ (adding instead of subtracting).}
Explanation checklist:
Quiz Environments Reference
Core Structure Commands
| Command | Purpose |
|---|
\quizPage{Title} | Full banner with auto-numbered quiz + chapter |
\quizInfo or \quizInfo[N] | Name/date/score strip (N = total points) |
\quizInstructions | Default instruction bar |
\quizInstructions[text] | Custom instruction text |
\quizQ | Auto-numbered question (indigo circle badge) |
\quizDivider | Light horizontal rule between sections |
\quizScoreBox | "How did you do?" self-assessment at end |
Answer Input Types
| Command | Purpose | Example |
|---|
\quizBlank[width] | Simple underline (default 3cm) | \quizBlank[4cm] |
\quizAnswerLine{label} | Labeled answer line | \quizAnswerLine{Unit rate} |
\quizSentence{op} | Styled ___ op ___ = ___ | \quizSentence{$\div$} |
\quizWorkSpace[height] | Dotted work area (default 2cm) | \quizWorkSpace[1.5cm] |
Multiple Choice and Selection
| Command | Purpose |
|---|
\quizMC{A}{B}{C}{D} | 2×2 multiple choice grid |
\quizCircle{A}{B}{C}{D} | Horizontal answer bubbles |
\quizTF | True/False bubbles |
\quizCompare{left}{right} | Comparison with >/</= bubbles |
Visual Question Helpers
| Command | Purpose | Example |
|---|
\quizGroupPic[shape]{N}{M} | N groups of M shapes | \quizGroupPic[circle]{3}{4} |
bonusChallenge env | Purple box for bonus | Encouraging framing |
\bonusNote | Encouragement text | "This is extra credit" |
quizMatch / \quizMatchRow | Two-column matching | Draw lines between columns |
quizTable env | Fill-in table | \begin{quizTable}{3} |
Reusable Visuals from VMfunMath.sty
Always pass quizIndigo as the color to keep the quiz palette consistent.
| Command | Best for | Example |
|---|
\fractionBar[color]{shaded}{total} | Fraction/ratio models | \fractionBar[quizIndigo]{3}{8} |
\fractionCircle[color]{shaded}{total} | Fraction pie chart | \fractionCircle[quizIndigo]{2}{5} |
\numberLine[step]{start}{end} | Number lines | \numberLine[1]{-5}{5} |
\numberLineFraction[color]{parts} | Fraction number line | \numberLineFraction[quizIndigo]{6} |
\numberBond[color]{whole}{part1}{part2} | Part-whole | \numberBond[quizIndigo]{100}{35}{} |
\arrayGrid[color]{rows}{cols} | Area model | \arrayGrid[quizIndigo]{4}{6} |
\areaGrid[color]{rows}{cols} | Area unit squares | \areaGrid[quizIndigo]{3}{5} |
\perimeterRect[color]{w}{h}{unit} | Labeled rectangle | \perimeterRect[quizIndigo]{8}{5}{cm} |
\barGraph[color]{title}{data}{max} | Bar graph | \barGraph[quizIndigo]{Votes}{A/5,B/3}{8} |
\columnAdd{a}{b} | Vertical addition | \columnAdd{34.7}{28.5} |
\columnSub{a}{b} | Vertical subtraction | \columnSub{53.2}{27.5} |
\dotGroups[color]{groups}{per} | Groups for ratios | \dotGroups[quizIndigo]{3}{4} |
\skipCountArc[color]{start}{end}{step} | Skip counting | \skipCountArc[quizIndigo]{0}{24}{6} |
\baseTenBlocks{H}{T}{O} | Place value | \baseTenBlocks{2}{4}{7} |
\ruler{length}{unit} |
Custom TikZ — Your Best Tool for Quality
Grade 6–8 quizzes need sophisticated visuals. You are encouraged to create custom TikZ diagrams. These make quizzes engaging, visually distinctive, and fun. Below are patterns — adapt, combine, and invent freely.
Coordinate Plane (4-quadrant)
\begin{center}
\begin{tikzpicture}[scale=0.55]
\draw[quizSlateLight, thin] (-5, -5) grid (5, 5);
\draw[quizSlate, thick, <->] (-5.5, 0) -- (5.5, 0) node[right, font=\sffamily\small] {$x$};
\draw[quizSlate, thick, <->] (0, -5.5) -- (0, 5.5) node[above, font=\sffamily\small] {$y$};
\foreach \x in {-5,...,-1, 1,...,5} {
\node[below, font=\sffamily\tiny, text=quizSlate] at (\x, -0.3) {$\x$};
\node[left, font=\sffamily\tiny, text=quizSlate] at (-0.3, \x) {$\x$};
}
\fill[quizIndigo] (3, 4) circle (4pt);
\node[above right, font=\sffamily\small\bfseries, text=quizIndigo] at (3, 4) {$A(3,4)$};
\end{tikzpicture}
\end{center}
Number Line with Negatives
\begin{center}
\begin{tikzpicture}
\draw[quizSlate, thick, <->] (-5.5, 0) -- (5.5, 0);
\foreach \x in {-5,...,5} {
\draw[quizSlate] (\x, -0.15) -- (\x, 0.15);
\node[below, font=\sffamily\footnotesize] at (\x, -0.2) {$\x$};
}
\fill[quizIndigo] (-3, 0) circle (4pt);
\node[above, font=\sffamily\small\bfseries, text=quizIndigo] at (-3, 0.2) {$A$};
\end{tikzpicture}
\end{center}
Ratio Table
\begin{center}
\begin{tikzpicture}
\def\cols{4} \def\colW{1.6cm} \def\rowH{0.8cm}
\fill[quizIndigoLight, rounded corners=3pt] (0, 0) rectangle (\cols*1.6, \rowH);
\node[font=\sffamily\bfseries\small, text=quizIndigoDark] at (0.8, 0.4) {Label};
\node[font=\sffamily\bfseries\small, text=quizIndigoDark] at (2.4, 0.4) {$2$};
\node[font=\sffamily\bfseries\small, text=quizIndigoDark] at (4.0, 0.4) {$4$};
\node[font=\sffamily\bfseries\small, text=quizIndigoDark] at (5.6, 0.4) {?};
\fill[quizGoldLight, rounded corners=3pt] (0, -\rowH) rectangle (\cols*1.6, 0);
\node[font=\sffamily\bfseries\small, text=quizGoldDark] at (0.8, -0.4) {Label};
\node[font=\sffamily\bfseries\small, text=quizGoldDark] at (2.4, -0.4) {$3$};
\node[font=\sffamily\bfseries\small, text=quizGoldDark] at (4.0, -0.4) {?};
\node[font=\sffamily\bfseries\small, text=quizGoldDark] at (5.6, -0.4) {?};
\draw[quizIndigo!40] (0, -\rowH) grid[xstep=\colW, ystep=\rowH] (\cols*1.6, \rowH);
\end{tikzpicture}
\end{center}
Box Plot
\begin{center}
\begin{tikzpicture}
\draw[quizSlate, thick, <->] (-0.5, 0) -- (10.5, 0);
\foreach \x/\v in {0/50, 2/55, 4/60, 6/65, 8/70, 10/75} {
\draw[quizSlate] (\x, -0.15) -- (\x, 0.15);
\node[below, font=\sffamily\tiny] at (\x, -0.2) {$\v$};
}
\draw[quizIndigo, thick] (1, 0.5) -- (1, 1.3);
\draw[quizIndigo, thick] (1, 0.9) -- (3, 0.9);
\fill[quizIndigoLight] (3, 0.5) rectangle (7, 1.3);
\draw[quizIndigo, thick] (3, 0.5) rectangle (7, 1.3);
\draw[quizGoldDark, very thick] (5, 0.5) -- (5, 1.3);
\draw[quizIndigo, thick] (7, 0.9) -- (9, 0.9);
\draw[quizIndigo, thick] (9, 0.5) -- (9, 1.3);
\end{tikzpicture}
\end{center}
Clue Box (for bonus puzzles)
\begin{center}
\begin{tikzpicture}
\node[fill=quizBonusLight, draw=quizBonusPurple!40, rounded corners=6pt,
text width=10cm, inner sep=8pt, font=\sffamily\small] {
\textcolor{quizBonusPurple}{\faLightbulb}\hspace{2mm}\textbf{Clue 1:} ...\\[2mm]
\textcolor{quizBonusPurple}{\faLightbulb}\hspace{2mm}\textbf{Clue 2:} ...\\[2mm]
\textcolor{quizBonusPurple}{\faLightbulb}\hspace{2mm}\textbf{Clue 3:} ...
};
\end{tikzpicture}
\end{center}
Other TikZ ideas to consider: Dot plots, histograms, 3D prism drawings, nets of solids, double number lines, pie charts, Venn diagrams, tape/bar diagrams, function machines, angle diagrams, transformation grids. Be creative — if a topic calls for a visual you haven't seen here, draw it.
Question Type Catalog
Use at least 3 different types per quiz. This is not exhaustive — invent new types when appropriate.
Visual-to-Symbolic
Student looks at a picture and writes the math.
\quizQ What number do these base-ten blocks show?
\begin{center}
\baseTenBlocks{3}{4}{7}
\end{center}
\quizAnswerLine{The number is}
\answerExplain{$347$}{Count: $3$ hundreds ($300$) + $4$ tens ($40$) + $7$ ones ($7$) $= 347$.}
Multiple Choice
\quizQ What is the area of a triangle with base $10$ cm and height $6$ cm?
\quizMC{$16$ cm$^2$}{$30$ cm$^2$}{$60$ cm$^2$}{$36$ cm$^2$}
\answerExplain{B ($30$ cm$^2$)}{$A = \frac{1}{2} \times b \times h = \frac{1}{2} \times 10 \times 6 = 30$ cm$^2$.
Common mistake: forgetting $\frac{1}{2}$ gives $60$ cm$^2$ (choice C).}
True/False with Visual
\quizQ True or False: Point $B$ is in Quadrant III.
% [coordinate plane TikZ with point B at (-2, 3)]
\quizTF
\answerExplain{False}{Point $B(-2, 3)$ has a negative $x$ and positive $y$,
so it's in Quadrant II, not III. Quadrant III is (negative, negative).}
Comparison
\quizQ Which is the better buy? Circle $>$, $<$, or $=$.
\quizCompare{$6$ muffins for $\$4.50$}{$8$ muffins for $\$5.60$}
\answerExplain{$<$ (left is more expensive per muffin)}{Left: $\$4.50 \div 6 = \$0.75$ each.
Right: $\$5.60 \div 8 = \$0.70$ each. $\$0.75 > \$0.70$, so the right deal is better.}
Fill-in Table
\quizQ Complete the ratio table.
\begin{quizTable}{4}
Red & $2$ & $4$ & \quizBlank[1cm] \\ \hline
Blue & $3$ & \quizBlank[1cm] & $9$ \\
\end{quizTable}
\answerExplain{$6$ and $6$}{The ratio is $2:3$. Multiply both by $2$: $4:6$.
Multiply both by $3$: $6:9$.}
Matching
\quizQ Match each expression to its simplified form.
\begin{quizMatch}
\quizMatchRow{$3(x + 4)$}{$5x + 2$}
\quizMatchRow{$2x + 3x + 2$}{$3x + 12$}
\quizMatchRow{$7x - 2x$}{$5x$}
\end{quizMatch}
\answerExplain{See explanation}{$3(x + 4) = 3x + 12$ (distributive property).
$2x + 3x + 2 = 5x + 2$ (combine like terms). $7x - 2x = 5x$.}
Word Problem with Diagram
\quizQ A recipe uses $3$ cups of flour for every $2$ cups of sugar.
How many cups of sugar do you need with $9$ cups of flour?
% [TikZ ratio table or double number line]
\quizAnswerLine{Cups of sugar}
\answerExplain{$6$}{The ratio is $3:2$. Since $9 \div 3 = 3$, multiply
both parts by $3$: $3 \times 3 = 9$ flour, $2 \times 3 = 6$ sugar.}
Bonus Challenge
Always multi-step, puzzle-like, and encouraging.
\begin{bonusChallenge}
\bonusNote
\quizQ I am thinking of a number. If you multiply it by $3$ and subtract $4$,
you get $17$. What is my number? Show your work.
\quizWorkSpace[2cm]
\answerExplain{$7$}{Work backward: $17 + 4 = 21$, then $21 \div 3 = 7$.
Check: $7 \times 3 - 4 = 21 - 4 = 17$. \checkmark}
\end{bonusChallenge}
What to INCLUDE
\quizPage + \quizInfo + \quizInstructions — every quiz, no exceptions- Visual elements from VMfunMath.sty (always use
quizIndigo color)
- Quiz-specific elements (
\quizMC, \quizCircle, \quizTF, \quizCompare)
- Custom TikZ illustrations — be creative, make them engaging
\answerExplain{answer}{explanation} for every question — with teaching explanationsbonusChallenge with \bonusNote — exactly one per quiz\quizScoreBox at the very end\quizDivider before the bonus section
What to OMIT
These should never appear in quiz topic files:
\begin{practiceBox} — quizzes use \quizQ, not \prob\begin{conceptBox} / \begin{stepsBox} / \begin{vocabBox} — no teaching\begin{workedExample} / \begin{sideBySideExample} — no examples\begin{warmUp} / \begin{exploreBox} / \begin{errorBox} — no activities\begin{riddleBox} / \begin{codeBreaker} / \begin{activityBox} — no games\mascotSays{} / \encouragement{} — use \quizScoreBox instead\begin{summaryBox} / \begin{learningGoals} — no summaries\section{} / \topicTitle{} — quizzes use \quizPage{} instead\prob / \resetProblems — use \quizQ (auto-numbers per quiz)\answer{} / \answerTF{} / \answerMC{} — use \answerExplain{}{} for everything
Enforced Rules
1. \answerExplain{}{} for Every Question — No Exceptions
Every \quizQ must have \answerExplain{short answer}{explanation}. The short answer goes in the Answer Key. The explanation teaches. Do NOT use \answer{}, \answerTF{}, or \answerMC{}.
2. At Least 3 Different Visual Types Per Quiz
A quiz with 6 text-only computation questions is unacceptable. Use the visual toolbox and TikZ patterns. Different visual elements, not the same one repeated.
3. No Teaching Content
Quizzes are assessment only. No concept explanations, worked examples, or tips. The answer explanations do the teaching.
4. Math Always in $...$
\answerExplain{$12$}{...} % ✓ correct
\answerExplain{12}{...} % ✗ wrong
\answerExplain{True}{...} % ✓ (text, not math)
5. Correct Math — Always Verify
Double-check every answer. Incorrect answers destroy student trust. Compute each answer by hand, then verify again. If you're unsure, re-derive from scratch.
6. Exactly 6 Questions + 1 Bonus
Not 5, not 7, not 8. Exactly 6 regular questions and 1 bonus in the bonusChallenge environment. This ensures consistent 2-page layout.
7. Bonus Must Be Encouraging
Always use \bonusNote inside bonusChallenge. Frame as fun extra credit, never as a requirement.
8. Do Not Use \resetProblems or \resetQuiz
Question numbers auto-reset with each \quizPage. Do not manually reset.
9. Strictly 2 Pages
If your quiz is running to page 3, reduce TikZ height, use \quizWorkSpace[1cm], switch to \quizMC or \quizCircle instead of \quizMatch, or shorten the bonus. Never exceed 2 pages.
Real-World Context Guidelines
Use contexts appropriate for the target age:
Good for 11–14 year olds: Shopping deals, phone/data plans, gaming stats, sports records, recipe scaling, travel distances, temperature/weather, allowance/savings, science data (animal speeds, population), school events, music streaming, social media polls.
Avoid: Babyish contexts (counting toys, sharing stickers), overly abstract problems with no context, adult financial topics (mortgages, taxes), controversial topics.
Quiz Color Palette Reference
| Color name | Use for |
|---|
quizIndigo | Primary accent, question badges, visual fills |
quizIndigoLight | Light fills, backgrounds |
quizIndigoDark | Dark text on light backgrounds |
quizGold | Secondary accent |
quizGoldLight | Alternate row fills |
quizGoldDark | Secondary dark text |
quizSlate | Neutral axis lines, borders |
quizSlateLight | Grid lines |
quizBonusPurple | Bonus challenge elements |
quizBonusLight | Bonus background fills |
