Chapter 56: Debugging AI-Generated Code

James runs the SmartNotes statistics module that Claude Code generated in their last session. Instead of results, the terminal fills with red text: a traceback, a file name, a line number, and a type he has never seen before. He resizes the terminal to read the full message, but it does not help. He has no idea where to start.

"Every programmer hits this wall," Emma says. "AI can generate hundreds of lines of Python in seconds, but it cannot guarantee those lines are correct. When something breaks, you need to find the bug, understand it, and fix it. That is debugging, and no AI tool can do it for you if you do not understand the process."

She is right. Up to this point, everything has worked because the code was small and the types were simple. But SmartNotes is growing. Functions call other functions. Edge cases multiply. The AI makes mistakes that look correct on first read but fail on specific inputs. This chapter teaches you to handle exactly that situation: code that breaks, and the skills to make it work again.

What You Will Learn

By the end of this chapter, you will be able to:

• Read Python tracebacks bottom-up to identify the error type, message, and crash location
• Place strategic print() statements to diagnose logic errors that produce wrong results without crashing
• Recognize the five most common AI failure patterns (off-by-one, wrong operator, missing edge case, incorrect type narrowing, scope error)
• Apply the five-step debugging loop: reproduce, isolate, identify, fix, verify
• Use the Error Taxonomy to classify bugs by category and choose the right debugging tool
• Diagnose and fix five planted bugs in a SmartNotes module as a capstone exercise

Chapter Lessons

Lesson	Title	What You Do	Duration
1	Reading Tracebacks	Read tracebacks bottom-up, identify error types, match to source code	20 min
2	Print Debugging	Place strategic prints, use binary search to narrow suspects, clean up after	20 min
3	Common AI Failure Patterns	Learn five patterns, build a review checklist, spot bugs before running code	20 min
4	The Debugging Loop	Follow the five-step loop: reproduce, isolate, identify, fix, verify	15 min
5	SmartNotes Bug Hunt	Find and fix five bugs (one per Error Taxonomy category) in a capstone exercise	20 min
6	Chapter 56 Quiz	20 scenario-based questions covering all debugging concepts	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 now DEBUGGING code, building on the types, functions, control flow, and data structures you already own.

Stage	What You Do	Claude Code Tool
Predict [AI-FREE]	Predict what error a buggy function will produce, or whether a fix resolves the bug. Press Shift+Tab for Plan Mode.	Plan Mode protects prediction
Run	Press Shift+Tab to exit Plan Mode. Run the code or pytest to see the actual error. Compare to your prediction.	You run it, not Claude Code
Investigate	Read the traceback or print output to understand why the bug occurred. Use /investigate for Socratic questions.	/investigate probes mechanics
Modify	Apply a minimal fix and predict whether it will pass all tests	You edit, Claude Code reviews
Make [Mastery Gate]	Fix a real bug independently using the debugging loop. Use /bug for structured debugging workflows.	Your work, Claude Code guides

Starter Kit

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 chapter.

Prerequisites

Before starting this chapter, you should be able to:

• Write typed Python functions with parameters, return types, and docstrings (Chapter 49)
• Write if/elif/else branches and for/while loops (Chapter 50)
• Define and use dataclasses with typed fields (Chapter 51)
• Write and run pytest tests using uv run pytest (Chapter 46)
• Read AI-generated code and predict what it does (Chapters 43, 45)

The SmartNotes Connection

This chapter debugs a pre-built SmartNotes statistics module. The module contains five functions that Claude Code generated, and each one has a planted bug from a different Error Taxonomy category:

• Bug #1 (Type Error): A function converts a value to the wrong type before doing arithmetic
• Bug #2 (Logic Error): A function uses the wrong comparison operator, producing incorrect results on certain inputs
• Bug #3 (Specification Error): A function implements behavior that does not match the docstring
• Bug #4 (Edge Case Failure): A function crashes when given an empty list
• Bug #5 (Orchestration Error): A function passes arguments to another function in the wrong order

You will start by learning the tools (Lessons 1-4), then apply all of them in the Bug Hunt capstone (Lesson 5).