--- title: "Before you repair data, build the diagnostic" canonical: https://dxdev.com/blog/2026-06-27_most-bugs-are-dirty-data-so-build-the-diagnostic-first/ datePublished: 2026-06-27 --- Many issues arrive with an explanation already attached: “the record is missing,” “the data is corrupt,” “the login is broken,” or “the page failed to save.” Those descriptions are useful starting points, but they are not evidence. The strongest work I did in this group of issues was not a code patch. It was building small diagnostics that could answer a narrower question: **what does the system actually know, and which parts of that state are genuinely inconsistent?** That question prevented two different kinds of expensive mistake. In one case, a complaint that sounded like missing data turned out to be a mismatch between the account model and the person trying to use it. In another, a repair tool initially flagged several rows as broken, but a preview showed that most were valid records in a state the tool had not yet learned to recognize. ## A report is a hypothesis, not a diagnosis A user describes the symptom they can see. The system stores facts at several layers: identity, permissions, contact methods, relationships, configuration, content, and lifecycle state. Those layers do not always align with the words used in a support request. Before changing data, build or reuse a read-only view that lets an authorized reviewer see the relevant relationships together. It should answer the smallest useful question without exposing more personal or operational detail than necessary. For an access problem, that may mean comparing the person, their permitted identity, the login path, and the role that governs access. For a layout or configuration problem, it may mean comparing the visible structure with the stored references and the state that explains why an item is intentionally unplaced. The point is not to collect everything. It is to replace a vague story with enough evidence to decide whether there is a defect, an expected exception, a data-model gap, or a user-experience misunderstanding. ## Preview before repair A diagnostic that only returns “bad” and “good” can create its own damage. The first version of one tool found several rows that did not match its expected structure. A bulk cleanup was tempting. The preview made the important distinction: some records were truly inconsistent; others were deliberately waiting outside the active structure. Without that preview, a repair would have deleted or moved valid content merely because it was not where the tool expected it to be. A safe repair workflow separates four stages: 1. **Read and classify.** Inspect the authoritative state without mutation and explain why each item was flagged. 2. **Preview the proposed change.** Show what would change, what will remain untouched, and why. 3. **Require authorized confirmation.** For consequential changes, ensure an accountable person reviews scope, customer impact, and recovery before the write occurs. 4. **Verify the result.** Confirm the intended inconsistency is resolved, valid exceptions remain intact, and audit records support later investigation or reversal. The preview is not a decorative feature. It is the boundary between a diagnostic that informs judgment and an automation that can silently turn a false assumption into a destructive action. ## Fix the model, not only the symptom The other lesson is that a clean data record can still reveal a product assumption that no longer fits reality. A system may assume that the person who owns an account is the person who uses it, that every item belongs in the active view, or that an empty relationship always indicates an error. Those assumptions work until a legitimate case falls outside them. When it does, the right response is not automatically to force the data back into the old shape. It may be to clarify ownership, support a valid alternate relationship, make the workflow understandable, or limit a feature to the cases it was actually designed to serve. This is why diagnostics are durable product work. They do not only find bad rows. They reveal where the software's mental model differs from the people and work it is supposed to support. ## The takeaway Before you repair data, make sure you can explain what is wrong, what is valid, and what will change. Start with read-only evidence. Preview a proposed repair. Keep authorized human judgment at the decision point. Verify the outcome and preserve a recovery path. The goal is not to make data conform to the first rule a tool can express. It is to make the system more truthful about the difference between a real inconsistency, a valid exception, and an assumption that needs to be redesigned. ## Related - [Before you automate a process, make sure the information is telling the truth](/ai-at-work/2026-06-27_before-automation-make-sure-information-is-true/): the plain-language companion to this evidence-first approach - [A presence check is not type validation](/blog/number-nan-type-assumption-crashed-bracket-save/): another example of a valid record exposing a narrow software assumption