Dustin SnellingsSoftware engineer

Build journal / Engineering note

When --write and --check disagree, the formatter is the bug

A formatter changed embedded lesson code. Public commits show how I stopped the rewrite and repaired the examples with AI assistance.

All notes

Public repair checkpoint ·

A formatting tool was changing the code that DURA was teaching. The first repair was to stop letting that tool rewrite the lesson files.

DURA embeds runnable examples in MDX lessons. The public repair record describes Prettier interpreting characters inside JSX code props as Markdown emphasis, changing identifiers and comments. It also records a non-idempotent result: running --write did not produce files that --check accepted.

Stop the source of the damage

The initial fix restored two C examples, added **/*.mdx to .prettierignore, and removed MDX from the commit hook’s formatting pattern. That established a boundary: this formatter could still handle other files, but it could no longer automatically rewrite lesson content.

Repair the examples in context

A follow-up repair restored embedded code and indentation through AI-assisted review against each lesson’s surrounding examples and task. A second pass also corrected factual errors found during that review.

The July 5 repair checkpoint documents another failure mode: a search for damaged type suffixes had missed an underscore inside compute_parametric_var. It records restoring those identifiers, using language-specific formatters for exercise blocks, and validating Python formatting with Black. The remaining search matches included legitimate math and regular expressions.

What the evidence supports

The linked commits show the changes and record build, typecheck, and lint results from the repair work. Those checks support the repair process; they do not establish that every code example was executed or that the whole curriculum was free of errors. The date above identifies a public repair checkpoint, not when the incident began.

The work was AI-assisted. The initial commit declares approximately 95% assistance and the follow-up repairs declare approximately 100%. I authored and integrated the changes; those declarations describe assistance, not independently measured percentages or proof of correctness.

The principle I carry forward

A tool that rewrites content needs a check that understands what that content means. A lesson can render while teaching broken code. Formatting, compilation, and educational accuracy are different questions, and each needs its own evidence.

verso