Task shape: choose how to run it, then declare it

The wrong shape costs more than any wording inside the prompt. A loop with no gate spins until the money runs out. A fan-out over steps that depend on each other redoes the same work in parallel. A subagent sent to answer a one-grep question pays a whole context to learn what grep would have told you. A scheduled job with no stop and no report fails silently every morning for a month. Each of these happens in real projects; anonymized cases are in references/cases.md. Read one when a situation feels familiar.

This skill is the two-minute decision that precedes any multi-step or unattended work, and the five-line declaration that goes with it. It does not build the loop, write the Workflow script, or decide whether something should be automated at all; the hand-offs are at the end.

First: is this even multi-step?

Most tasks are a single pass: read, think, write, done. If you can finish it in one turn with the tools in front of you, do that. Running this skill on a typo fix is itself the waste it warns against. Continue only when the task has one of these properties: it repeats, it iterates until a check passes, it runs while nobody is watching, it fans out over more than a handful of independent items, or it will cost money outside this session.

If none apply, say so in one line, "Shape: single pass, nothing unattended," and go. Do not write the five-line declaration for a task with no unattended part; a declaration that says "in-session only, no external spend, one pass" is ceremony, and ceremony is what makes people stop reading declarations.

The four questions

Answer them in order; each one rules shapes out.

1. Can a machine check when it is done? A test that goes green, a diff that is empty, a number that crosses a threshold, a file that exists with the right shape. If the only judge is a person's taste, no loop will help: do a single pass and put the result in front of the person. A loop whose gate cannot fail the work is an expensive way to make the model agree with itself.
2. Does it have to outlive this session? If the work must happen tomorrow or every Monday, nothing in-session is the answer. It is a scheduled job, and it gets built only after one manual run has been proven reliable.
3. Are the pieces independent? If N items can each be judged without knowing the others, they can fan out. If step 3 needs step 2's result, they are a sequence, and running them in parallel produces N confident answers to the wrong question.
4. What does one wrong step cost? Tick each that applies. Binding: the output commits someone to something. Customer-facing: a person outside the team sees it. Depended-on: other software or reports read it as true. Trust: a mistake would cost a customer's or partner's trust. One tick means the run's output goes through a human review gate before it is acted on, whatever shape you choose. The shape decides how the work is done; the gate decides whether its result may leave the room.

The shapes

Default to the lightest shape that works. Graduating later is cheap; a heavy shape chosen out of habit is paid for on every run.

Two shapes are easy to confuse. A script repeats without judgment: the same command on each item. A fan-out applies judgment to each item. If you find yourself writing a prompt that says "for each file, do X" and X is a command, that is a script, and a loop of subagents would cost a hundred times more for the same result.

Before any unattended run: the declaration

Once the shape is chosen, and before anything runs that nobody is reading step by step, write five lines. They go in the plan you show the user, in the handoff note if the run outlives the session, and at the top of the prompt handed to a subagent or loop. Treat it as a rule, not a suggestion: an unattended run without a declaration does not start.

SHAPE     script + self-checking loop, max 10 runs
CEILING   US$50 across the batch (the user's number); about US$5 a run
STOP      result settles below the threshold for 40 steps  |  10 runs  |
          2 failed attempts, then question the model, not the parameters
REPORT    once, at the end: four sentences plus one closed question
NEVER     read eval/answer-key.md; push any commit; touch other projects

• Shape. One of the eight, with the cap on iterations or agents.
• Ceiling. In dollars or tokens. Anything that spends outside this session (a script calling a model, a cloud routine, a Workflow) runs on the user's number; if they have not given one, propose it and wait. Work inside this session is the session's cost and needs no separate yes, but it still carries its iteration cap.
• Stop. Two exits, always: the success check a machine runs, and the hard cap. Add a timebox on attempts: after N failures, stop tuning parameters and question the approach. Without the timebox a loop tunes parameters forever and never runs the real thing.
• Report. Once, at the end, in the length the reader asked for. A report per iteration turns a background run into a feed the user has to read.
• Never. The files and folders the run must not read or write: sealed answer keys, other projects' folders, gated outputs, anything whose reading would make the result untrustworthy or whose writing would deploy.

A run that must outlive the session also needs proof of life: it writes a dated line to a file somebody reads ("ran, 14 items, 0 errors") every time it runs. A scheduler reporting "succeeded" is not evidence; a missing line is.

Token discipline inside any shape

• Scope the context. Load the instructions and the inputs the step names, not the whole project. Scoped context is what keeps a step cheap and legible.
• Tell a subagent what to return. "Report the three files that define the pricing ladder and the line where the flag is read" comes back in a paragraph. "Look into pricing" comes back as a transcript.
• Do not poll with a model. Task notifications wake you when work you started finishes. Wake on a timer only for state the harness cannot see, and pick the interval from how fast that state changes: a CI run that takes eight minutes gets one check at eight minutes, not eight checks at one.
• Batch independent calls in one message. Sequential calls that do not depend on each other pay latency for nothing.
• Name the output contract. The file the run writes and its shape, so the result can be checked by reading one file rather than a transcript.
• Exhaust the free version first. A dry sweep of a parameter costs nothing; run it before the sweep that costs a dollar a point.
• Measure cost per accepted result, not tokens burned. If fewer than half the iterations produce something kept, the loop is costing more than it saves; stop and change the approach rather than the parameters.
• Retry the cheap failures. A network reset on the first of several hundred calls should not end the run. Retry transient errors a few times with backoff, and count the retries against the ceiling.

Writing the prompt for a subagent, a loop, or another agent

Six parts, in this order, each a line or two. The order matters: the goal first so everything after is read against it, the constraints last so they are the freshest thing in context when the work starts.

1. Goal: the end state, in a form that can be checked.
2. Inputs: the files by path. Not "the relevant context".
3. Output: the file to write and its shape.
4. Stop: the gate and the cap, from the declaration.
5. Never: from the declaration.
6. Report: what to say back, and how long.

Say why a constraint exists when the reason is not obvious; a model that understands why a file is sealed does not look for a workaround. Mark any hypothesis as a hypothesis: "this is a candidate, not an instruction, and say so if the run refutes it" produces an honest result where "fix it this way" produces a confirmation.

Hand-offs

When you are the agent running unattended under an order, use the declaration above and build the loop yourself; do not stop to interview a user who is not there.

Anti-patterns

• Loop with no gate: the model grades its own work and passes it.
• Fan-out over dependent steps: parallel answers to a moving question.
• Subagent for a one-grep question: a whole context to learn a line number.
• Ceiling by hope: "it should be cheap" is not a number.
• Feed instead of report: per-iteration updates to someone who asked for one summary.
• Cron with no stop: a scheduled job that fails every morning and tells nobody.
• Scheduling before proving: automating a run that has never once worked by hand.
• Reading the answer key: a run that can see the file it will be scored against is not an experiment.