Trace Teacher Guide

Overview

Choose the workflow that matches your access

Both workflows use the same Trace JSON format. Most teachers should create and test a file, then share it through their LMS. Publishing a data set in the Course, Unit, and Trace data set menus requires access to the web server.

Recommended for most teachers

Create a Trace data set with AI

The prompt on this page tells an AI assistant how to convert trusted lesson material, sample code, and standards into the exact JSON structure Trace expects.

1. Gather the standards, lesson notes, algorithms, and code students have already been taught.
2. Go to Generate tracing problems with AI and select Copy prompt.
3. Paste the prompt into your preferred AI assistant.
4. Replace every bracketed course, unit, language, standard, title, grade-level, and problem-count setting.
5. Paste your trusted source material between the source-material markers and submit the prompt.
6. Ask the AI to save its response as a downloadable file named course-unit-topic-trace.json.
7. Download the file without changing .json to another file type.
8. Open and complete every generated trace before assigning it.

Instructional design

How Trace works

Trace highlights one source-code line and asks the student to complete the entire program-state row after that line executes. Students repeat values that remain unchanged and leave a cell blank only when that variable, condition, or output does not yet apply.

The JSON file contains the correct states in instructional order. A step may represent initialization, a condition check, an iteration, a procedure or method return, or final output. The highlighted source line uses a one-based line number even when the programming language uses zero-based indices.

• Java: arrays and strings normally begin at index 0.
• AP CSP pseudocode: lists begin at index 1.
• Other languages: follow that language’s actual evaluation, scope, indexing, and output rules.

Before assigning

Test a downloaded data set

1. Open Trace through the website or a local web server.
2. Enter a test learner identity.
3. Under Or open a trace data set, select the downloaded JSON file.
4. Confirm its title, course, unit, language, standards, code, and indexed memory display.
5. Complete every row of every problem using the expected values.
6. Intentionally enter one wrong value and confirm that the feedback identifies the correct column without revealing unrelated answers.
7. Complete the problem and verify that the PNG contains the correct identity, completion ID, timestamps, problem information, and trace table.
8. Correct the source file and retest whenever any answer, code line, column, or step changes.

Canvas or another LMS

Share a manually uploaded data set

1. Attach the tested .json file to the assignment.
2. Link students to https://johnmcgarvey.com/trace/.
3. Tell students which problem or problems to complete.
4. Ask students to submit the completion PNG produced by Trace.

Student file-opening directions

1. Download the JSON file from the LMS. Do not open it in Google Docs.
2. Open Trace and enter your own name and school email before beginning.
3. Select Or open a trace data set and choose the downloaded file.
4. Complete the assigned trace, download the PNG once, and upload that PNG to the assignment.

Suggested routine

Directions for students

1. Use your own identity. Your name and email lock when you check the first step.
2. Read the highlighted line. Execute only what that line requires in the current state.
3. Complete the whole row. Repeat unchanged values; leave cells blank only when they do not yet apply.
4. Use feedback to correct your reasoning. Do not guess rapidly. Return to the code and identify the operation that changes the state.
5. Finish the assigned problem once. Trace is not a repeated-session assignment.
6. Download the PNG immediately. One completion image is generated for the locked identity.

Completion evidence

What the PNG records

The completion image includes the learner’s locked name and email, start and completion times, a unique completion ID, course, unit, data set, problem, standard, number of step checks and corrections, and the completed correct trace table.

Identity is entered before tracing and cannot be edited after the first check. The app permits one PNG generation for that completion. This discourages one completed trace from being relabeled for several students.

Local data

Privacy and browser storage

Trace does not send learner identity, progress, or answers to a server. The profile and progress remain in local browser storage. The PNG is created on the device and leaves the browser only when the student submits or shares it.

• Clearing browser data removes the locally saved profile and progress.
• Using a different browser or device creates a separate local record.
• Opening a teacher-authored JSON file loads code and answers but does not upload student information.
• Do not place student names, private information, passwords, or answer keys from secure assessments inside a publicly shared JSON file.

AI-assisted authoring

Generate tracing problems with AI

Replace the bracketed settings, paste trusted source material at the bottom, and submit the entire prompt. Review every generated state transition before using the file with students.

You are creating a JSON algorithm-tracing data set for the Trace website.

