Saop

SAOP: the plan-first executor

The most expensive mistake in AI-assisted work is building on a half-baked structure. A wrong assumption made at the start costs a whole block of work to unwind. SAOP removes that risk: it thinks a problem fully through, read-only, before the first line is written, and hands back a plan whose every endpoint is already checkable.

"Executor" means this skill executes the SAOP method, the planning pass, end to end. It does not write the implementation; that begins only after you approve the plan. The method README is the "why"; this is the "how": https://github.com/kaposty/saop

Read-only during the pass, and Plan Mode

The pass plans; it does not implement. It reads and researches (Read, Grep, Glob, WebSearch, WebFetch, and Bash for read-only checks like git log) and hands the plan back as text. Implementation of a planned task begins only after you approve, in a fresh message; the one exception is the triviality gate's light path below, which states its single change first and applies it only if you do not object. Treat destructive shell commands as out of scope during the pass.

"Read-only" is only as strong as what enforces it. The frontmatter drops the editing tools (Edit, Write, NotebookEdit) while the skill is active, but that restriction lifts on your next message, so it is a safety net, not a lock. The real guarantee is Plan Mode: there the harness blocks every state-changing command until you approve, across turns.

So the first thing to do on invocation, once the task is past the triviality gate below, is check whether the session is in Plan Mode:

• In Plan Mode: proceed. The read-only pass is genuinely enforced.
• Not in Plan Mode: turn it on by calling EnterPlanMode, with one short line on why ("switching to Plan Mode so the pass stays read-only across turns"). This keeps the verified protection on by default instead of relying on the human to remember to toggle it. EnterPlanMode asks the human to approve the switch, so it stays their call, not a silent takeover; if they decline, continue, but say plainly that the pass then only plans by convention, with no hard stop on an accidental write. The same applies where EnterPlanMode is not available (a non-interactive context): say so and continue read-only by convention. Plan Mode only supplies the enforcement; the SAOP phases below still govern what you do.

One honest caveat: subagents this skill may spawn to explore do not inherit Plan Mode. They are told to read only, but that is instruction, not a hard lock.

When NOT to run it (check first)

This is the first gate, before Step 0 and the phases. The method is a tool against expensive ambiguity, not a ritual. If the problem is trivial and well understood, its solution already in plain sight, do not run the full pass, say so and just do it. The light path is short but not blind: read the one place you are changing, state the exact change and the single check that verifies it, and make the change only once a message from the human has arrived after your statement and does not object to it (the invocation turn drops the editing tools anyway, so the edit can never land inside the skill turn); before you commit to "trivial", glance for the one hidden dependency that would make it not trivial (a name collision, an external caller, a shared config). If that glance turns something up, it was not trivial, so run the pass. SAOP earns its keep when many parts depend on each other, the path is unclear, or a late correction would cost a multiple of early clarification.

The method is domain-agnostic. It plans a new project or subproject, a feature, a migration, a security hardening, a compliance review, a backend, any body of work whose parts depend on each other. Nothing below is specific to writing code.

Step 0: Lock the goal first

Once the task has passed the triviality gate above as non-trivial, lock the goal before the four phases. SAOP plans the solution to an already-identified problem, so make sure you and the human are aiming at the same, well-scoped target. This is what keeps the plan from being excellent at the wrong thing.

• If the request is already a crisp, well-scoped problem, skip this and start sketching.
• If the goal is broad or open ("bring our cyber-security to top notch", "optimize and fact-check our compliance", "perfect the homepage backend"), do not guess the scope. Use the AskUserQuestion tool to lock it in one focused round:
  • the concrete target (what "done" looks like),
  • the success criterion (how we will know it worked),
  • the boundaries (what is explicitly in scope and what is out),
  • hard constraints (stack, deadline, must-not-touch areas).

Then restate the locked goal in one line and get a quick confirmation before Sketch. One round, not an interrogation: ask only the few questions that change what gets planned, kept to a handful of genuinely decisive ones, and do not pack many separate facts into a single question. Then proceed. If the human's answer reveals the real goal is different from the literal request, plan the real goal.

The four phases

Run them in this fixed order. The order is the acronym.

S · Sketch

Draft the rough solution as a sequence of a few main steps. Keep it deliberately coarse, a first draft, not a finished plan. From the outset, split every element into three buckets and keep them visible:

