The Debugging Discipline

Lesson preview

Before you paste any error into an AI, do four things. First, read what the error literally says — the file, the line number, the error type, the message. Don't skim it; read it. Second, write a one-sentence hypothesis. In writing, even if you're not sure. Third, now consult the AI — but you're checking a hypothesis, not asking an oracle to think for you. ' The gap between what you thought was wrong and what was actually wrong? That gap is your entire curriculum. Here's what each trace teaches you. Trace 1 — TypeError: Cannot read properties of undefined. ok first. ok with a structured error, then validate the success shape with Zod. elements ?? []) — this makes the crash disappear and installs silent error-swallowing in its place. content: Input should be a valid list. Real cause: an assistant tool-use turn was replayed as a bare string. content verbatim; type the history structure so this can't happen silently again. Trace 3 — relation does not exist (works locally, fails in staging). Real cause: the migration was never applied to staging. Real fix: migration lives in the repo; CI checks that migration history matches the target project. Trace 4 — 429 contention across accounts. Covered in depth in the example above. Retrying harder cannot fix contention between requests. slice(0, 50) is added. Real cause: the 'performance cap' silently changed semantics — the model summarised a sample while the report quoted totals. Real fix: compute totals in code over all rows; pass computed aggregates to the model. If context length forces truncation, truncate detail rows — never numbers.

Frequently asked questions

Who is "The Debugging Discipline" for?

This Expert module in AI Delivery Skills & Workflows is for operators, founders and growth teams who run AI in real work and want production-grade judgement. It takes about 10 minutes and ends with a 5-question quiz.

Do I need to code?

Not to follow the lesson. The concepts are explained in plain language; if you build AI systems yourself, the exercise shows where the ideas map onto code.

What comes before and after this module?

Before "The Debugging Discipline", take "Prompt Engineering at Production Quality" (module 6 of AI Delivery Skills & Workflows). It is the last module of AI Delivery Skills & Workflows; continue with another volume in the curriculum.

Related modules

• Previous
  Prompt Engineering at Production Quality

  Prompts as versioned, schema-validated software, not vibes.

• Same topic
  Observability & Tracing

  First in your build order, even though it's fourth on the page — error analysis needs traces to read.

• Same topic
  Debugging AI Workflows

  Find the failing step, build the minimum repro, fix the actual problem.