Approving instructions — the approval gate

When you open the Instructions tab on Review & Edit, a yellow banner sits above the Instructions.md document. Until you click Approve instructions, the autograder check is locked.

This article explains why the gate exists and what to actually check during your review.

Why the gate exists

Instructions.md shapes the student experience more than any other artifact. Starter and solution code can be tested mechanically (does it pass?), but whether the instructions are pitched at the right level for your students is something only you can judge.

Earlier versions of CodeTeach skipped this gate — generation flowed straight into the autograder check. We added it after instructors reported the same problem multiple times: the AI would produce technically-correct instructions that were way too sparse for the difficulty, students would get stuck, and the instructor would discover this only after deploying.

The gate forces a pause. Read the doc, confirm the level fits, then proceed. It's also a useful checkpoint for catching small issues (typos, wrong example outputs, vocabulary mismatches) before they ship.

What to actually check — four things

1. Difficulty fit (the main thing)

Does the level of code shown in the document match the Difficulty you picked?

• Beginner — Implementation Steps should show complete code for each TODO. Complete Program section should show the entire solution as one runnable block. If it doesn't, the AI under-shot.
• Intermediate — Implementation Steps should show partial snippets and pseudocode. No complete solutions inline. If it does, the AI over-shot (and your students get a give-away).
• Advanced — Implementation Steps should show no code, only requirements. If you see code samples, the AI over-shot.

If the level is wrong, click Regenerate at the top of the Instructions tab. It re-runs only the Instructions.md generation at your selected Difficulty.

If you're unsure what each level looks like, Choosing a difficulty level has side-by-side examples.

2. Examples that match the starter

The AI sometimes invents example outputs that don't match what the starter actually produces. Concrete case: if your starter prints Good Morning! / Good Afternoon! / Good Evening! based on the system clock, an AI example showing input: 9 → output: Good Morning! is wrong — the starter doesn't take input, it reads the clock.

If you see suspicious examples, edit them by hand or run validation — the autograder check catches test/output mismatches and bounces the assignment back.

3. Vocabulary and tone

Does it match how you'd actually talk to your students?

• Beginner course — short sentences, define terms inline, encouraging tone
• Advanced course — assume the reader knows the standard library; terse is fine

If the tone is off, edit directly in the Instructions tab's Edit view. The Markdown is fully editable.

4. Section completeness

Standard Instructions.md has these sections in order:

1. Title (#)
2. Overview
3. Learning Objectives
4. Getting Started
5. Implementation Steps (one subsection per TODO)
6. Complete Program
7. Testing
8. Grading Rubric
9. Tips and Hints

If any are missing or feel skimpy, edit by hand — or click Regenerate to start over.

What clicking Approve actually does

When you click Approve instructions:

• The yellow banner turns green: "Instructions approved for [level]"
• A new Run autograder check button appears on the Review screen, above the tabs
• The session's instructionsApproved flag flips to true in the database
• Status stays generated until you actually click Run autograder check

Approval is a one-time gate for the lifetime of an assignment. If you later edit Instructions.md, the approval stays — you don't have to re-approve. (We trust that an edit is also an implicit re-approval.)

What if I disagree with the gate? Can I just click Approve and skip the review?

You can. The gate is procedural — it doesn't actually verify you read anything. If you've reviewed the instructions in 30 seconds and they look fine, click Approve and move on.

That said: it's worth doing the actual review, especially the difficulty-fit check in section 1 above. The most common student frustration in CodeTeach assignments is "the instructions don't tell me enough" or "the instructions tell me too much" — both of which the difficulty-fit check is designed to catch.

What if Instructions.md needs significant work?

Three options:

• Edit by hand — directly in the Edit view of the Instructions tab. Markdown editor with a Preview toggle to see rendered output.
• Regenerate — re-runs only Instructions.md at the current Difficulty. Costs one credit.
• Change Difficulty and regenerate — go back to the wizard form (click Seed in the progress bar), update Difficulty, then return to Instructions and click Regenerate. The new Instructions.md will reflect the new level.

After significant edits, no need to re-validate (Instructions.md doesn't affect the autograder). But re-read your edits one more time before final approval.

Where to go next

• Approved and ready to run the autograder? → The autograder check explains what runs during validation.
• Realised the difficulty is wrong? → Click Seed in the progress bar, change Difficulty, come back, click Regenerate on this tab.
• Validation just failed? → When validation fails.