principle-make-operations-idempotent
About principle-make-operations-idempotent
A software development skill for designing state-changing operations that converge on the intended state when repeated or resumed after a crash. It outlines reconciliation patterns and checks for restart-safe behavior.
Key features
- 01Design operations to converge
- 02Account for retries and crashes
- 03Use stale-state cleanup patterns
- 04Check behavior across reruns
Use cases
- 01Making startup safe to repeat
- 02Handling interrupted processing loops
- 03Designing retryable lifecycle commands
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/principle-make-operations-idempotentin Claude Code to confirm it loaded.
Bundled filesLICENSE
Details
From the project READMEMake Operations Idempotent
Design operations so they converge to the correct state regardless of how many times they run or where they start from. Every state-mutating operation should answer: "What happens if this runs twice? What happens if the previous run crashed halfway?"
Why: Commands, lifecycle operations, and processing loops run where crashes, restarts, and retries are normal. If partial state changes the next run's outcome, every restart becomes a debugging session.
The pattern:
- Convergent startup: scan for existing state, clean stale artifacts, adopt live sessions
- Content-based cleanup: compare by content equivalence, not creation order
- Self-healing locks: use PID-based stale lock detection
- Idempotent scheduling: failed work respawns cleanly, fresh input regenerated after each cycle
The test:
- What happens if this runs twice in a row?
- What happens if the previous run crashed at every possible point?
- Does re-execution converge to the same end state?
If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.