Incident Ladder¶

Reference Position¶

flowchart TD
  family["Reproducible Research"] --> program["Deep Dive Make"]
  program --> reference["Incident Ladder"]
  reference --> review["Design or review decision"]
  review --> capstone["Capstone proof surface"]

flowchart TD
  trigger["Hit a naming, boundary, or trade-off question"] --> lookup["Use this page as a glossary, map, rubric, or atlas"]
  lookup --> compare["Compare the current code or workflow against the boundary"]
  compare --> decision["Turn the comparison into a keep, change, or reject call"]

Read the first diagram as a lookup map: this page is part of the review shelf, not a first-read narrative. Read the second diagram as the reference rhythm: arrive with a concrete ambiguity, compare the current work against the boundary on the page, then turn that comparison into a decision.

When a Make-based build misbehaves, the first job is to reduce confusion.

This page provides a stable escalation path for diagnosing rebuild, correctness, and parallel-safety incidents without folklore.

Step 1: Preview¶

Ask what Make intends to do before you let it do it.

make -n <target>

Use this to catch unexpected target selection, recipe fan-out, and accidental default-goal behavior.

Back to top

Step 2: Trace Causality¶

Ask why Make believes work is necessary.

make --trace <target>

This is the fastest path to locating a stale edge, a changed prerequisite, or a hidden assumption that someone modeled indirectly.

Back to top

Step 3: Dump The Evaluated World¶

Ask what rules and variables Make actually ended up with.

make -p > build/make.dump

Use this when command-line variables, includes, or layered mk/*.mk files are making the behavior hard to see by inspection.

Back to top

Step 4: Prove Or Break Convergence¶

Ask whether the build reaches a stable state.

make all
make -q all

If the second command says work is still needed, treat that as a real defect, not as a "Make being weird" moment.

Back to top

Step 5: Stress Concurrency¶

Ask whether the graph stays truthful when scheduling changes.

make -j2 all

Parallel-only failures usually indicate one of these:

missing edge
multi-writer output
shared mutable state
non-atomic publication
misuse of order-only prerequisites

Back to top

Step 6: Reduce To A Repro¶

If the build is still confusing, make the failure smaller before you keep theorizing.

The target outcome is a tiny Makefile that preserves the defect class and removes everything else.

This is where capstone/repro/ becomes especially useful as a reference for what a good teaching or debugging repro looks like. When you need an executed example instead of a hand-driven repro, use make PROGRAM=reproducible-research/deep-dive-make capstone-incident-audit and read the published Repro Catalog.

Back to top

Fast Symptom Table¶

Symptom	First suspicion	First command
unexpected rebuild	changed prerequisite or hidden input	`make --trace <target>`
build never converges	non-modeled input or self-poisoning output	`make all && make -q all`
only fails under `-j`	missing edge or shared state	`make -j2 all`
CI differs from local	version, shell, locale, or discovery drift	`make -p` and portability audit
release bundle looks wrong	build truth and release truth are mixed	inspect `dist` contract and manifest inputs

Back to top