SDD 04 - Matt Pocock Skills: Lab Route
SDD Learning · Previous: Matt Pocock Skills starter guide · Next: Spec Kit starter guide
Levels 2 to 6 with Matt Pocock Skills. Use a focused engineering workflow, keep the decisions, and verify the result. Read the Matt Pocock Skills starter guide first: it explains the tool, and this page applies it to the shared lab.
This is the baseline route. Walk it first: it is the default way through the lab, and the run every other track is compared with.
Colors mean the same thing in every diagram of this Learning: see the color key.
The route at a glance
| Level | What you use | What it leaves behind |
|---|---|---|
| 2 · Specify | grill-with-docs, then to-spec | Accepted behavior, vocabulary and exclusions |
| 3 · Plan | A plan for one slice; to-tickets only for several slices | One bounded task mapped to AC1–AC7 |
| 4 · Implement | implement | The change and its tests |
| 5 · Verify | Your own run of the tests and the CLI | Observed results on the final code |
| 6 · Review | code-review | Standards and spec findings, and a handoff |
The contract, the acceptance criteria AC1 to AC7 and the level checks are the same on every route and are described in the lab. Only the steps differ.
Set up once
Download the starter lab, unpack it and run the baseline from a fresh copy of its doc-index-starter directory:
$ python3 -m unittest discover -v $ python3 doc_index.py sample-docs
The four baseline tests pass and the CLI prints two filename/title rows. These skills work on a Git repository: implement commits to the branch you are on, and code-review reviews the diff since a commit you name. Make the lab directory a repository and commit the baseline, so that there is a fixed point to review against:
$ git init $ git add -A $ git commit -m "baseline"
Install the skills as the starter guide describes and confirm which skills the agent can discover. Then run the repository setup once in the lab directory, in agent chat:
/setup-matt-pocock-skills
Setup asks where issues live. Choose local markdown: the lab needs no remote tracker, and specs and tickets are then files under .scratch/ in the lab directory.
Record the installed version, the agent and the model in training/WORKSHEET.md.
Level 2 · Specify
Ask for the clarification workflow. The text after the skill name is an ordinary prompt:
/grill-with-docs Add an optional --format json mode to the existing Markdown indexing CLI. Keep default text output byte-for-byte unchanged (AC1). JSON is an array of objects (AC2) with exactly the string fields file and title, sorted by filename (AC3). An empty directory returns [] (AC4). Unknown formats and missing directories fail with a nonzero exit status, a useful stderr message and empty stdout (AC5). Quotes and non-ASCII characters in titles survive JSON encoding and decoding (AC6). Keep the top-level-only scan and the title fallback (AC7). Use the Python standard library only. Do not add recursion, network access, a database or a web interface. Read the implementation and baseline tests first. Ask about anything ambiguous. Do not edit code yet.
Resolve output fields, ordering, empty input, failure behavior and compatibility. When the decisions are made, record them so they survive the session. Upstream would skip the spec for a change that fits one context window; the lab writes one because level 6 hands the work to a fresh session. With a local tracker to-spec writes the spec as a file under .scratch/:
/to-spec
| Record | Example for this lab |
|---|---|
| Behavior | JSON output is opt-in; default text output stays compatible |
| Vocabulary | A title is derived using the existing parser's behavior |
| Decision | Use the standard library JSON encoder |
| Exclusion | No recursive indexing or new document formats |
These are suggested records, not mandatory upstream filenames. A tiny task does not need an elaborate document hierarchy.
Level 2 check: a partner can explain the promised behavior and the exclusions from the artifact alone.
Level 2 complete. You turned “add JSON” into a contract someone else can check. Good work: this is the step most people skip.
Level 3 · Plan
This change fits one slice, so a ticket breakdown is not needed. Ask for one bounded slice with explicit checks:
Plan the smallest complete change for the accepted JSON-output contract. List the relevant files and compatibility risks. Map acceptance criteria AC1 to AC7 to tests. Include error and empty-input behavior. Stop for review before implementation.
Review the plan for unnecessary dependencies and speculative refactoring. A task called “finish JSON” is too vague if no one can tell how it will be checked.
Complete at least three rows of the worksheet's requirement-to-evidence table, one for compatibility and one for an error case.
Level 3 check: the plan identifies how AC1 will be preserved and checked.
Level 3 complete. Every criterion you care about now points to a task and a check. From here on you build what you have already decided.
Level 4 · Implement
/implement Implement the accepted slice, one behavior at a time, with a failing test before each change. Keep the baseline tests. Do not change unrelated files.
implement drives tdd one red-green slice at a time, runs the full test suite once at the end, runs code-review and commits to the current branch. Inspect the diff for unrelated changes. A spec, task list or generated test file is not evidence that a test ran.
Level 4 check: JSON output works, the original tests still pass, and there are new tests for the feature.
Level 4 complete. The feature exists and the old behavior is still there. Run it once more, just to see your JSON come out.
Level 5 · Verify
Run the commands yourself in the lab directory:
$ python3 -m unittest discover -v $ python3 doc_index.py sample-docs $ python3 doc_index.py sample-docs --format json
The default output should still be the original two tab-separated rows. The JSON should parse to this value; spacing is unimportant:
[{"file":"alpha.md","title":"Alpha"},{"file":"beta.md","title":"beta"}]The new tests should also cover an empty directory, an invalid format, a missing directory and a title containing quotes or non-ASCII text. Record the commands, the results and the revision in the worksheet. The independent checker in the trainer kit can be run against your directory.
Ask the agent to report the exact commands and observed outcomes from the final code, and to list any acceptance criterion that is unverified.
Level 5 check: the evidence is from the final code and every unmet criterion is visible.
Level 5 complete. You can show what ran and what it returned. Enjoy the passing run.
Level 6 · Review
implement already closed with a code-review: read its two sets of findings, repository standards and fidelity to the spec. If you changed anything afterwards, run the review again and name the baseline commit as the fixed point:
/code-review Review the diff since the baseline commit against the accepted spec.
Claude Code has a /code-review of its own that hunts bugs instead; with the plugin installed, this one is mattpocock-skills:code-review.
Then have a second participant open a fresh session with the repository artifacts and answer the handoff questions.
| Handoff question | Evidence to point to |
|---|---|
| What did we agree? | Accepted behavior and exclusions |
| What changed? | The implementation diff and the bounded task |
| How was it checked? | Test command, result and checked revision |
| What remains? | A precise gap or next task |
If the next participant must reconstruct the entire chat to answer these questions, improve the durable record.
Level 6 check: the worksheet states accepted, incomplete or needs revision, says why, and points to what the next session must read.
Level 6 complete. You have walked the whole loop on this route. Take a moment to enjoy that before you go on.
Track checkpoint
Name the one decision from this exercise that a fresh session most needs, and show where it is written down.
Matt Pocock Skills lab route complete. You have walked the loop with skills you chose yourself and left a record that a fresh session can start from.
Next: another track
Your worksheet from this run is the baseline. Start from a fresh copy of the starter lab, keep the agent, model and contract the same, and replay the change on another route: Spec Kit, OpenSpec, BMAD Method or Superpowers. The comparison says what to observe.