• Known: established fact.
• Assumed: taken to be true but unverified.
• Unknown: genuinely open. Note which unknowns reading or a cheap probe could answer (resolve those yourself) and which only the human can (ask those).

Ground the sketch in the real context, thoroughly. Do not plan from assumption where the facts are readable. Actively review everything that bears on the problem: the relevant code, docs, prior decisions, configuration, git history, and, where useful, external sources. Search broadly first, casting the field's own wide net (for code, glob for the likely files and grep for the symbol; for a legal question, the governing statutes and prior contracts; for a launch or market move, the comparable efforts and how they actually went) so you find all the relevant places, not just the first, then read them. Narrowing means skipping the irrelevant, never the relevant. If there is genuinely nothing to ground in yet (a brand-new project with no code or docs), say so plainly and plan from stated, flagged assumptions rather than inventing facts.

Understand the whole context, then let it set the criteria. Before optimizing anything, work out automatically what this project is: its purpose, the domain it lives in, and what it already stands for, the governing decisions, conventions, and constraints it carries, and the approaches it has already tried and rejected. These rarely live in the function under edit; read the project's own governing sources for them, its top-level docs, ADRs, configuration, and notes, not just the code nearest the task. The goal is comprehension deep enough that the evaluation criteria fall out of the context itself: you do not carry a fixed checklist into a problem, you derive, from understanding the domain, the criteria any good solution here must be judged against. A data-sovereignty project surfaces residency and legal basis; a latency-critical one surfaces tail latency; a cost-bound one surfaces price per unit. The skill is tuned to none of these, it reads which ones apply. Whatever you derive here is exactly what Optimize researches and scores against, so a shallow read of the context caps the quality of the optimum.

Check the lifecycle of what you plan to touch. Before proposing work on an existing artifact, establish its status: a thing marked deprecated, superseded, replaced-by-X, or already solved elsewhere is a closed decision. Read such a marker as binding, not as a defect list to action, resurrecting or re-implementing it repeats a decision the project already made, and reversing that decision needs its own explicit justification, never a silent plan step. Equally, state plainly how the plan relates to the project's stated goals or priorities: if it is orthogonal to them, say so openly rather than letting it read as progress toward them.

Coverage gate. Before going further, state plainly what you have read, what you still only assume, and what is unknown. If a structure-critical unknown can be answered by reading, read it; if only the human can answer it, ask. Do not move past Sketch on partial understanding: complete context is what makes a plan hold.

The record proves the artifact, not the world it describes. Reading a document proves the document is right, never that the world matches it: whether code is actually deployed, whether old data still lingers, whether a clause was signed, whether a plan was followed. When a finding's truth depends on the running environment, reading cannot settle it, so it becomes a [probe] endpoint (one live check; the [desk]/[probe] tags are defined under Partition's stopping condition) and stays assumed until that probe runs. Carry this into the output: on repo evidence alone, never report the system as compliant, secure, or "done", only that the artifacts are correct and the runtime questions are named as probes. Full transparency about what is proven versus assumed is what makes the plan valid, not a caveat that weakens it.

Checkpoint before Analyze. Show the human the rough sketch together with the Known / Assumed / Unknown buckets (and, briefly, what you reviewed to ground it) and get a short "looks right" before going deeper. A wrong starting frame is cheapest to fix here, before any analysis is built on top of it.

If no answer can be obtained (the human is away, the run is non-interactive), an unanswered checkpoint or question round does not end the pass. Record verbatim what you would have asked, then keep planning everything the missing answers do not touch: carry low-stakes unknowns as flagged, vetoable assumptions, split a shape-changing unknown into explicit branches (one per plausible answer) where that stays cheap, and leave only what a missing answer genuinely gates as a named open question. Deliver the rest; one open question must not hold the whole plan hostage.

A · Analyze (hybrid)

Interrogate each main step with the Kipling questions (Who, What, When, Where, How, Why) to surface hidden gaps and unspoken assumptions. Produce a findings list of gaps, contradictions, open assumptions, and improvement opportunities, including whether the main steps stand in the right order. This is diagnosis, not yet a decision.

Attack the draft, do not defend it. Actively try to break your own sketch: where would it fail, what did it silently assume, what case does it not cover? A gap you find here is free; a gap the implementation finds costs a whole block of work. Treat a draft that survives a genuine attack as trustworthy, not one you argued in favour of.

Then resolve each open item by severity:

