Writing Steps Topics

Step 0 — Discover Topics with the Script

Before writing anything, run the discovery script to learn what topics the chapter contains, the grade level, and the target audience:

python3 scripts/get_chapter_topic_facts.py --chapter <N>

The script output tells you:

• Grade Info — grade level, grade display name, and target student age range (read from scripts/config.py and .env). Use this to calibrate vocabulary, sentence complexity, and number difficulty.
• Chapter title — so you know the mathematical domain.
• Core topics — the list of topics in topics/ you must write step-by-step versions for.
• Additional topics — state-specific topics in topics_additional/ (with which states use them).
• Modified topics — state-specific variants in topics_modified/ (with which states use them).
• Summaries — a brief content description for each topic, giving you a head start on understanding the math before you read the source file.

To list all available chapters:

python3 scripts/get_chapter_topic_facts.py --list-chapters

Use the script output to plan your work: note how many files you need to create (core + additional + modified) and read the summaries to understand the scope.

Step 1 — Read the Study Guide Source Topics

For every topic listed by the script, read the corresponding Study Guide source file before writing:

When reading each source file, extract:

• What concepts are taught
• What vocabulary is introduced
• What difficulty level and number range is used
• What types of problems appear in the practice section

The step-by-step file must use the same filename as the Study Guide file.

Step 2 — Write High-Quality Step-by-Step Topics

Write each topic following the Topic Structure and Content Guidelines below. Focus on:

• Mathematical accuracy — double-check every calculation in examples and answers.
• Clear procedural steps — the stepsCard is the centerpiece. Steps must be concise, unambiguous, and cover the full procedure.
• Age-appropriate language — use the grade/age info from the script output (see "Writing for the Target Audience" below).
• Variety in examples — don't reuse the same numbers or problem types across examples. Use realistic contexts (money, sports, cooking, school supplies).
• Correct LaTeX — follow the LaTeX Conventions section exactly.

Step 3 — Compile and Verify

After writing ALL topics for the chapter (core + additional + modified):

1. Create a test file tests/test_steps_ch<N>.tex that includes all the new topic files.
2. Compile with: latexmk -xelatex -output-directory=build -interaction=nonstopmode -f tests/test_steps_ch<N>.tex
3. Check the log for errors: grep -i 'error\|undefined' build/test_steps_ch<N>.log | grep -v Warning | head -20
4. Open the PDF for review.

File Location & Naming

Place topic files in:

• Core topics: steps_topics/
• State-specific additional: steps_topics_additional/
• State-specific modified: steps_topics_modified/

Naming: Same filenames as the Study Guide source files — ch<CC>-<SS>-<slug>.tex

Examples: ch01-01-what-is-a-ratio.tex, ch02-03-divide-multi-digit-numbers.tex

Key Differences from the Study Guide

Topic Structure (2–3 pages)

Every step-by-step topic follows this flow:

Required Elements

1. Section header — \section{} only (do NOT use \stepByStepTitle{})
2. Step Goal — brief learning objectives in stepGoal (2–3 items)
3. Vocabulary — key terms grouped in stepVocabBox with \vocabItem entries (2–4 terms)
4. Steps Card — ALL steps listed concisely in stepsCard with \stepItem, with a clear descriptive title
5. Worked Examples — 1–2 examples using stepExample with \stepShow and \stepResult
6. Practice — 5–6 problems organized by step in stepPractice

Optional Elements (use at most 1 per topic to save space)

• \watchOut{} for a common mistake
• \mascotStepTip{} for an owl character tip
• stepTryIt for guided practice with blanks (only if space allows — skip if topic already has 2 examples)

Elements to OMIT

These should NOT appear in step-by-step topics:

• \encouragement{} — no motivational closers
• challengeBox — no bonus challenges
• \stepReminder{} — use sparingly, prefer cutting to save space
• conceptBox — use stepsCard instead
• vocabBox — use stepVocabBox instead
• exploreBox, errorBox, riddleBox, activityBox, warmUp — none of these
• realWorld, funFact, didYouKnow, storyProblem — none of these
• summaryBox — no summaries
• compareBox, patternBox, codeBreaker, mathTrail — none of these

Section Guide

Section Header (required)

\section{Place Value Relationships}

Do NOT use \stepByStepTitle{} — it duplicates the section title and adds an unnecessary "Step-by-Step Guide" subtitle. The \section{} command already renders the numbered title (e.g., "1.1 Place Value Relationships").

Step Goal (required)

\begin{stepGoal}
\begin{itemize}
    \item Explain how each digit's value is $10$ times the digit to its right
    \item Read the value of a digit based on its place
\end{itemize}
\end{stepGoal}

Brief — just 2–3 bullet points. Keep it tighter than the study guide's learningGoals.

Vocabulary (before stepsCard)

Group all vocabulary in a single titled box using stepVocabBox:

