Chapter 57: TDG Mastery
James stares at a one-sentence problem statement: "SmartNotes needs search." No function name. No parameter list. No docstring. No tests. In every TDG exercise from Chapter 46 onward, Emma provided the specification, handed him the test file, or guided him through the verification stack step by step. Now the scaffolding is gone. He has a problem statement, a text editor, and Claude Code. Everything else is his responsibility.
"This is the whole point of Phase 4," Emma says. "You are not learning new Python. You are not learning new tools. You are learning to drive the TDG cycle yourself, from a blank file to a verified implementation. Every piece you need is already in your hands. The question is whether you can combine them without someone holding the steering wheel."
This chapter removes the training wheels. You will translate a problem statement into a typed function stub, write a complete test suite that defines "correct," prompt AI for an implementation, run the verification stack, debug any failures, and review the generated code critically. By the end, you will have built a real search feature for SmartNotes using nothing but the TDG process you have been practicing since Chapter 46.
What You Will Learn
By the end of this chapter, you will be able to:
- Translate a plain-English problem statement into a Python function stub with typed parameters, return type, and a precise docstring
- Plan and write a complete test suite covering happy path, edge cases, and error paths before any implementation exists
- Execute the generate-verify-debug cycle: prompt AI, run the verification stack (ruff, pyright, pytest), diagnose failures, and iterate
- Evaluate AI-generated code for correctness beyond the test suite by checking for hardcoded values and predicting untested outputs
- Complete the full TDG cycle independently from problem statement to verified implementation
Chapter Lessons
| Lesson | Title | What You Do | Duration |
|---|---|---|---|
| 1 | From Problem Statement to Specification | Translate a one-sentence problem into a typed function stub with a precise docstring | 20 min |
| 2 | Writing the Complete Test Suite | Plan and write tests covering happy path, edge cases, and error paths. All tests fail (RED). | 20 min |
| 3 | Generate, Verify, Debug | Prompt AI, run the verification stack, diagnose failures, and iterate to GREEN | 20 min |
| 4 | SmartNotes Search Capstone | Build the search feature from scratch using the full TDG cycle with no scaffolding | 25 min |
| 5 | Chapter 57 Quiz | 16 scenario-based questions covering specification, testing, verification, and independent TDG | 25 min |
PRIMM-AI+ in This Chapter
Every lesson includes a PRIMM-AI+ Practice section following the five-stage cycle from Chapter 42. This is Phase 4: you are driving the TDG cycle independently, combining specification, testing, generation, verification, and debugging into a single fluid process.
| Stage | What You Do | Claude Code Tool |
|---|---|---|
| Predict [AI-FREE] | Predict what the specification should contain, what tests will fail, or how the AI will implement a function. Press Shift+Tab for Plan Mode. | Plan Mode protects prediction |
| Run | Press Shift+Tab to exit Plan Mode. Run pyright on stubs, pytest on tests, or the full verification stack. Compare results to your prediction. | You run it, not Claude Code |
| Investigate | Read test output or generated code to understand why a prediction was wrong or a test failed. Use /investigate for Socratic questions. | /investigate probes mechanics |
| Modify | Refine a specification, add a missing test, or fix a failing implementation. Predict whether the change resolves the issue. | You edit, Claude Code reviews |
| Make [Mastery Gate] | Execute a full TDG cycle from a new problem statement with no guidance. Use /tdg for structured TDG workflows. | Your work, Claude Code guides |
Your PRIMM-AI+ starter kit from Chapter 42 works throughout Phase 4. Use /predict, /investigate, /bug, /debug, and /tdg commands as you work through each lesson.
Prerequisites
Before starting this chapter, you should be able to:
- Write typed Python functions with parameters, return types, and docstrings (Chapter 49)
- Write and run pytest tests using
uv run pytest(Chapter 46) - Use
@pytest.mark.parametrizeand fixtures (Chapter 52) - Run the verification tools:
uv run ruff check,uv run pyright,uv run pytest(Chapters 52-56) - Read tracebacks bottom-up and apply the debugging loop (Chapter 56)
The SmartNotes Connection
This chapter builds a real search feature for the SmartNotes application you have been developing since Chapter 46. The feature lets users find notes by keyword and optionally filter by tag. You start with nothing but that one-sentence requirement and end with a fully tested, AI-generated implementation.
The four lessons mirror the four stages of a TDG cycle:
- Lesson 1 (Specify): Translate the problem statement into a function stub with types and a precise docstring
- Lesson 2 (Test): Write a complete test suite that defines what "correct" means before any code exists
- Lesson 3 (Generate-Verify-Debug): Prompt AI, run the verification stack, and iterate to GREEN
- Lesson 4 (Capstone): Do it all again, independently, for a second search requirement
The search-feature-spec.md file in this chapter folder contains the expected function signature for students who want to check their work after Lesson 1.