Checkpoint and Rollback Manager with Compensation Steps and Failure Injection Tests

Guides Claude Code to implement checkpoint snapshots, rollback modes, and compensating actions for side-effecting agent phases, then prove them with failure-injection tests. Helps you decide the rollback strategy per phase.

You get: Findings and safe-to-run-unattended verdict with reasons, phase risk table and files changed with purpose

More like this

The prompt

checkpoint-and-rollback-manager-with-compensation-steps-and-failure-injection-tests.md
Role: You are a distributed workflow engineer using Claude Code in {repo_path}, with access to read code, edit files, and run commands.

Context: The pipeline for {pipeline_goal} contains phases with side effects such as {side_effect_examples}. When a late phase fails, earlier outputs may be stale or partially applied. The decision to support: for each phase, choose restore-from-checkpoint, compensate, or manual intervention, and decide whether the current design is safe to run unattended.

Task: Implement a checkpoint and rollback manager in {language} that snapshots phase state, supports rollback to a named checkpoint, runs compensating actions in reverse order, and records an audit trail. Prove behavior with failure-injection tests.

Inputs (ask for missing items; list assumptions separately):
- {phase_list} with side effects and whether each is idempotent
- {checkpoint_store} and retention limit {retention_count}
- {rollback_policy_defaults}
- Which phases cannot be undone
- {test_framework}

Workflow:
1. Discovery: read the existing execution and state code. Report how state is currently stored and where side effects occur, with file evidence.
2. Phase risk table: Phase, Side effect, Idempotent (yes, no, unknown), Rollback mode, Compensation action, Residual risk.
3. Design: checkpoint record format (run id, phase, timestamp, state hash, schema version), rollback API, and compensation registry.
4. Implement: snapshot write, integrity check on read, rollback to checkpoint, reverse-order compensation, and an append-only audit log. If compensation fails, halt and mark the run needs-manual-review.
5. Failure injection tests: crash after snapshot, failure mid-phase, compensation raising an error, corrupted checkpoint, and repeated rollback (idempotency). Run them and report real results.
6. Review the diff for unsafe assumptions.

Constraints:
- Never run destructive commands against real external systems; use fakes or mocks
- Do not mark a phase reversible without evidence or a stated assumption
- Do not delete checkpoints beyond the retention limit without logging
- Keep changes scoped to orchestration code
- No secrets in logs, fixtures, or audit records

Output format:
1. Findings and safe-to-run-unattended verdict with reasons
2. Phase risk table
3. Assumptions and open questions table
4. Files changed with purpose
5. Failure-injection test matrix: Scenario, Expected, Actual, Status
6. Risks, missing information, and next actions as a checklist

Acceptance criteria:
- Rolling back twice yields the same final state
- Corrupted checkpoints are detected and never restored
- Compensation runs in reverse completion order and skips phases that never completed
- Compensation failure halts the run with a clear status
- Every audit entry includes run id, phase, action, and outcome

Quality checks:
- Confirm each acceptance criterion has a passing test or an honest note on why not
- Confirm no test touches real external services
- Check retention cleanup is logged
- State explicitly what remains unverified

Tips and common edits

Use after the basic runner exists. Be candid about which phases are non-idempotent, since the verdict depends on it. Ask Claude Code to stop after the Phase risk table if you want to approve rollback modes before implementation.

Questions about this prompt

Agent Run Post-Mortem: Trace Root Cause and Prompt or Tool Fixes

Analyzes a pasted agent trace to find the first real failure and proposes exact prompt rewrites or tool changes, each with a test.

DAG Scheduler with Fan-Out/Fan-In Barriers and Resumable Run Ledger for Agent Pipelines

Guides Claude Code to build or refactor a dependency-aware DAG scheduler for agent phases, with cycle validation, bounded parallelism, join policies, retries, and an append-only run ledger so interrupted runs resume without redoing finished nodes.

Orchestrator System Prompt Builder with Progress Ledger and Stop Conditions

Writes a ready-to-deploy orchestrator system prompt that delegates to your workers, tracks progress in a ledger, merges results and stops on defined conditions.

Parallel Git Worktree Task Split with Interface Contracts and Merge Order

Turns a pasted feature spec into independent coding-agent tasks with file ownership, interface contracts, a merge order and a done command for each task.

Subagent Fan-Out Plan for a Large Codebase Migration

Plans a big migration so an orchestrating agent can split it into independent chunks for parallel subagents, each with a clear brief, a verification command and merge rules.

Typed Phase Handoff Contracts and Validator for Multi-Agent Pipelines

Has Claude Code define schema-based handoff contracts between agent phases, generate a validator, and add contract tests. Supports the decision of which phase boundaries need strict contracts versus lightweight checks.

Claude Code Plan-Then-Implement a Feature With Approval Checkpoints

Makes Claude Code explore the repo, write a step-by-step plan for your approval, then build the feature in small verified steps, stopping at each checkpoint for your go-ahead.

Coding Agent Task Brief with Guardrails, Test Plan, and Rollback Steps

Creates a scoped brief for an AI coding agent that limits file changes, defines tests, and includes a rollback plan and review checklist.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Claude Code Behavior-Preserving Refactor with Characterization Tests and Staged Commits

Guides Claude Code to refactor a module safely by first pinning current behavior with characterization tests, then applying small reversible steps with verification after each. Delivers a diff, risk register, and rollback plan.

Claude Code Feature Implementation Plan and Build from a Ticket with Repo Convention Discovery

Has Claude Code investigate how similar features are built in the repository, produce an implementation plan with acceptance tests, then implement it in verified increments. Surfaces risks, open questions, and next actions before and after coding.

Claude Code Hook Writer: Auto-Run Lint, Typecheck or Tests After Edits

Produces a PostToolUse hook entry for settings.json, the script it calls and a concrete procedure to test that the check runs after file edits.