\begin{stepVocabBox}
    \vocabItem{Place Value}{How much a digit is worth based on where it sits in a number.}
    \vocabItem{Expanded Form}{Writing a number as the sum of each digit's value.}
\end{stepVocabBox}

The box has a default title "Words to Know". You can customize it: \begin{stepVocabBox}[New Words].

Keep to 2–4 terms — only essential vocabulary for the procedure.

Steps Card (required — the centerpiece)

\begin{stepsCard}[How to Find the Value of Each Digit in a Number]
    \stepItem{Find the digit's \textbf{place} — ones, tens, hundreds, thousands, etc.}
    \stepItem{Each place is \textbf{$10$ times} the place to its right and \textbf{$\frac{1}{10}$} of the place to its left.}
    \stepItem{Multiply the digit by its \textbf{place value} to find what it's worth.}
\end{stepsCard}

Rules for the stepsCard:

• Always provide a clear descriptive title that tells the student what they are learning to do (e.g., [How to Multiply Multi-Digit Numbers], [How to Compare Two Decimals]). The default title "The Steps" is too vague — students must know what the steps are for.
• 2–5 steps maximum
• Each step is ONE concise sentence
• Steps auto-number with colored circles (step1Color, step2Color, etc.)
• This is shown ONCE — then examples demonstrate how to apply all steps

Worked Examples (required, 1–2 per topic)

\begin{stepExample}{In $3{,}555$, how does the value of the $5$ in the hundreds place compare to the $5$ in the tens place?}
    \stepShow{1} Find each digit's place:\\
    The first $5$ is in the \textbf{hundreds} place. The second $5$ is in the \textbf{tens} place.

    \stepShow{2} Hundreds is one place to the left of tens, so it is $10$ times greater.

    \stepShow{3} Find the values: $5 \times 100 = 500$ and $5 \times 10 = 50$.
    \stepResult{The $5$ in the hundreds place is $10$ times the $5$ in the tens place ($500$ vs.\ $50$).}
\end{stepExample}

Each worked example applies ALL steps to ONE problem:

• Use \stepShow{n} to label which step is being applied (colored badge)
• Use \stepResult{answer} for the final answer (green checkmark box)
• Keep each step's application brief — 1–2 lines
• If you do 2 examples, the second should be more concise

Your Turn (optional — only if space allows)

\begin{stepTryIt}{In $4{,}442$, compare the value of the $4$ in the thousands place to the $4$ in the hundreds place.}
    \stepShow{1} What place is each $4$ in?\par
    Thousands $4$: \answerBlank[2.5cm] \qquad Hundreds $4$: \answerBlank[2.5cm]

    \stepShow{2} Which place is to the left? It is \answerBlank[1.5cm] times greater.\par

    \stepShow{3} Values: $4 \times$ \answerBlank[1.5cm] $=$ \answerBlank[2cm] and $4 \times$ \answerBlank[1.5cm] $=$ \answerBlank[2cm]
\end{stepTryIt}

Same structure as stepExample but with blanks. Skip this if the topic already has 2 examples — it's better to stay within 2–3 pages than to include everything.

Watch Out / Tips (optional, at most 1)

\watchOut{The same digit can mean very different things! The $7$ in $7{,}000$ is worth $7{,}000$, but the $7$ in $70$ is only worth $70$.}

Or:

\mascotStepTip{Move one place to the LEFT and the value gets $10$ times bigger. Move RIGHT and it gets $10$ times smaller!}

Pick ONE — not both. Many topics won't need either.

Step Practice (required)

\newpage
\begin{stepPractice}{Place Value Practice}
    \resetProblems

    \stepPracticeHeader[step1Color]{Identify the Place}
    \begin{multicols}{2}
    \prob What place is the $6$ in $6{,}432$? \answerBlank[2.5cm]
    \answer{thousands}
    \prob What place is the $8$ in $3.482$? \answerBlank[2.5cm]
    \answer{hundredths}
    \end{multicols}

    \stepPracticeHeader[step2Color]{Compare Digit Values}
    \prob In $2{,}255$, the $2$ in the thousands place is how many times the $2$ in the hundreds place? \answerBlank[2cm]
    \answer{$10$ times}

    \stepPracticeHeader[step3Color]{Find the Value}
    \begin{multicols}{2}
    \prob Value of $9$ in $9{,}301$: \answerBlank[2cm]
    \answer{$9{,}000$}
    \prob Value of $4$ in $0.743$: \answerBlank[2cm]
    \answer{$0.003$}
    \end{multicols}

    \wordProblem{Mia says the $5$ in $5{,}500$ and the $5$ in $550$ are worth the same. Is she right? Explain.}{~}
    \answer{No. In $5{,}500$ the first $5$ is worth $5{,}000$; in $550$ the first $5$ is worth $500$. They are $10$ times different.}
\end{stepPractice}

Keep practice short — aim for 5–6 problems total. Use \stepPracticeHeader[stepNColor] to organize by step. Include 1–2 problems per step category plus 1 word problem.

Full Template

% ============================================================================
% Section X.Y — Topic Title
% CCSS 5.XXX.X.X
% ============================================================================
\section{Topic Title}

\begin{stepGoal}
\begin{itemize}
    \item Goal 1 (keep to 2–3 goals)
    \item Goal 2
\end{itemize}
\end{stepGoal}

\begin{stepVocabBox}
    \vocabItem{Term 1}{Brief definition.}
    \vocabItem{Term 2}{Brief definition.}
\end{stepVocabBox}

\begin{stepsCard}[How to Do the Main Skill]
    \stepItem{Step 1 — one clear sentence.}
    \stepItem{Step 2 — one clear sentence.}
    \stepItem{Step 3 — one clear sentence.}
\end{stepsCard}

% --- 1–2 Worked Examples ---
\begin{stepExample}{Example problem statement.}
    \stepShow{1} Apply step 1...
    \stepShow{2} Apply step 2...
    \stepShow{3} Apply step 3...
    \stepResult{Final answer}
\end{stepExample}

% --- Optional: 1 tip or warning ---
\mascotStepTip{One helpful tip.}

% ============================================================================
% PRACTICE (4–5 problems)
% ============================================================================
\newpage
\begin{stepPractice}{Topic Practice}
    \resetProblems

    \stepPracticeHeader[step1Color]{Category 1}
    \prob Problem \answerBlank[2cm]
    \answer{answer}

    \stepPracticeHeader[step2Color]{Category 2}
    \begin{multicols}{2}
    \prob Problem \answerBlank[2cm]
    \answer{answer}
    \prob Problem \answerBlank[2cm]
    \answer{answer}
    \end{multicols}

    \stepPracticeHeader[step3Color]{Put It All Together}
    \prob Problem \answerBlank[2cm]
    \answer{answer}

    \wordProblem{Word problem text.}{unit}
    \answer{answer}
\end{stepPractice}

Content Guidelines

Keep It Brief — Target 2–3 Pages

The step-by-step book must match the study guide's page count (~130 pages). Every element must justify its space:

If a topic runs to 3 pages, another should be 2 pages to compensate.

Steps First, Examples Second

Never interleave step explanations with examples. The flow is always:

1. stepsCard — all steps listed
2. stepExample × 1–2 — worked examples applying all steps
3. Optional: stepTryIt (only if space allows)
4. stepPractice — independent practice

Same Concepts, Procedural Approach

Step-by-step topics cover the same math content as the Study Guide but present it as a procedure-first lesson:

Writing for the Target Audience

The script output includes the grade level and target student age range. Adapt your writing accordingly:

• SHORT sentences — one idea per sentence.
• Everyday words — "split", "share", "groups", "flip", "same as", "left over".
• Address the student — "you", "your".
• Use relatable contexts — school supplies, sports scores, recipes, sharing snacks, pocket money.
• Match the math level to the grade — use number ranges, operation types, and concept depth appropriate for the grade shown in the script output.

TikZ Diagrams & Visual Aids

In some cases we might need to include a TikZ diagrams, shapes, or graphs to illustrate concepts (especially for geometry, coordinate plane, measurement, and circle topics).

Page Budget

Target ~130 pages total for 44 core topics + initial pages + answer key:

• 44 topics × ~2.5 pages = ~110 pages
• Initial pages = ~4 pages
• Chapter openers (7) = ~7 pages
• Answer key = ~6 pages
• Running total = ~127 pages (leaves room for state additional topics)

This means each topic should average 2–3 pages. If a topic runs to 3 pages, keep another at 2.

Available Environments (VMfunSteps.sty)

LaTeX Conventions

• Use $...$ for ALL math
• Use \textbf{...} to bold key terms on first use
• Use \times for multiplication, \div for division
• Every practice problem needs an answer: \answer{}, \answerTF{}, or \answerMC{}
• Do NOT use \answerExplain{}{} — explanations add too much volume. Use \answer{} instead to keep the book compact.
• Put \newpage before stepPractice

Checklist

• Ran python3 scripts/get_chapter_topic_facts.py --chapter <N> to discover topics, grade, and audience
• Read every Study Guide source file listed by the script
• File placed in correct steps folder, filename matches the Study Guide source file
• \section{} present (NO \stepByStepTitle{})
• stepGoal with 2–3 brief learning objectives
• stepVocabBox with 2–4 key terms
• stepsCard with clear descriptive title and 2–5 concise \stepItem entries
• 1–2 stepExample environments, each applying ALL steps
• stepPractice with 5–6 problems organized by step
• Every problem has an answer (use \answer{}, NOT \answerExplain{}{})
• All answers are mathematically correct
• NO \encouragement{}, challengeBox, summaryBox, or other extras
• At most 1 \mascotStepTip{} or \watchOut{} (not both)
• TikZ diagrams/shapes/graphs included when needed.
• Topic is 2–3 pages total
• Compile a test file in tests/ folder and open for my review and feedback