Writing Quiz Topics

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:

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