SDD 15 - Trainer Guide

category: learnz/sdd · date: 2026-10-04 · author: LALA · theme: github

SDD Learning · Previous: Framework Comparison

The learning objective is traceability from intent to evidence. Participants should finish able to explain a requirement, identify its implementation and demonstrate a relevant check. Finishing the feature is useful; understanding why it is accepted is the central outcome.

No clock

The path has six levels and no schedule. Let each learner or pair move on when they pass the level check. People learn this loop at very different speeds, and a learner who is rushed through a level learns to skip it. If the group meets for a fixed session, treat “how far did we get” as information, never as a score: a pair that finished level 3 with a contract they can defend has had a good session.

When a pair passes a level check, say so out loud before they go on.

Prepare before the session

Rehearse the baseline route with the exact agent, model, skills release and integration the group will use. Rehearse any other lab route you plan to offer the same way.
Complete installations and model access beforehand, so nobody spends their first level fighting a setup. Pair participants when one working agent session is available for two learners.
Give everyone the same starter lab. Confirm the four baseline tests pass.
Open the SDD Learning, foundations and lab.
Download the trainer kit and diagram pack.
Keep the reference solution for the debrief or a recovery demonstration. It is deliberately separate from the participant baseline.

The trainer kit contains a black-box acceptance checker, a small reference implementation and facilitation notes. Both programs use the Python standard library. The reference illustrates the feature; it does not prescribe the only acceptable design.

The levels

The six levels as a route: understand, specify, plan, implement, verify, review.

Level	Facilitate	Watch for	Passed when
1 · Understand	Explain request, contract, plan and evidence using the contract diagram	Participants calling a technical preference a requirement	They can say what each of the four proves
2 · Specify	Let pairs inspect the baseline and review the contract	Silent changes to compatibility, ordering or error behavior	A partner predicts the output from the contract alone
3 · Plan	Review requirement-to-task-to-test mappings	Tasks that omit tests or only cover the happy path	AC1 has a task and a check
4 · Implement	Let participants implement one bounded change	Unrelated rewrites, missing regression tests and guessed completion	JSON works and the old tests still pass
5 · Verify	Ask participants to run checks on their final revision	Old results, unexecuted commands and unchecked edge cases	The evidence is from the final code
6 · Review	Pair review and a short handoff	“Done” without a requirement/evidence explanation	Someone else could continue from the handoff

Read the colors with the group

Color key: cyan intent, blue contract, purple plan, pink change, green evidence, amber review, red problem, gray context, white method.

One color means one thing in every diagram, and the first six colors are the six levels in order. Show the key once at the start; afterwards the group can read any diagram in the Learning without a new explanation. Frameworks are white in every diagram so that color never suggests a ranking.

Use the diagrams as prompts

Diagram	Ask the group
Learning route	What concrete artifact should exist before the next level?
Contract example	What is still ambiguous in “add JSON”?
Feedback loop	Is this failure in the code or in the agreed requirement?
Matt Pocock Skills memory	Where does this decision live after the session?
Spec Kit artifacts	Which document owns this decision?
OpenSpec delta	Which behavior is added and which is preserved?
Test feedback	Have we observed a relevant failure and checked the final code?
Memory	What will a fresh session need to retrieve?

Observable completion criteria

Criterion	Satisfactory evidence	If missing
Contract	Behavior, exclusions and concrete scenarios are reviewable	Revisit the requirement before discussing implementation style
Traceability	At least three acceptance IDs map to tasks and executable checks	Ask the learner to complete the mapping
Compatibility	Default output remains identical and is tested	Treat this as an acceptance criterion that is still open
Verification	Current results cover the promised behavior and record gaps	Mark the work incomplete
Handoff	The next session can find the accepted spec and remaining work	Add the missing pointers and decision record

Avoid a single numerical score that hides a broken compatibility requirement. A learner can demonstrate good reasoning while the feature remains incomplete; record those outcomes separately, and praise the reasoning.

Run the independent acceptance checker

Unpack the trainer kit. From its trainer directory, pass the participant's project path:

bash

$ python3 check_acceptance.py /path/to/doc-index-starter

The checker invokes doc_index.py in subprocesses with temporary synthetic documents. It checks the training contract, including baseline text behavior, JSON structure, empty input, errors, escaping, top-level discovery and fallback. It does not write to the participant's project.

To see a passing example, run it against the included reference:

bash

$ python3 check_acceptance.py reference-solution

The reference passes 8 of 8 checks. The untouched baseline passes 3 of 8 because the feature is deliberately absent. Explain that a failed acceptance check is useful evidence, not a reason to hide or rewrite the criterion.

Common interventions

Situation	Intervention
Installation is still not working	Use a prepared machine or pair with a working session, so the learner's attention stays on the levels
The agent starts coding before agreement	Ask the learner to identify the accepted contract and unresolved choices
The plan is much larger than the feature	Remove tasks unrelated to the stated acceptance criteria
Tests only assert successful exit	Ask what wrong output could still pass
The agent changes the tests to fit a regression	Compare the changed expectation with the accepted contract
Model access fails	Run a facilitator demonstration with the same artifacts, or inspect the reference after a manual planning attempt
A learner is stuck on a level	Go back one level together; the gap is usually there
A learner feels behind	Remind them there is no clock, and point at the levels they have already passed

Debrief questions

Which ambiguity would have caused the most rework if it had stayed unresolved?
What did the specification help you decide, and what still required engineering judgment?
Which passing test was most informative? What does it leave unchecked?
Where would you store the next change to this contract?
What would you keep if you changed frameworks tomorrow?
Which level felt best to finish, and why?

Framework tracks

Everyone walks the Matt Pocock Skills lab route first; it is the baseline. Afterwards let each pair choose the route they are curious about: Spec Kit, OpenSpec, BMAD Method or Superpowers. All routes have the same levels, contract and checks. Start each run from a fresh copy of the starter lab. Record the versions and any changed agent or model settings. Compare handoff quality, corrections, verification and artifact maintenance; one training run is not a performance benchmark.

Use the framework selector and comparison article to discuss fit. Use the knowledge map to connect the different routes back to one engineering loop.