47. Reproducible debugging

Level: intermediate · Reading time: 8 min · Prerequisite: book/chapters/46-adapted-data-structures.html · Track: supplemental · Maturity: draft · Last review: 2026-05-09

Prerequisites: book/chapters/46-adapted-data-structures.html. See also: book/chapters/46-adapted-data-structures.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Debugging chapters often list tools without showing how a failure becomes reproducible and explainable.

Red Thread (Single Project)

One failure is reduced, reproduced, inspected, and fixed through a small stable scenario.

For what

This chapter helps the reader move from vague bug reports to reproducible technical evidence.

What you are going to do

You will inspect one reproducible failing case, the narrowed contract it breaks, and the fixed version.

Coherent example

space demo/debug

proc normalize_port(raw: int) -> int {
  if raw < 0 { give 0 }
  if raw > 65535 { give 65535 }
  give raw
}

Global explanation

Debugging should be taught as reduction and evidence. The useful move is to isolate a contract, reproduce the failure with the smallest still-meaningful case, and keep the path stable while you inspect it.

Invalid case

proc bad_port(raw: int) -> int {
  if raw { give 0 }
  give raw
}

This invalid case is intentionally small. It exists to isolate the contract failure that the chapter is trying to teach.

Common pitfalls

• Keeping bug reports too large to reason about.
• Changing too many things before reproducing the failure.
• Using tooling pages without a concrete failing story.

Short exercise

Reduce the invalid example to the smallest still-failing shape and write the contract it breaks.

Summary in 5 points

1. Debugging begins with reduction.
2. A stable failing scenario is better than a huge noisy one.
3. The contract matters more than the symptom wording.
4. Reproducibility is a technical asset.
5. Fixes should be explained against the reduced case.