principle-make-operations-idempotent

Make a script idempotent by designing it to converge to the correct end state regardless of starting conditions. Scan for existing state at startup, clean stale artifacts, adopt live sessions, and add reconciliation steps wherever partial state could change the next run's outcome.

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

Use PID-based stale lock detection: record the process ID in the lock and check whether that process is still alive before treating the lock as valid. This lets a restarted operation self-heal instead of blocking on a lock left by a crashed run.

Use content-based cleanup whenever artifacts may be recreated or reordered across runs. Comparing by content equivalence avoids deleting or keeping the wrong items when a previous run crashed midway and left partial outputs behind.

Retries fail when partial state from the crashed run changes the next run's behavior, such as leftover locks, half-written outputs, or consumed inputs. Idempotent scheduling respawns failed work cleanly and regenerates fresh input after each cycle.