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.
This repository (Asymmetric-al/core)
Vendored from p3-stack (MIT) at commit 09909eb. Provenance is in references/upstream.md. On conflict, the current user request, root AGENTS.md, the nearest nested AGENTS.md, and the matching docs/ai/rules/* rulebook win over this skill.
- Explicit invocation only: use it when the user invokes
/principle-make-operations-idempotent (Claude Code, Cursor, T3 Code) or $principle-make-operations-idempotent (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.
- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.
Edit this canonical copy in docs/ai/skills/principle-make-operations-idempotent/, then run bun run skills:sync and bun run skills:verify.
1---2name: principle-make-operations-idempotent3description: "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."4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/asymmetric-al/principle-make-operations-idempotent7---89# Make Operations Idempotent1011Design 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?"1213**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.1415**The pattern:**1617- Convergent startup: scan for existing state, clean stale artifacts, adopt live sessions18- Content-based cleanup: compare by content equivalence, not creation order19- Self-healing locks: use PID-based stale lock detection20- Idempotent scheduling: failed work respawns cleanly, fresh input regenerated after each cycle2122**The test:**23241. What happens if this runs twice in a row?252. What happens if the previous run crashed at every possible point?263. Does re-execution converge to the same end state?2728If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.2930<!-- CORE-OVERLAY-START -->3132## This repository (Asymmetric-al/core)3334Vendored from [p3-stack](https://github.com/uzairansaruzi/p3-stack) (MIT) at commit `09909eb`. Provenance is in `references/upstream.md`. On conflict, the current user request, root `AGENTS.md`, the nearest nested `AGENTS.md`, and the matching `docs/ai/rules/*` rulebook win over this skill.3536- Explicit invocation only: use it when the user invokes `/principle-make-operations-idempotent` (Claude Code, Cursor, T3 Code) or `$principle-make-operations-idempotent` (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.37- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.3839Edit this canonical copy in `docs/ai/skills/principle-make-operations-idempotent/`, then run `bun run skills:sync` and `bun run skills:verify`.4041<!-- CORE-OVERLAY-END -->