Explain-back and rubrics

Every course ends with one explain-back in its demonstrate lesson. The learner says in their own words what they built and why, and the runner judges it against a rubric you write. This page covers the prompt, the rubric, the pass mark and what happens when the judge is unavailable or the learner needs another try.

Write the prompt

The prompt sits under ## Explain back in the final lesson (explain-back). Ask about decisions, not definitions. The tutor asks open questions and never leads the learner to the answer. This is the tested lesson:

---
title: Finish and explain
stage: demonstrate
checks: [final-check]
calls:
  - id: choose-check
    ask: Which behaviour will the final check protect?
objectives:
  - id: agent-passes
    text: The agent passes the final check
    by: final-check
  - id: agent-explained
    text: The learner explains the agent
    by: explain-back
---

## Goal

You can show the agent works and say why.

## Explain back

Explain which tool your agent calls and why you chose it.

## Explain back is required once in the final lesson and not allowed in any other (lesson headings).

Write the rubric

The rubric is tutor/<lesson-id>.rubric.md for the final lesson. It is tutor-only, so the learner never sees it verbatim (folder layout). This is the tested rubric:

---
pass: 2 of 3
---
- **Names the output type** and says why a typed result is safer than prose
- **Describes the tool call**: what triggers it and what it returns
- **Names one failure mode** and how the checks would catch it

The rules (rubric grammar):

• The frontmatter key pass is K of N, such as 2 of 3, with positive whole numbers and K at most N.
• Each top-level list item is one criterion. Nested items belong to their parent. Paragraph text is a note to the judge and is not counted.
• N must equal the number of criteria.
• A criterion is met or not met. There is no partial credit or weighting.
• The explain-back passes exactly when at least K criteria are met. One short of K is a fail, however close.

Write each criterion so a judge can decide from what the learner said. Make criteria about the learner’s own decisions, such as “describes the tool call: what triggers it and what it returns”.

Judging needs a capable runner

Judging needs the judge capability. A runner without it records the attempt and leaves the objective unsettled (explain-back). An unavailable judge is not a fail, and it is not a pass. Nothing settles on it.

Only a passing explain-back is recorded as explained evidence. An objective settles only when all three settlement conditions hold:

1. Its evidence passed, and the runner had the capability that evidence needs.
2. Every call in its lesson was the learner’s decision, and the runner can show that it was.
3. The lesson was not skipped.

A call whose provenance is unverified leaves the objective unsettled. A call is verified only on a host whose confirmation boundary was qualified separately. This specification qualifies no host, so on every other host the call stays unverified. Skipping is always allowed and always recorded as skipped, never as passed.

Retries and help

A learner who does not meet the bar gets targeted help and may try again. Help stays spoken. The tutor reveals hints one at a time and never counts help as an attempt (help). Write criteria that stay fair on a second try.

The tutor stays silent on the project

From the moment the prompt is put until the attempt is judged or the learner leaves the step, the tutor must not create, edit, move or delete any project file (silence during explain-back). This includes retries. A learner who wants to change the project leaves the explain-back, returns to build and review, and starts a new explain-back later. Do not write a prompt or a hint that asks the tutor to fix the project while judging it.

Quizzes are practice, not evidence

A ## Quiz is a short list of questions that catches a misconception early. A wrong answer never blocks progress, and a quiz never settles an objective (quizzes). Use a quiz to teach and an explain-back to settle. The overview of evidence kinds shows the difference.

What you can run today

From the checkout root of the agentcourses/agentcourses repository, set up as the quickstart describes, the internal harness checks a course folder, including that its rubric exists for the final lesson and its criteria count equals its pass denominator:

uv run --locked python tools/check_contracts.py --example /path/to/your-course

It does not judge an explain-back. No public validate command is available yet, and judging belongs to a runner that has the judge capability.