COURSE: [ENTER COURSE NAME]
UNIT: [ENTER UNIT, TOPIC, OR SKILL]
STANDARDS: [ENTER THE STANDARDS THAT MAY BE ASSESSED]
DATA SET TITLE: [ENTER STUDENT-FACING TITLE]
TARGET GRADE OR COURSE LEVEL: [ENTER LEVEL]
APPROXIMATE NUMBER OF PROBLEMS: [ENTER NUMBER, USUALLY 2-10]
PROGRAMMING LANGUAGE OR NOTATION: [JAVA, AP CSP PSEUDOCODE, OR ANOTHER LANGUAGE]
CODE SCOPE: [SHORT SEGMENTS, COMPLETE METHODS/PROCEDURES, COMPLETE PROGRAMS, OR MIXED]

TASK
Convert only the supplied source material into original, guided algorithm-tracing problems. Students will see source code on the left and complete a program-state table one highlighted step at a time.

CONTENT RULES
1. Use only syntax, concepts, algorithms, and standards supported by the supplied source material.
2. Do not copy secure assessment questions. Create original values, names, scenarios, and code.
3. Begin with the simplest state change appropriate to the source and increase difficulty gradually.
4. Give every problem one clear tracing goal and enough initialized context to determine every answer.
5. Follow the selected language exactly. Preserve capitalization, operators, punctuation, braces, indentation, scope, evaluation order, and output behavior.
6. For AP CSP pseudocode, use College Board-style textual notation such as ←, DISPLAY, IF, ELSE, REPEAT, REPEAT UNTIL, FOR EACH, PROCEDURE, RETURN, and MOD.
7. AP CSP list indices begin at 1. Java array and String indices begin at 0.
8. Keep code lines short enough to display clearly. Put indentation spaces inside the code string.
9. Add a specific standard to every problem.
10. Use short table columns that represent relevant variables, parameters, conditions, collection elements, return values, or output.
11. Every trace row represents the complete state after the highlighted line executes. Repeat values that remain unchanged.
12. Use the em dash character — when a column does not yet apply. Students may leave that cell blank.
13. Include enough steps to reveal the important state transitions without adding redundant rows.
14. A repeated source line may appear in several steps when it executes during several iterations.
15. Give every step a concise label and an explanation of why its state is correct.
16. Avoid ambiguous input, nondeterministic behavior, implementation-dependent results, and multiple valid traces.
17. Use an optional memory object only when an indexed string, list, array, or similar structure will help students.

JSON RULES
1. Create a unique data-set id using lowercase letters, numbers, and hyphens, ending in -v1.
2. Create a unique descriptive id for every problem.
3. The code array contains source lines in display order.
4. Each step line is a one-based source-line number and must be between 1 and the number of code lines.
5. Each step values array must contain exactly one string for every column, in matching order.
6. Store trace answers as strings, including numbers and Boolean values.
7. Do not include trailing commas.

OUTPUT RULES
1. Return one valid JSON object and nothing else.
2. Do not use Markdown fences or commentary.
3. Use exactly this structure:

{
  "id": "course-unit-trace-v1",
  "title": "Student-Facing Trace Set Title",
  "course": "Course Name",
  "unit": "Unit Name",
  "language": "Programming Language or Notation",
  "description": "One-sentence description.",
  "problems": [
    {
      "id": "descriptive-problem-id",
      "title": "Student-facing problem title",
      "standard": "Specific standard assessed",
      "prompt": "Tell the student what to trace and record.",
      "goal": "Short explanation of the tracing target.",
      "tags": ["Topic", "Skill"],
      "code": [
        "first code line",
        "    indented code line"
      ],
      "memory": {
        "type": "list, array, or string",
        "name": "structureName",
        "indexBase": 0,
        "values": ["value1", "value2"]
      },
      "columns": ["variable", "condition", "output"],
      "steps": [
        {
          "line": 1,
          "label": "Initialization",
          "values": ["0", "—", "—"],
          "explanation": "Explain the state after this line."
        }
      ]
    }
  ]
}

Omit the memory property when the problem does not use an indexed structure.

FINAL QUALITY CHECK
- Confirm that the JSON parses.
- Confirm that every required field is present.
- Confirm that every ID is unique.
- Confirm that every step line points to a real code line.
- Confirm that every values array has exactly the same length as columns.
- Manually execute every line and confirm every state, condition, index, return value, and output.
- Confirm that all claims and syntax are supported by the source material.
- Confirm that the response contains JSON only.

SOURCE MATERIAL BEGINS BELOW
--------------------------------------------------
[PASTE STANDARDS, LESSON NOTES, ALGORITHM DESCRIPTIONS, AND SAMPLE CODE HERE]
--------------------------------------------------
SOURCE MATERIAL ENDS HERE