Business integrity review

Business State & Data Integrity Review

Use this skill when reviewing code that mutates domain state, transitions workflow statuses, performs multi-step writes, or triggers external side effects (emails, webhooks, payments, queues, file operations).

Workflow

1. Audit state-machine transitions and invariants:
   • Check that every state transition (fromState -> toState) validates the current state before mutating:
     • Are terminal states (completed, cancelled, archived, refunded) protected against illegal re-entry or mutation?
     • Are concurrent transitions guarded via optimistic locking (WHERE id = ? AND version = ? or AND state = ?) or row locks so two parallel requests cannot both succeed?
2. Verify transaction boundaries vs. external side effects:
   • Atomic local writes: Multi-table updates that must succeed or fail together must run inside a single database transaction.
   • No slow I/O inside DB transactions: Verify that external HTTP calls, LLM requests, or file uploads do not hold open database transactions or locks.
   • Partial failure & retry safety: Ask what happens if the database commit succeeds but the post-commit webhook/queue dispatch fails (or vice versa):
     • Can the operation be retried without creating duplicate records or double-firing external side effects?
     • If an async step fails or is cancelled mid-flight, is the entity moved to a clean, recoverable failure state rather than stuck in 'running' forever?
3. Check financial, counter, and cascade integrity:
   • Verify that numeric totals, quotas, and balances cannot go negative or drift under concurrent updates.
   • Check deletion and archival paths to ensure child records, foreign keys, and active references are neither orphaned nor destructively wiped without authorization.