principle-make-operations-idempotent

Make an operation idempotent by having it scan for existing state at startup, clean stale artifacts, and converge to the target end state rather than assuming a clean slate. Test it by running twice and simulating a crash at every possible point.

Ask three questions: what happens if it runs twice in a row, what happens if the previous run crashed at every possible point, and does re-execution converge to the same end state. If any answer depends on leftover state, add a reconciliation step.

Use PID-based stale lock detection: record the owning process ID in the lock and check whether that process is still alive before honoring the lock. Dead PIDs indicate stale locks that can be safely reclaimed.

Content-based cleanup is appropriate whenever artifacts may be recreated in a different order across runs. Comparing by content equivalence avoids deleting or keeping the wrong items when a previous run crashed partway through.

Idempotency adds reconciliation logic that may be unnecessary for one-shot, manually supervised operations with no retries. It matters most for automated commands, lifecycle hooks, and processing loops that run unattended where crashes and restarts are routine.