principle-make-operations-idempotent
cursor/plugins
Design operations to converge to correct state regardless of crashes, restarts, or retries.
What is principle-make-operations-idempotent?
A design principle for making commands, lifecycle steps, and processing loops resilient to partial failures. Apply this when building systems that must handle crashes, restarts, and retries without leaving inconsistent state behind.
- Ensure operations produce the same end state whether run once or multiple times
- Scan for existing state and clean stale artifacts on startup
- Detect and handle stale locks using PID-based validation
- Regenerate fresh input after each cycle so failed work respawns cleanly
- Compare state by content equivalence rather than creation order
How to install principle-make-operations-idempotent
npx skills add https://github.com/cursor/plugins --skill principle-make-operations-idempotentHow to use principle-make-operations-idempotent
- 1.Identify all state-mutating operations in your system
- 2.For each operation, ask: what happens if this runs twice? What if it crashed halfway?
- 3.Add a reconciliation or scan step at the start to detect and adopt existing state
- 4.Use content-based comparison instead of timestamps or creation order to identify duplicates
- 5.Implement stale lock detection (e.g., PID-based) for any locking mechanism
- 6.Test by running operations multiple times and after simulated crashes at different points
Use cases
- Designing deployment or provisioning scripts that may be interrupted and re-run
- Building background job processors that must survive worker crashes
- Creating database migration systems that can safely resume from any point
- Implementing service startup routines that clean up after unclean shutdowns
- Designing retry logic for distributed systems where partial state changes are common
- Backend engineers building resilient systems
- DevOps engineers designing deployment automation
- Distributed systems developers
- Anyone building crash-recovery mechanisms
principle-make-operations-idempotent FAQ
Run it twice in a row and verify the end state is identical. Then simulate crashes at every possible point in the operation and verify re-execution converges to the same state.
Retrying alone doesn't prevent partial state changes from corrupting the next attempt. Idempotent operations actively reconcile or scan for existing state so retries always converge correctly.
Focus on state-mutating operations that run in environments with crashes, restarts, or retries: deployments, migrations, background jobs, and service startup routines.
Use content-based equivalence checks rather than timestamps, and implement PID-based stale lock detection. Scan for existing state at startup and adopt or clean it as needed.
Full instructions (SKILL.md)
Source of truth, from cursor/plugins.
name: principle-make-operations-idempotent description: "Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs." disable-model-invocation: true
Make 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.
Related skills
More from cursor/plugins and the wider catalog.
principle-migrate-callers-then-delete-legacy-apis
Migrate callers and delete legacy APIs in one refactor wave instead of maintaining compatibility layers.
principle-minimize-reader-load
Reduce code complexity by minimizing reader cognitive load—collapse unnecessary layers and shrink mutable state.
principle-model-the-domain
Encode domain logic in structures instead of scattered conditionals and repeated assumptions.
principle-never-block-on-the-human
Proceed with reversible work without asking permission; reserve confirmation for irreversible actions only.
principle-outcome-oriented-execution
Prioritize end-state correctness over intermediate stability during planned rewrites and migrations.
principle-prove-it-works
Verify task completion by checking real artifacts, not proxies or self-reports.