Skip to content

BuilderIO/agent-native / packages/core/src/templates/chat/.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.

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: 466kUpdated Claude CodeCodexUnverifiedInstall
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: 466kUpdated Claude CodeCodexUnverifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall