principle-make-operations-idempotent

Designs state-mutating operations to converge to the same end state across retries and crashes.

3|2|Updated Aug 28, 2026
One-click install
npx skills add https://github.com/adjohn/pstack --skill principle-make-operations-idempotent-adjohn
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: principle-make-operations-idempotent
Source: https://github.com/adjohn/pstack/tree/main/skills/principle-make-operations-idempotent
Command: npx skills add https://github.com/adjohn/pstack --skill principle-make-operations-idempotent-adjohn

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Commands, lifecycle steps, and processing loops run in environments where crashes, restarts, and retries are normal. When partial state from a failed run changes the next run's outcome, every restart becomes a debugging session. This Skill provides a design principle for making operations safe to re-run. ## Core Features & Use Cases - Convergent Startup: Scan for existing state, clean stale artifacts, and adopt live sessions instead of assuming a clean slate. - Content-Based Cleanup: Compare artifacts by content equivalence rather than creation order to avoid duplicate or orphaned state. - Self-Healing Locks: Use PID-based stale lock detection so crashed processes do not permanently block future runs. - Idempotent Scheduling: Respawn failed work cleanly and regenerate fresh input after each cycle. - Use Case: When writing a CLI command that provisions resources or a worker loop that processes a queue, apply the three-question test (runs twice, crashes at any point, converges to the same end state) to identify where a reconciliation step is needed. ## Quick Start Ask the AI to review your command, lifecycle step, or processing loop for idempotency and identify where partial state could change the outcome of a re-run.

Frequently Asked Questions about principle-make-operations-idempotent

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make a command or script idempotent?▼

Make the operation converge to a target state instead of assuming a clean start. Scan for existing state on startup, clean stale artifacts, adopt live sessions, and ensure running it twice produces the same result as running it once.

What is the test for whether an operation is idempotent?▼

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.

How do I handle stale lock files after a process crash?▼

Use PID-based stale lock detection. On startup, check whether the process ID recorded in the lock is still alive; if not, the lock is stale and can be safely reclaimed instead of blocking all future runs.

When should I use content-based cleanup instead of creation order?▼

Use content-based cleanup whenever artifacts may be recreated or reordered between runs. Comparing by content equivalence prevents duplicate or orphaned state that order-based comparisons miss after crashes and retries.

When does idempotency design not apply?▼

It matters most for state-mutating operations that run amid crashes, restarts, and retries, such as commands, lifecycle steps, and processing loops. Pure read-only or single-shot operations with no persistent state do not need reconciliation logic.