Execution and Operations
The 8 principles in this chapter govern how work proceeds: how it is divided into units, how it survives crashes and concurrent actors, how the agent spends its context, and how it relates to the human who supervises it. A principle is a named pstack rule kept in its own skill file (its leaf); /poteto-mode reads the index of all principles and applies those a task triggers, as the Principles Overview explains. For unattended runs, see also Running Work While You Sleep.
Sequence Work into Verifiable Units (principle-sequence-verifiable-units)
Source: skills/principle-sequence-verifiable-units/SKILL.md
- Name: this is the one principle whose skill name departs from the title. The title is Sequence Work into Verifiable Units; the leaf is
principle-sequence-verifiable-units. - Rule: arrange work as a series of small units, each of which ends in a state you can check. Do not move to the next unit until the current one is green.
- The bracket: in a sweep, a migration, or a run of similar edits, each unit follows the same pattern: a known-good state, one change, the check, then onward. The per-unit check still runs when a tool makes the edits.
- Delivery order: order the work so that the sequence itself proves it to a reviewer.
- The failing test comes first, then the fix.
- The subtraction comes before the reshape.
- The baseline comes before the treatment.
- Every commit stands alone and passes by itself.
- Steering: when a single enormous diff appears, ask the agent to split it into verifiable units.
Make Operations Idempotent (principle-make-operations-idempotent)
Source: skills/principle-make-operations-idempotent/SKILL.md
- Rule: design every operation that changes state so that it converges on the correct state, regardless of how many times it runs or where a previous run stopped.
- Derive from what exists: base each step on the state that is actually present, and ignore what the previous run intended. Read the current state, compare it with the goal, and apply only the difference.
- Leftovers: whatever a run leaves in place (a lock, a temporary file, a record written only in part, a job it claimed) has to be identifiable as stale when the next run starts. The proof of staleness must remain valid at any point at which the earlier run could have stopped.
- Atomic writes: write to a temporary path, then rename the file into place.
- The test: imagine the operation running twice, and imagine the previous run crashing at each point where it could crash. If the outcome then depends on the leftovers, the design needs a reconciliation step.
- Steering: deployment and migration scripts are the obvious candidates for this principle.
Migrate Callers Then Delete Legacy APIs (principle-migrate-callers-then-delete-legacy-apis)
Source: skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md
- Rule: when a new internal API is introduced while old callers still exist, migrate the callers and delete the old API in the same wave. Compatibility layers that keep the old API alive are what this principle avoids.
- Tests: update the tests so they assert the new contract, and delete tests that only protect implementation details from before the refactor.
- Preconditions: the leaf limits the principle to cases where all 3 hold.
- No external callers rely on the old behavior staying compatible.
- The project is able to take breaking changes made in a coordinated way.
- The new API is part of a simplification or refactoring effort.
- Steering: name this principle when a diff introduces a compatibility shim “for now”.
Separate Before Serializing Shared State (principle-separate-before-serializing-shared-state)
Source: skills/principle-separate-before-serializing-shared-state/SKILL.md
- Rule: when concurrent actors might write to the same file, branch, key, or object, first ask whether they genuinely need one shared object or are merely publishing independent facts.
- Default: give each actor its own file, key, branch, or state directory, and merge only at the place where the state is read. The leaf adds that 2 workers each writing their own field into a single
state.jsonare still sharing mutable state. - Serialization: only when a single shared write target is a real invariant should access be serialized, and then structurally, with a lockfile, a single writer, sequential phases, or compare-and-swap.
- Cautions: instructions do not provide concurrency control, and the conclusion “we need a lock” is a smell to examine before acting on it.
- Steering: the guide’s example applies when 2 parallel attempts are about to write to the same branch:
separate before serializing shared state. give each attempt its own worktree, no locks.
Guard the Context Window (principle-guard-the-context-window)
Source: skills/principle-guard-the-context-window/SKILL.md
- Rationale: the leaf gives its reason directly. Overflowing the context degrades reasoning quality, introduces compression artifacts, and halts progress.
- Rule: when large outputs, long files, repeated reads, or fan-out planning start to fill the context, route the bulk work to subagents. The main thread keeps summaries; raw payloads stay out of it.
- Pattern: size each phase and cap its scope. That means limiting the number of files per phase, setting turn budgets, and counting the cost of the mechanism itself.
- Category: poteto-mode files this principle and Never Block on the Human under “Delegation”, which the guide describes as keeping parallel work manageable.
- Steering: a decline in answer quality late in a long session is a reason to name this principle.
Never Block on the Human (principle-never-block-on-the-human)
Source: skills/principle-never-block-on-the-human/SKILL.md
-
Premise: the leaf assumes a human who reviews work asynchronously, so the agent should never sit idle waiting for an answer. Because code changes can be reviewed and undone, an occasional wrong decision is usually cheaper than a stall.
-
Rule: make reasonable decisions, proceed, and let the human correct course afterwards.
- The leaf’s motto is “Proceed, then present”: do the work, show the result, and explain the reasoning instead of asking “should I do X?” beforehand.
- Let the system repair itself: record a problem when you see it, and correct it during the following round.
-
The boundary:
Kind of action Examples from the leaf Treatment Reversible Writing code, editing notes, splitting tasks Proceed without blocking Irreversible Force-pushing, deleting production data, sending external messages Still requires confirmation -
Direction and execution: the human sets the direction of the product, and carrying out the work should not stall while waiting for them.
-
Related rule: poteto-mode’s own “Autonomy” section draws a similar line, listing deploys, data deletion, customer messages, and force-pushes to shared branches as actions that always pause (see Using /poteto-mode).
-
Steering: when the agent stops to ask about a small, reversible choice, name this principle and tell it to proceed.
Outcome-Oriented Execution (principle-outcome-oriented-execution)
Source: skills/principle-outcome-oriented-execution/SKILL.md
- Rule: optimize for the intended, verifiable end state, and give less weight to keeping every intermediate state smooth.
- Rationale: keeping each step fully stable tends to create temporary compatibility code, which then becomes long-lived debt. The leaf prefers converging on the target architecture and proving correctness at explicit verification boundaries.
- Core rule: end-state integrity takes priority over transitional stability. Breakage in the middle is acceptable when it is planned, scoped, and reversible.
- Guardrails:
- Use the principle only for planned rewrites and migrations that have explicit phase boundaries.
- State in advance which areas may break temporarily.
- While migrating, keep high-signal checks on the areas being actively changed.
- Require full static and runtime verification when the plan is complete.
- Steering: name this principle when throwaway compatibility code accumulates in a migration. Its guardrails also mean it cannot justify unplanned breakage.
Experience First (principle-experience-first)
Source: skills/principle-experience-first/SKILL.md
- Rule: if what is easiest to implement differs from what would delight the user, the leaf sides with the user. The principle applies to trade-offs in product, UX, and feature scope.
- Practices:
- Each feature, control, and option needs a reason to exist.
- “Ship less, ship better.” By the leaf’s own measure, 3 polished features outperform 10 rough ones.
- Try ideas in disposable HTML before building them for production, where the same design decision costs far more.
- Polish the details, such as transitions, alignment, spacing, feedback, and error states.
- Keep the core loop tight, so that each feature either supports the central workflow or does not interfere with it.
- Who the user is: the leaf defines the user as anyone who consumes the work. That includes the end user of a UI, the colleague who imports a library or internal API, and the engineer who will maintain the code next. Each of them deserves the same consideration, and impact should be explained from their perspective.
- Relation to Foundational Thinking: the leaf places foundations in service of the experience. Foundational Thinking (see Premises and Thinking) decides the order in which work happens, whereas Experience First decides what the work is aiming at.
- Steering: when the agent proposes cutting scope because the implementation would be easier, name this principle and ask it to decide from the user’s side.