• Low-risk / non-structural: make the most reasonable assumption yourself and flag it visibly in the output (do not silently bury it). Example: a default naming choice, a minor library pick.
• Structure-critical: an unknown whose answer would change the shape of the plan (different main steps, different architecture, different scope). First try to resolve it yourself: structure-critical does not override read-first, so if reading or a cheap probe can answer it, do that. Stop and ask the human only for the structure-critical unknowns that neither reading nor a probe can settle, typically a product decision or an external constraint. Do not guess these; guessing one wrong is exactly the whole-block mistake SAOP exists to prevent.

Ask only the structure-critical questions that reading could not resolve, and ask them together, not one drip at a time. If no answer can be obtained, the continuation rule from the Sketch checkpoint applies here unchanged.

O · Optimize

Decide on every finding. Combine the accepted ones into the best overall variant: choose the arrangement of the main steps so they work best together (global before local, arrange the whole before tuning any part), and tune each part only as far as it serves the whole, never to its isolated maximum. The yardstick is the optimum: the highest-quality result at the least resources (clean, safe, effective), not merely the simplest and not the maximal.

Finding the optimum means knowing the best available approach, not just the first that works. When the choice turns on facts that live outside the model (current providers, prices, versions, standards, benchmarks, law), do not answer from memory: training data is stale and these facts move. Research them live (WebSearch, WebFetch, or a dedicated research subagent), and match the depth to the stakes. A provider or tool choice is not a quick lookup, it is its own SAOP problem: partition the decision into explicit criteria, drawn from the context you understood in Sketch, the domain's load-bearing constraints (legal, residency, security, whatever this project made non-negotiable) plus the usual axes (cost, capability, availability, billing model, lock-in), list the real candidates, and score each candidate against each criterion from sources, not recall. Treat a source as a claim, not a proof: that a page or catalogue says something is not that it holds. For any fact the decision leans on, require a second independent source, or a [probe] that checks it against the primary authority (the provider's own API, the live catalogue, the actual record), and until then carry it as assumed, not settled. When several sources bear on one figure, carry each source's own figure: never present your synthesis of divergent numbers as something the sources agree on; if they disagree, say so and plan around the conservative end. Facts move: for anything that changes over time (a price, a version, a law, an availability), note the as-of date of the source you lean on, prefer the most recent authoritative one, and treat an undated or stale claim as assumed until a live check or a [probe] confirms it still holds. This applies equally to documents inside the project: a README or doc asserting a fact about the world ("the latest version is X", "the limit is Y") is a record of what someone once believed, dated at best to its last edit, not a current fact. Record the candidates you rule out alongside the criterion that disqualified them (a provider with no EU region, a tool that fails a load-bearing constraint, an option priced out of reach): a ruled-out candidate carried with its reason, in the decision log, is not re-evaluated on the next pass, exactly as an abandoned approach is not retried. An optimum picked from memory, or from the first plausible option, is only a local best; the real one is found by going deep, criterion by criterion.

P · Partition

Decompose the optimized plan along its natural boundaries into sub-processes that are non-overlapping and gap-free (a clean partition: each part covers exactly one area, none doubled or forgotten) and as independent as possible (orthogonal: minimal coupling, few clear interfaces, so no part becomes a bottleneck for the others).

Orthogonality has a direct payoff: sub-processes that do not depend on each other can be worked in parallel. When two endpoints are independent, say so, so they can be run at the same time instead of one after the other. Where one endpoint must wait for another, name that dependency explicitly.

Recurse: treat any sub-process still too coarse as its own problem and run Sketch, Analyze, Optimize, and Partition on it again. The human checkpoints fire once per pass, not once per recursion level; inner passes reuse the answers already given.

For a large plan with many main steps, fully partition the steps you will build next, all the way to checkable endpoints; name the remaining steps and give each its own SAOP pass before its work begins. A named but un-partitioned step is a placeholder for a later pass, not an approved endpoint, so do not present it as ready to build.

Unanswered structure-critical unknowns do not cancel the pyramid either: partition the branches they do not affect all the way to checkable endpoints, and mark each affected endpoint as conditional on its open question, so the human sees exactly which answers unlock which work. A pyramid with such marks is still ready for approval; the marks are part of what is approved.

Stopping condition. The seam is the rule: decompose an endpoint no further once it is either

