SDD 12 - Superpowers: Lab Route
SDD Learning · Previous: Superpowers starter guide · Next: Visual Knowledge Map
Levels 2 to 6 with Superpowers. Agree a short design, watch a test fail for the right reason, make it pass, and verify the final code. Read the Superpowers starter guide first: it explains the tool, and this page applies it to the shared lab.
Walk the Matt Pocock Skills lab route first if you have not: it is the baseline this route 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 | brainstorming | An agreed intent and the bounded classification |
| 3 · Plan | The short design, reviewed in chat | An approach with its tests |
| 4 · Implement | test-driven-development | The change and its tests |
| 5 · Verify | verification-before-completion and your own run | Fresh results from the final code |
| 6 · Review | requesting-code-review | Findings, a decision 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. Install Superpowers for your coding agent as the starter guide describes and begin a fresh session in the lab directory. Confirm that the skills are discoverable.
Record the installed version, the agent and the model in training/WORKSHEET.md.
Level 2 · Specify
Use Superpowers for this existing CLI change. 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. Inspect the code and tests, ask about anything ambiguous, then present the appropriate design for review.
Answer the questions against the existing behavior. Check that the agent classifies the work as a bounded change to an existing flow and keeps the acceptance IDs.
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
A useful short design explains the argument change, the reuse of the current collection logic and the subprocess tests that will prove compatibility. Review it in chat before implementation. A written specification and plan through writing-plans belong to architectural work, which this is not.
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
Ask for test-driven implementation. A useful first test invokes the existing CLI with --format json and expects parseable records; it should fail because the argument is unsupported. The agent then implements enough to satisfy that behavior and checks the unchanged baseline tests. The next tests exercise empty input and escaping.
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 distinguish what it executed from what it inferred. “The tests should pass” is a prediction; a current test result is evidence.
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
Ask for a review of the work against the design and the contract, then rerun the relevant checks after any fix. For this change one implementation session is enough; more agents would add coordination without independent work to schedule. Then have a second participant 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
Why is this change bounded rather than a new architecture? Show one meaningful failure observed before the implementation and the verification result from the final revision.
Superpowers lab route complete. You watched a test fail for the right reason, made it pass and verified the final code.
Compare with your baseline
Put this worksheet beside the one from the Matt Pocock Skills lab route. Which corrections did each route need, which artifacts would you keep, and what would a fresh session find first? The comparison says what to observe. The routes differ in emphasis, and one run is not a ranking.