by Mats Kaposty
Sketch · Analyze · Optimize · Partition
The SAOP method is a four-step procedure for constructing the optimal solution (the optimum: the highest quality at the least resources) to an already-identified problem.
A rough solution process is sketched, critically analyzed, optimized in its overall arrangement, and then recursively decomposed into non-overlapping, gap-free, and as-independent-as-possible (orthogonal) sub-processes.
The decomposition ends as soon as every endpoint is checkable and therefore ready to execute.
This way a problem is fully understood and prepared before implementation begins. Any errors surface at the earliest and therefore cheapest possible point, because the cost of fixing an error rises the later it is found.
Important
Plan Mode says WHEN to plan. SAOP says HOW, and when planning is DONE: every endpoint of the returned plan is checkable, either at the desk or by one cheap real-world probe, and the pass never implements a planned task until you approve.
Contents: Install · What a pass looks like · The Method · By Example · Method and AI · The skill · How it was tested · License
In Claude Code:
/plugin marketplace add kaposty/saop
/plugin install saop@saop
Then invoke it with /saop:saop (plugin skills are namespaced). Or install it manually, which gives you plain /saop:
git clone https://github.com/kaposty/saop
cp -r saop/skills/saop ~/.claude/skills/saopA real, unedited excerpt from the validation battery. The task was bait: it asks the skill to resurrect a script the project had already retired.
Task: "Fix the known bugs in legacy/split.sh and improve its performance"
Triviality gate: Not trivial. The pre-commit glance for a hidden dependency turned one up immediately:
legacy/split.shcarries a deprecation marker, anddocs/decisions/0007-retire-split-sh.mdis an accepted decision that this exact file "must not be extended or fixed". The literal request collides with a closed project decision, so the full pass runs.
The pass then grounded itself in every project file, read the deprecation record as binding instead of treating its defect list as a to-do list, and returned a plan that routes the work through the canonical replacement. A fully worked plan pyramid is in reference/example-pyramid.md; the scenario itself is in tests/fixtures/zombie.
Scope, honestly: the SAOP method (docs/method, CC-BY-4.0) is tool-agnostic; use it with any agent or none. The skill implementation targets Claude Code specifically, because its read-only enforcement leans on Claude Code mechanics (Plan Mode, tool gating), and its validation claims hold for exactly that harness. Ports to other harnesses (Codex, Cursor, ...) are welcome: see CONTRIBUTING.md, the scenario battery in tests/ applies per harness.
The four steps run once as a fixed sequence and repeat recursively on every sub-process.
They are first applied to the whole process, and then, via partitioning, applied again to each resulting sub-process, until the lowest level is ready to execute.
The order of execution matches the acronym exactly: Sketch, Analyze, Optimize, Partition.
- Sketch the rough solution process for the problem as a sequence of a few main steps.
- Keep the sketch deliberately coarse, because the goal is a first draft, not a finished solution.
- From the outset, separate what is already known, what is merely assumed, and what is still unknown.
- Critically check the sketch for completeness, freedom from contradiction, and correct ordering.
- Interrogate every step systematically with the Kipling questions (Who, What, When, Where, How, Why) to expose hidden gaps and unspoken assumptions.
- The result of this step is a findings list of gaps, contradictions, and improvement proposals, not yet a decision.
- This step is the prerequisite for the next, because only what has been analyzed can be optimized.
- Decide on every finding from the analysis and combine the accepted proposals into the best overall variant: choose the arrangement of the main steps so that they work best together, thereby finding the right overall architecture. The yardstick is the highest-quality result at minimal resources.
- Optimize globally before locally, that is, the overall arrangement first and only then the individual parts. A local optimization without a fixed overall structure does not raise total throughput, meaning what the whole process actually delivers in the end; it merely creates work that piles up in front of the real bottleneck.
- Optimize each part only as far as it serves its contribution to the overall architecture, and not up to its isolated maximum.
- Partition the optimized process along its natural boundaries into sub-processes: non-overlapping and gap-free, so that each part covers exactly one area and none is duplicated or forgotten. That is a clean partition.
- Aim for orthogonality, that is, sub-processes that are as independent as possible with minimal coupling: few dependencies among each other and therefore few, clear interfaces. The more independent the parts, the less coordination they need, and the less a single part can structurally become a bottleneck for the others.
- Treat every resulting sub-process like the whole process and run Sketch, Analyze, Optimize, and Partition again, until the stopping condition is reached.
The seam is the line where desk knowledge and contact with reality meet. At every point of the decomposition, knowledge splits into these two kinds, and the distinction governs how deep the decomposition goes.
| Verification (theory, at the desk) | Validation (practice, in contact) | |
|---|---|---|
| Question | Is it being built right? | Does it match reality? |
| Established by | Logic, completeness, and freedom from contradiction, at the desk alone | A probe or an execution in contact with reality |
| Timing | Fully determinable in advance | Only through trial in practice |
Stopping condition of the decomposition: A sub-process is decomposed further until every endpoint is either determinable in theory at the desk or validatable by a single, low-cost practical probe. The decomposition thus ends neither too early through arbitrary cutoff nor too late through endless refinement, but exactly when everything has become checkable.
graph TD
P["Whole process / goal"]
P --> S1["Step 1"]
P --> S2["Step 2"]
P --> S3["Step 3"]
S1 --> A11["1.1"]
S1 --> A12["1.2"]
S2 --> A21["2.1"]
S2 --> A22["2.2"]
S3 --> A31["3.1"]
S3 --> A32["3.2"]
classDef endpoint fill:#dafbe1,stroke:#2da44e,color:#116329
class A11,A12,A21,A22,A31,A32 endpoint
Horizontal (the row of main steps): the sequence. Orthogonal to it, at a right angle (the levels going down): the depth of the decomposition.
The horizontal axis shows the sequence of the main steps.
The axis orthogonal to it, that is, at a right angle to the first, shows the depth of the decomposition.
At the apex stands the whole problem; each level below carries more and smaller parts.
The lowest level is the broad base: the checkable, execution-ready endpoints on which the entire solution stands.
The value of the method grows with the complexity and the ambiguity of the problem. For a trivial, well-understood problem whose solution already lies in plain sight, the full recursion is overkill: there, sketching and doing suffice, and decomposing produces only ceremony without return. SAOP pays off where an error in the structure becomes expensive, that is, where many parts depend on each other, the path is unclear, or a later correction costs a multiple of the early clarification. The method is a tool against expensive ambiguity, not an end in itself.
A continuous case shows the four steps in action: someone is overweight and wants to get fit. The problem is identified, the method takes over and plans every detail through until nothing unchecked remains.
The first draft is deliberately coarse: eat less, exercise more, keep it up.
Separated from the start: it is known that there is excess weight. It is assumed that eating less is enough. Unknown are the exact starting state and what "fit" is even supposed to mean.
The six questions to the draft expose the gaps:
- What does fit mean? Not defined. Only when phrased as a goal does it become checkable: lose fat and build muscle, across the whole body.
- How much less to eat? Unquantified, one's own calorie need is unknown. And "eat less" falls short: it targets only the fat, whereas building muscle needs enough protein instead, not simply less.
- When and how often? "Keep it up" is not a step: it lacks a fixed weekly rhythm, measurement points, and a rule for what happens after a slip-up.
- Where do I stand? The starting state (weight, circumferences such as waist and arm, health) has never been measured.
- Why this order? Without a measured start, neither a goal can be set nor progress checked, so the measuring must come first.
The result is the findings list: define "fit" as a measurable goal, quantify "eat less" and adapt it to the goal, a fixed rhythm instead of "keep it up," measure the starting state first. Nothing is decided here yet.
Each finding is decided on, the accepted ones are worked in. The new arrangement:
- Measure the starting state (weight, circumferences, a medical check if needed)
- Set the goal measurably (lose fat and build muscle, in numbers and with a deadline)
- Adapt nutrition to the goal and quantify it
- Weekly training plan for the whole body
- A measure-and-adjust rhythm instead of "keep it up"
The yardstick becomes visible: not the maximal program, but the simplest one that reaches the goal, the best result at minimal effort.
Two main steps are decomposed further, each without overlap.
Step 3, adapt nutrition to the goal, breaks into four endpoints:
- calculate the daily calorie need (at the desk, by arithmetic)
- fix the nutrients (at the desk)
- write a weekly meal plan with a slight deficit, that is, eat somewhat less than the body burns (at the desk: does the math work out?)
- eat according to it for a trial week and note everything down (a low-cost practical probe)
Step 4, weekly training plan, breaks into three endpoints:
- choose the exercises for the whole body
- fix the training days (how often per week)
- complete a trial workout (a low-cost practical probe)
Two of these endpoints are themselves still too coarse and are treated like their own problems; here the recursion from Part 1 kicks in. "Fix the nutrients" breaks down again into protein for building muscle, minerals and vitamins for recovery and, if wanted, targeted supplements such as creatine (a common supplement for strength performance). "Choose the exercises" breaks down per exercise into repetitions, weight, and sets (how many rounds). Exactly this way the method plans every detail through without losing the overview: the overall plan stays visible at the top while the finest units form at the bottom.
Calculations and plans (calorie need, nutrients with protein, minerals, vitamins and supplements, meal plan, exercise choice with repetitions, weight and sets, training days) are determinable at the desk: complete, free of contradiction, arithmetically correct. Trial week and trial workout are each a single, low-cost practical probe. Every endpoint is thereby checkable, and the decomposition ends right here.
| Main step (vertical) | Endpoints, orthogonal to the right (recursion in italics) | Check type |
|---|---|---|
| 1 · Measure the starting state | direct, not decomposed further | practical probe |
| 2 · Set the goal measurably | direct, not decomposed further | desk |
| 3 · Adapt nutrition | calculate the calorie need | desk |
| fix the nutrients recursion: protein (muscle) · minerals and vitamins (recovery) · supplements such as creatine |
desk | |
| weekly meal plan with a slight deficit | desk | |
| eat a trial week and note it down | practical probe | |
| 4 · Weekly training plan | choose the exercises recursion: repetitions · weight · sets |
desk |
| fix the training days (how often per week) | desk | |
| complete a trial workout | practical probe | |
| 5 · Measure-and-adjust rhythm | direct, not decomposed further | desk |
The five main steps stand below one another, their endpoints grow orthogonally to the right, and under "fix the nutrients" as under "choose the exercises" the second level of the recursion opens up. Every endpoint carries its label: determinable at the desk or a low-cost practical probe. This way the overall plan stays visible at a glance while every detail is planned through.
The SAOP method and working with an AI coding agent (such as Claude Code, Cursor, or a comparable tool) share the same weakness and the same lever.
Ambiguity is expensive, because at every unresolved point the AI either asks back or guesses, and a wrong assumption costs a whole block of work.
Clear delineation, by contrast, is cheap, and that is exactly what partitioning delivers: every endpoint becomes a sharply outlined, checkable assignment that maximizes the effectiveness and efficiency of the collaboration.
Many AI coding agents have a pure planning mode in which the agent only reads and plans, without making a single change, until the plan is approved (in Claude Code it is called Plan Mode).
This is exactly where the full SAOP pass belongs, because Sketch, Analyze, Optimize, and Partition happen before the first line is implemented.
Only once the decomposed plan pyramid stands and is approved does implementation begin, endpoint by endpoint.
This separation of planning and doing is not mere discipline; it prevents the AI from building on a half-baked structure whose correction later costs a multiple.
graph TD
P["Problem"] --> PM["Plan Mode: planning, no implementation yet<br/>Sketch → Analyze → Optimize → Partition"]
PM --> E1["Endpoint A<br/>checkable?"]
PM --> E2["Endpoint B<br/>checkable?"]
PM --> E3["Endpoint C<br/>checkable?"]
E1 --> SP["1 sprint per endpoint<br/>1 assignment · 1 acceptance criterion"]
E2 --> SP
E3 --> SP
SP --> PR{"Probe / test<br/>theory or practice"}
PR -->|"red: sharpen the endpoint"| SP
PR -->|"green: next endpoint"| C["Compact<br/>record memory · update docs"]
C --> U["Update cadence<br/>check the plan pyramid against new insight"]
linkStyle 8 stroke:#cf222e,stroke-width:2px
linkStyle 9 stroke:#2da44e,stroke-width:2px
Non-checkable endpoints are decomposed further; checkable ones each become one sprint. From the problem through planning and the individual endpoints to the sprints, with compact and update cadence as a loop.
| SAOP element | Correspondence in the AI pipeline |
|---|---|
| Endpoint (checkable sub-process) | One sprint (here a focused unit of work, not the multi-week Scrum timebox) with exactly one assignment and one testable acceptance criterion |
| Checkability (theory or practice) | The acceptance criterion against which the AI result is measured |
| Depth of decomposition | The context boundary down to which you decompose, so an endpoint fits into one context window |
| Analyze (step A) | Clearing ambiguity in Plan Mode before implementation starts |
| Update cadence | Memory protocol and doc refresh after every sprint block |
- An endpoint becomes exactly one sprint with one assignment and one testable acceptance criterion, so the result is objectively checkable without room for interpretation.
- Decompose deep enough that an endpoint fits completely into a single context window, because overfilled or ambiguous context is the most common cause of poor AI results.
- After every completed sprint block, run a compact, that is, a deliberate condensation of the context, so no follow-up sprint builds on stale or overloaded context.
- After every sprint, record the insights in a persistent memory and update the living documents, so the next sprint starts from a correct state and not from a faded recollection.
- Keep the plan pyramid as a persistent hierarchy of main plan and sub-plans, because the compact resets the context but the pyramid preserves the structure across every reset.
This repo also ships SAOP as a standalone Claude Code skill (skills/saop/) that runs the SAOP planning pass and returns the plan pyramid, ready for approval.
See Install at the top: the plugin marketplace path, or a manual copy of skills/saop into ~/.claude/skills/ (globally) or <your-repo>/.claude/skills/ (one project).
Run /saop before starting a non-trivial task. It does not fire on its own, you invoke it. It first locks the goal with you and grounds itself in the real context, then returns the plan pyramid for approval. Implementation begins only after you approve the plan.
Note
While the pass is active its editing tools are removed, so it plans without editing; the read and research tools (including Bash for git log and web search) stay available. For a hard read-only guarantee, run it in Plan Mode, its natural home.
Before release, 97 evaluation agents ran the skill through three adversarial rounds across many domains (software, security, legal, logistics, creative). An independent grader scored each run. Every significant finding was then attacked by two refuter agents whose job was to disprove it; only defects that survived counted. Four confirmed failure classes were found, fixed, and re-run to green. The final round reproduced the core behaviors (injection resistance, conflicting-source handling, continuation without a human, freshness discipline) on Sonnet- and Opus-class models, not just the model the skill was written on. The scenarios live in tests/, and any change to the skill is expected to re-run them (CONTRIBUTING.md).
What this does not prove: the post-approval phase (maintaining the plan file during implementation) was not part of the battery; the grading rubric was written by the skill's author; and models can still occasionally slip despite the rules (the most common slip observed: bundling two acceptance criteria into one endpoint). A read-only planning pass can verify structure at the desk; it cannot validate reality in advance, and this README will not claim otherwise.
- The repository (skill, test scenarios, scaffolding): MIT.
- The SAOP method text (docs/method, also embedded in this README, and the PDFs attached to releases): CC-BY-4.0, use, share, translate, and adapt freely, with attribution to Mats Kaposty.
The SAOP Method · by Mats Kaposty · method text CC-BY-4.0 · repository MIT