Skip to content

BuilderIO/agent-native / .agents/skills/reliable-mutations

reliable-mutations

Verified

How the agent must perform writes so they actually persist under the hosted foreground run budget and long-running background handoffs. Use whenever you create, update, delete, or batch-write app data — especially "do this for many items" loops, or any task where the user expects N things to end up saved.

FileKindSize
SKILL.mdskill md3.4 KB
---
name: reliable-mutations
description: >-
  How the agent must perform writes so they actually persist under the hosted
  foreground run budget and long-running background handoffs. Use whenever you
  create, update, delete, or batch-write app data — especially "do this for many
  items" loops, or any task where the user expects N things to end up saved.
scope: dev
---

# Reliable Mutations

## Rule

Make a change in **one atomic call** when the action supports it, then **verify
the persisted end state and report concrete proof** (counts/ids). Never drive a
multi-step change by looping many small writes, and never report success from a
tool ✓ alone.

## Why

Hosted foreground agent runs have a short soft budget so they can hand off
cleanly under synchronous serverless walls. Durable background runs get a much
longer budget, but they still should not rely on loops of many small writes:
continuations can retry the same intent and leave partial state if each item is
committed separately. One atomic call commits or fails as a unit; verification
turns a hopeful ✓ into a fact.

## How

1. **Prefer a single atomic call.** If an action accepts the whole set (add
   many, set all, bulk update), pass the full batch in one call so it commits
   atomically. Check the action surface for a batch/plural form before reaching
   for a loop.
2. **Do not loop many small writes under any run budget.** A sequence of N
   per-item writes can still leave partial or no state when a foreground run
   hands off, a background run continues, or an upstream provider fails. If no
   batch action exists, that is a gap in the action layer — add or extend an
   action that accepts the batch (see the `actions` skill) rather than papering
   over it with a loop.
3. **Verify the end state after writing.** Re-read the data (a list/read action,
   a count query) and confirm the result matches intent — the right number of
   rows, the expected ids/fields. Do this before you tell the user it worked,
   and include the relevant verification expectation in the app's `AGENTS.md`.
4. **Report proof-of-done, not vibes.** State concrete evidence: "saved 12 of 12
   panels (ids …)" or "updated 5 rows". Do not infer success from the presence
   of a tool ✓ on an individual call.
5. **On a time-budget cutoff, fail loud.** If the turn is cut before the change
   is fully committed and verified, say so explicitly and report what *did*
   persist (M of N) and what remains. Never round a partial or unverified write
   up to "done".

## Don't

- Don't loop `for each item: write(item)` for a large set in a single hosted
  turn.
- Don't claim completion because every tool call returned ✓ — a ✓ on an aborted
  chunk does not mean the row was committed.
- Don't silently shrink the scope ("I added a few of them") and present it as the
  finished task.
- Don't try to "fix" this by asking for a longer run timeout — the budget is
  correct; restructure the write instead.

## Related

- `actions` — define or extend a batch/atomic action when only per-item writes
  exist.
- `storing-data` — where app data lives and how reads/writes are scoped.
- `performance` — avoid query waterfalls when verifying end state.
- Design doc: `packages/core/docs/design/durable-agent-runs.md` — the real
  ceiling fix (checkpointed and durable runs); this skill is the agent-facing
  mitigation that reduces how often the ceiling is hit.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall