A practical debugging guide for AI builders

When “just fix it” stops working,here's what to do next.

Code Literacy for AI Builders is a step-by-step guide for people who can build surprisingly capable software with AI—but don't know how to investigate it when something breaks.

Describe the problem. Follow the evidence. Find the relevant code. Then give your AI a repair assignment that doesn't invite more guessing.

Get the Book ✓ No programming background required

Digital ebook • Practical worksheets and prompts included

AI CODING SESSION
AII've updated 7 files to fix the login issue.
YouDon't edit anything else yet. Show me where the failure begins.
auth.ts+12 −4

18− return user;

18+ if (!user.emailVerified) {

19  + throw new AuthError(...)

20}

◎

3 questions to ask:
What caused the failure? What evidence supports that? What else could this affect?

The problem

Stop debugging
by guesswork.

You ask AI to add something. It works on the first try, which feels incredible. A few days later, something unrelated breaks.

You → Paste the error into Claude.

AI → Confidently changes five files.

You → Can you just fix it?

AI → Makes “additional improvements.”

The bug remains. Now you also have twelve changed files and no idea whether the AI fixed a cause, hid a symptom, or created another problem nearby.

The answer isn't a better magic prompt. It's a better investigation.

The method

From vague bug to verified repair.

01

Define the behavior

Write down what should happen, what actually happened, and the exact steps another person could follow.

02

Follow the evidence

Trace the action through the browser and server until you find the first wrong or unknown checkpoint.

03

Narrow the search

Connect that checkpoint to the responsible part of the application and one to three files worth reading.

04

Direct the repair

Give AI a focused brief, review what changed, and repeat the original check before you accept the fix.

The point is not to understand the whole codebase. It is to make the problem small enough that you—and your AI—can reason about it without guessing.

What you'll be able to do

Make the next problem smaller.

Turn “it doesn't work” into a report someone else can reproduce
Separate what you observed from what you merely suspect
Find the first place where the behavior becomes wrong
Use exact clues to locate the files connected to the bug
Explain a relevant block of code in ordinary language
Ask AI to investigate before it starts rewriting things
You may not always find the exact broken line. You will know how to narrow the search, ask for the missing evidence, and stop AI from making broad speculative changes.

One investigation from beginning to end

A reminder is off. The email still arrives.

What Maya sees

GivenMaya has an email reminder scheduled for a task.

WhenShe turns the reminder off.

ExpectNo reminder email is sent.

ActuallyThe page says “Reminders off,” but an email arrives two days later.

What the evidence reveals

BrowserThe correct request was sent.

ServerThe update succeeded and the reminder was saved as inactive.

Later workA background process still selected the reminder for delivery.

Next stepInspect the code that chooses which reminders qualify to send. Don't edit anything else yet.

The book follows this same bug from the first report to the verified repair.

Inside the book

One workflow, built one step at a time.

01

Behavior before code

Use Given, When, Then to decide what the software should do before anyone—or any AI—starts building.

02

Describe the bug

Turn a vague complaint into a report with exact steps, expected behavior, actual behavior, and safe context.

03

Find where the bug begins

Follow the action through browser and server checkpoints until you find the first wrong or unknown result.

04

Meet the parts of an application

Connect the evidence to the job responsible: page, route, service, database, background work, or outside integration.

05

Find the code connected to the bug

Use exact paths, messages, filenames, and function calls to reduce a large project to one to three relevant files.

06

Read the relevant code in plain English

Explain the inputs, decisions, repeated work, outputs, and side effects without pretending to know what the file doesn't show.

07

Turn evidence into a diagnosis

Trace the important value, compare possible explanations, and choose the smallest check that could prove you wrong.

08

Direct and verify the repair

Give AI a constrained brief, review the diff and tests, then repeat the original scenario before accepting the change.

One familiar example runs through the book. You learn the process without having to relearn the product in every chapter.

Built to stay open beside you

Use the book while you debug.

You don't have to read it once and remember everything. The worksheets, checklists, and prompts are designed to come back out the next time something breaks.

  • Given, When, Then behavior worksheet
  • Reproducible bug-report template
  • Browser and server evidence checklist
  • First-wrong-checkpoint worksheet
  • Relevant-file search ladder
  • Plain-English code-reading guide
  • AI investigation and repair prompts
  • Diff review and verification checklist
Jackson Riso

About the author

Jackson Riso

Technology founder, CTO, and AI consultant

  • CTOCertifly
  • Founder & CEORoomRelay
  • FounderSame Day Openings
  • Employee #10Teachable
  • ConsultantTechnology & AI

Why listen to me?

I use AI to write production code every day. I also have to clean up after it.

I'm the CTO of Certifly, the founder and CEO of RoomRelay, and the founder of Same Day Openings. I was employee #10 at Teachable before it was sold for $250 million. I've also spent years helping companies as a technology and AI consultant.

Those aren't credentials I collected to write a book. They're the places where I learned this process. I use AI to write real code for real products every day—and that means I regularly have to debug the code it generates.

AI makes me faster. It also produces confident explanations, broad changes, and fixes that don't quite fix the problem. When that happens, I trace the behavior, follow the evidence through the system, read the relevant code, and make the AI prove its diagnosis before I trust the repair.

This book teaches the same process I use in my own work.

Digital ebook

Code Literacy for AI Builders

A practical field guide for the moment your AI-built software stops behaving and prompting alone isn't getting you anywhere.

  • ✓ Step-by-step debugging workflow
  • ✓ One complete running example
  • ✓ Worksheets and checklists
  • ✓ Copy-and-customize AI prompts

The practical guide

Find the bug.
Follow the evidence.
Fix the right thing.

Written for nontechnical AI builders

Framework and language agnostic

Designed to use beside a real project

Get the Book

No programming background required.

A few reasonable questions

FAQ

Do I need to know how to code?

No. The book begins with behavior and evidence, not syntax. Technical terms appear only when they help answer a real question about the bug.

Is this a programming book?

Not in the traditional sense. You'll look at real code, but you won't be asked to memorize syntax or build an app from scratch. The goal is to investigate the software AI has already helped you build.

Which AI coding tool do I need?

Whichever one you're already using. The ideas work across Claude Code, Codex, Cursor, Replit, Lovable, Bolt, and similar tools.

Do I need my own project?

No. One simple application and one continuing bug carry the explanation. The included worksheets help you apply the same process to your own project later.

Does it only apply to one programming language?

No. Folder names and syntax change, but the investigation does not: define the behavior, follow the evidence, identify the responsible job, and narrow the files worth reading.

Is this useful if I already know how to code?

Probably less so. If you're comfortable tracing bugs, reading diffs, and finding your way around an unfamiliar codebase, you likely know most of the process.

What format is the book?

It is a digital ebook designed to read straight through or keep open as a reference while you investigate a real problem.

The next time something breaks, don't start with another guess.

Start with the behavior. Follow the evidence. Find the relevant code. Then tell your AI exactly what needs to change.

Get the Book

A practical debugging guide for people building software with AI

Get the Book