writing-quiz-topics

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:

1. Choose at least 3 different visual question types (see Question Type Catalog below)
2. Plan a difficulty progression — start easy, build up, bonus is hardest
3. Plan specific numbers, scenarios, and contexts
4. Do the math first. Compute every answer before writing the question.
5. 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)

1. 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

2. 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.

3. Check explanation matches answer. It's easy to write correct math but a mismatched explanation.

4. Verify visual accuracy. If you drew a TikZ diagram, do the numbers in the diagram match the question and answer?

5. 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.tex
• topics_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):

1. \quizPage{Title} — banner with auto-numbered quiz and chapter
2. \quizInfo — name/date/score strip (defaults to 7 points; use \quizInfo[N] for custom)
3. \quizInstructions — instruction bar (or \quizInstructions[custom text])
4. 6 questions using \quizQ with at least 3 different visual types
5. \quizDivider — separator before bonus
6. bonusChallenge environment with \bonusNote and 1 question
7. \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:

• Names the method or rule used
• Shows intermediate steps
• Includes a check where possible (\checkmark)
• Addresses at least one common mistake ("Common mistake: ...")
• Uses vocabulary from the topic (reinforces learning)

---

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 explanations
• bonusChallenge 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