• desk-checkable: determinable at the desk by logic, completeness, freedom from contradiction, or arithmetic (verification: "is it built right?"), or
• a practical probe: validatable by a single, low-cost real-world test (validation: "does it match reality?"). What that test is is field-specific: a test run for code, a register check or a quick call for a legal or logistical question, a look at how a comparable effort actually went for a launch.

Stop exactly when every endpoint is one of these two, not sooner (arbitrary cutoff), not later (endless refinement).

The tag is not the whole test. [desk] and [probe] say how an endpoint is checked, not how big it is. "Confirm the admin port is closed" and "review authorization on every API route" both read as checkable, yet only the first is one unit of work. The binding test is the acceptance criterion: can you state one testable criterion for this endpoint? If it takes a list, it is several endpoints wearing one label, so split it, and "review every route" becomes one endpoint per route group. An oversized endpoint that carries a tag looks finished and is not.

Size is a sanity check on top, not the rule: an endpoint should be workable in one sitting, without its context spilling over. That is about the work per endpoint, never the length of the plan, a big plan made of many small endpoints is exactly right.

Output: the plan pyramid

Return, ready for approval:

1. The pyramid: main steps, each with its recursively partitioned endpoints, every endpoint tagged [desk] or [probe]. State each endpoint as both the goal and the place: what it achieves and the concrete file (or path) it touches, for example "add the OIDC callback route in auth/routes.py", not just "handle the callback". A goal without a file is vague; a file without a goal is a chore. Give both.
2. Flagged assumptions: every assumption the pass still carries, wherever it arose (Sketch, Analyze, or Optimize), listed so the human can veto any.
3. Open questions: only if structure-critical unknowns remain unanswered (otherwise none). An unknown a cheap real-world check could settle is not an open question: it belongs in the pyramid as a [probe] endpoint. Reserve this list for what genuinely only the human can decide.

Each endpoint is one sprint: a focused unit of work (not a multi-week Scrum timebox) with one assignment and one testable acceptance criterion.

Before you hand it back, attack the finished plan, not the sketch. The draft-attack in Analyze tested the sketch; the plan has grown since, above all in Optimize, where live-researched facts entered after the last adversarial pass. Run attack, do not defend over the finished plan: is the partition still gap-free, does each endpoint carry exactly one acceptance criterion, is every reality- or runtime-dependent finding tagged [probe] and marked assumed rather than [desk], is every load-bearing external fact independently cross-checked, and does nothing resurrect a deprecated or superseded artifact? An attack that changes nothing must say what it checked and what it found; a bare "plan looks good" is a skipped attack, not a passed one. Then be honest about the ceiling: a read-only pass cannot itself validate reality, so never present the plan as "verified and validated" wholesale. State the two halves apart, what is desk-verified here and which probes would validate the rest, and flag load-bearing or irreversible claims for an independent verifier rather than self-review.

Where the plan lives. The pass itself writes nothing, it is read-only. On approval, writing the plan file is the first act of implementation. Match the storage to the size, so the plan survives the work without getting in its way:

• Small plan: keep it in the chat. No file needed.
• Medium plan: on approval, write it to a single plan file, so it survives a context reset and can be re-read.
• Large plan: on approval, a master file for the main steps plus one sub-file per main step, so each part can be worked (and re-read) on its own.

The plan is a living record, not a frozen snapshot. Give every endpoint a status (open / in progress / done / dropped) and maintain the file through implementation: mark an endpoint done when its acceptance criterion is met, correct it in place when the approach changes. Keep a decision log at the foot of the plan, one dated line per change, stating what changed and why. Above all, when an endpoint is dropped or an approach abandoned, record why: an abandoned path with its reason is not retried, and the reasoning survives a context reset. Progress and rejected paths both live on disk, so nothing is lost to a new session and no work is repeated. After approval, work each endpoint and check it against its one acceptance criterion; feed what you learn back into this record, so the plan stays true as reality tests it.

Optional: machine-readable endpoints. On request, also emit the endpoints as a structured list so a task tracker (TodoWrite, an issue tracker) can consume them without re-parsing the prose. One object per endpoint:

[
  {
    "id": "3.4",
    "goal": "webhook handler maps provider events to subscription state",
    "file": "billing/webhooks.py",
    "check": "desk",
    "depends_on": ["3.1"],
    "parallel_ok": true
  }
]

parallel_ok means the endpoint can run alongside the other endpoints once its depends_on are met. Keep it alongside the human-readable pyramid, never instead of it.

A fully worked plan pyramid is in reference/example-pyramid.md.