Say the outcome
A well-framed request names what done looks like and leaves the route to the agent.
06chapters · a complete reference
~12 minfull read · any chapter stands alone
18field notes — tips, gotchas & rules
1core idea · work with the agent, not around it
01 · Framing requests
Frame the outcome, not the method.
Operator's output is only as good as your instruction — not because it needs hand-holding, but because ambiguous scope invites over-reach. A well-framed request usually runs without a single clarifying question.
- Start with a clear outcome, not a method — Operator will sometimes find a better approach than the one you had in mind.
- Scope is your strongest lever. When in doubt, narrow it; you can always widen it on the next run.
- Constraints are information, not restrictions — “Node 18, no ESM” or “stay backwards-compatible” tells it how to decide without stopping to ask.
- Paste one concrete example — a single “like this” is worth three paragraphs of description, and Operator generalises from it.
02 · Letting it plan
Let it plan before it touches a file.
Operator reasons about the best path before acting. The reading phase is often longer than the writing phase — a quiet stretch is usually mid-read, not idle.
- Don't interrupt a quiet stretch — a reset loses the context Operator has built by reading your code.
- On ambiguous or risky tasks it surfaces the plan as text first — that pause is the approval gate working, not indecision.
- For large work it decomposes into phases itself; giving it a phased structure just makes each diff smaller to review.
- Ask it to “walk me through the plan before making changes” to approve, redirect or narrow before a character is written.
The quiet stretch is the work
Reading takes longer than writing. A pause before the first edit is the plan being formed.
Planning is not overhead. The biggest source of wasted agent time is acting on a misunderstood task — a 30-second plan prevents a 10-minute rollback.
03 · Reading the diff
Read the diff in two minutes flat.
Operator's output is a git diff, and reading it well is a fast skill. The goal isn't every line; it's the few that matter. The pattern: file list, then deletions, then test changes, then comments.
- Read the file list first — a change outside the expected radius is the most common thing worth redirecting. Sort by path, not line count.
- Scan deletions before additions. Added lines are usually low-risk; deleted lines are where intent lives. Red before green.
- Watch for quiet test relaxation — a new .skip() or a dropped assertion is a silent regression. Grep for skip/xit after every run.
- Read the comments Operator adds — they document the decision behind the change, not noise.
Scan boundaries first
Deletions and edited interfaces carry the risk. The rest of a diff usually reads itself.
04 · Approval gates
Gates are the handshake, not an interruption.
Operator pauses before anything hard to reverse — pushes, merges, schema migrations, infrastructure. For most tasks the only gate is the final “merge this PR?”; the rest runs unattended.
- If a run hits zero gates, check the scope — either it's genuinely safe to run unattended, or it's narrower than you realised.
- Each gate shows what it's about to do and why. Approve, reject, or redirect — you're approving intent, not implementation.
- Configure gates per workspace — before any network call, any deletion, any commit, or none at all for a trusted repo. Defaults are conservative.
- Gates carry context: reject with a reason and Operator folds it forward. A rejection is a course correction, not a restart — prior work stays.
Gates are cheap, mistakes are not
Irreversible steps stop and wait. Everything reversible keeps moving without you.
05 · When to redirect
Redirect the direction, correct the detail.
Redirection is the normal mode of working with an agent, not failure. Two or three redirects is a healthy session; knowing when to steer rather than restart is what keeps it productive.
- Wrong detail is a correction — one sentence. Wrong direction is a redirect — one paragraph. Restarts are rare.
- Surface the constraint, not the symptom: “stay compatible with v2 clients” beats “don't touch the schema” — it lets Operator solve it differently.
- Partial work isn't wasted — redirected files stay on disk and Operator builds on them next run. You're steering a session, not resetting a test.
- Some redirects are architectural — “step back, this is too complex” is valid; Operator assesses what to unwind and proposes a simpler path.
Correct the detail, not the run
One sentence naming the symptom beats a restart — the context it built is worth keeping.
06 · Recovering a run
Recovery is part of the workflow.
Occasionally a run stalls, errors, or produces output you can't use. With the right routine a stalled run is a five-minute interruption, not a lost afternoon.
- Most “errors” are clarification requests in disguise — a missing credential, an uninstalled dependency, a conflict in your instructions. Read the stop message; it's the most diagnostic output there is.
- Read the session log before restarting — every file read, plan, gate and action is there, so you can redirect to the point it went off-track instead of rerunning.
- For partial output, commit the good parts first, then start a narrower follow-up from that checkpoint — Operator reads the committed state and continues.
- Three failures at the same point means an environment problem, not a task problem — a missing dependency or an expired credential. Change something before retrying.
A stall is a message
Expired credentials, a missing dependency, a rate limit. Read it, fix it, resume from the checkpoint.
Operator is best understood in motion.
The guide gives you the vocabulary; the intuition comes from running tasks. Start with something small, in a codebase you know well.