snoodleboot-io Problem Decomposition (Verbose)
Core Patterns
A Worked Decomposition: "Make Search Faster"
A stakeholder asks to make search faster. As stated this cannot be started, finished, or verified. Decomposition is the work of converting it into a tree whose leaves each have an owner, a size, and a number that says when they are done.
Step 1 — Make the root falsifiable.
❌ "Make search faster"
✅ "p95 latency of GET /search for authenticated users drops from
3.2s to under 800ms, without reducing result relevance
(measured by click-through at position 1-3)."
The negative constraint matters as much as the target. Without it, the fastest search is one that returns nothing, and someone will eventually optimize toward exactly that.
Step 2 — Spike before splitting. Do not decompose a performance problem along guessed lines. One day of measurement:
p95 = 3.2s, decomposed by span:
app handler 210ms ( 7%)
database query 2600ms (81%)
serialization 180ms ( 6%)
network/TLS 210ms ( 7%)
This single measurement kills three plausible workstreams. "Move rendering to the client" has a ceiling of 180ms against a 2,400ms gap — it cannot succeed even if executed perfectly. Amdahl's law is the sharpest decomposition tool available: compute each branch's ceiling before staffing it.
Step 3 — The tree.
ROOT: p95 /search < 800ms, CTR@1-3 not down more than 2%
│
├── B. Database query: 2600ms → under 500ms [ceiling: 2.6s ✔]
│ ├── B1. Add GIN trigram index on search_index.title
│ │ Done when: EXPLAIN ANALYZE shows Bitmap Index Scan,
│ │ not Seq Scan, and query p95 < 400ms
│ │ Size: half a day. Risk: index build locks writes → use
│ │ CREATE INDEX CONCURRENTLY
│ ├── B2. Bound the result set
│ │ Now: unbounded; p99 request materializes ~40k rows
│ │ Done when: keyset pagination, LIMIT 50, rows fetched < 100
│ │ Size: 2 days. Depends on B1 (ordering must be index-backed)
│ └── B3. Cache facet counts
│ Done when: facet computation < 20ms p95 at 5-min TTL
│ Precondition to verify: facet values change < 1/5min
│
├── C. Serialization: 180ms [ceiling: 180ms — defer]
├── D. Network: 210ms [ceiling: 210ms — defer]
└── A. App handler: 210ms [ceiling: 210ms — defer]
Deferring C, D, and A is not laziness; it is the decomposition doing its job. Solving B alone reaches roughly 3.2s − 2.1s = 1.1s… which still misses the 800ms target. That is worth knowing now: the tree tells you B is necessary but not sufficient, and that C+D+A must eventually yield ~300ms combined. A decomposition that cannot tell you this is not earning its keep.
Work Backwards From the Output
Forward decomposition ("first we need a database, then…") reliably produces work that turns out to be unnecessary. Backward decomposition starts from the artifact and asks what must exist immediately prior.
The user sees: 50 ranked results in under 800ms
← a scored, ordered candidate set
← a retrieved candidate set (recall step)
← an index queryable by term
← a normalized document corpus
Each arrow is a candidate boundary, and each node has an obvious "is it right?" test independent of the ones below it. You can validate ranking quality against a hand-built candidate set before the index exists.
Find the Seam
The test of a proposed split is whether you can write down what crosses the boundary. If you can name the type, it is a seam; if you can only gesture at "the search stuff", it is a wish.
✅ Seam — writeable as a contract:
def retrieve(query: str, limit: int) -> list[DocId]
def score(query: str, docs: list[DocId]) -> list[ScoredDoc]
Two engineers can now work in parallel against a stub. The scoring
engineer builds against a hardcoded DocId list on day one.
❌ Not a seam:
"You take the backend performance, I'll take the frontend performance"
Both need the same latency budget negotiated, both change the same
response payload shape, and neither can verify their half alone.
Vertical Slices Over Horizontal Layers
The most common decomposition failure is splitting by architectural layer, because the layers are the most visible lines on the whiteboard.
❌ Horizontal
Sprint 1: all schema migrations
Sprint 2: all repository + service code
Sprint 3: all API endpoints and UI
→ Nothing is demonstrable until sprint 3. Every wrong assumption
made in sprint 1 is discovered in sprint 3, at maximum rework cost.
✅ Vertical
Slice 1: single-field search, no facets, no paging, 10 hardcoded
docs, real path through DB → service → endpoint → UI
Slice 2: real index, still no facets
Slice 3: paging
Slice 4: facets
→ Integration risk is retired on day 3. Slices 3 and 4 can be cut
entirely if the metric is already met.
The vertical slice is deliberately embarrassing in scope. That is the point: it
proves the path, not the product. See incremental-implementation for carrying
slices into code.
Spike the Unknown First
Sequence by uncertainty, not by dependency order and not by what is easy to start. The purpose of ordering is to buy information as cheaply as possible.
A well-formed spike states a question, a timebox, and what each answer implies:
Question: Can Postgres trigram search return p95 < 400ms at 12M rows
on our current instance class?
Timebox: 2 days
If yes: B1 proceeds; the tree above holds.
If no: the whole B branch is replaced by "introduce a search engine",
which is a 6-week project, not a 3-day one — and we need to
know that before committing to the quarter.
Note the asymmetry: the spike costs 2 days and can save 6 weeks of misdirected work. Spikes that cannot change the plan are not spikes, they are early implementation.
"What Would Have To Be True?"
Given a plan, enumerate the conditions required for it to work, then test the cheapest and shakiest condition first. This finds fatal flaws before they are expensive.
Plan: cache facet counts for 5 minutes (B3)
What would have to be true?
1. Facet values change less than ~once per 5 min
→ check the write rate: 10-minute query. THIS FIRST.
2. Stale facet counts are acceptable to users
→ one question to product
3. Cache memory fits the facet cardinality
→ back-of-envelope: 200 facets × 8KB = 1.6MB. Fine.
Condition 1 turned out false — inventory writes ~40/min during
business hours. B3 is dropped for 30 minutes of investigation
instead of a week of implementation.
Detecting Hidden Dependencies Between "Independent" Parts
Parallel sub-problems are the payoff of decomposition, and false independence is the way that payoff evaporates. Two branches assigned to two people are only independent if all of these hold:
| Check | Question | Failure smell |
|---|---|---|
| Data | Do both write the same table or key? | "We'll just merge the migrations" |
| Schema | Does either change a shared type or contract? | Both edit the same response model |
| Order | Does one need the other's output to test? | "I'll verify once yours lands" |
| Resource | Do both consume the same budget (latency, memory, quota)? | Two 300ms budgets, one 400ms allowance |
| Deploy | Must they ship together to be correct? | A flag that must flip for both at once |
The latency-budget case is the one teams miss most often, because it looks like a resource conflict rather than a code conflict. In the worked example, B2 and B3 both consume the same 500ms query budget. Solved separately and measured separately, each looks successful; combined they can still miss. The fix is to assign explicit sub-budgets up front — B1+B2 ≤ 400ms, B3 ≤ 20ms — and make each leaf's done condition its own budget, not the global target.
For decomposing a failure rather than a goal, use root-cause-five-whys;
for turning a decomposition into scoped tickets, use feature-planning.
Common Anti-Patterns
❌ Decomposing before measuring — the tree is built on guesses about where time or complexity lives, and its branches have no ceilings. ✅ Spend one day measuring first. Compute each branch's maximum possible contribution before staffing it.
❌ Sub-problems with no done condition — "improve the query layer", "clean up search." ✅ Every leaf names a measurement: "EXPLAIN shows Index Scan and query p95 < 400ms."
❌ Splitting by layer — schemas this sprint, services next, UI after. ✅ Cut vertical slices that go end to end, however narrow.
❌ Assuming independence because two people were assigned — both branches land, both pass their own tests, and the integration misses the target. ✅ Run the five-way check (data, schema, order, resource, deploy). Assign explicit sub-budgets for shared resources.
❌ Uniform decomposition depth — every branch expanded to the same level of detail regardless of risk. ✅ Expand the uncertain and expensive branches deeply; leave known-cheap ones as single leaves.
❌ A one-level list called a decomposition — five bullet points with no structure or dependency. ✅ If nothing has children and nothing has a ceiling, you have a to-do list.
❌ Spikes that become the implementation — the timebox passes silently and the prototype ships. ✅ State the timebox and both branch outcomes before starting. Delete the spike code.
❌ Optimizing a branch with a ceiling below the target — six weeks moving a 180ms component against a 2,400ms gap. ✅ Check the ceiling first. A branch that cannot succeed at 100% is not a branch.
Decomposition Checklist
- Root restated with a metric, a baseline, and a target number
- Negative constraint recorded (what must not get worse)
- Measurement or spike completed before the tree was built
- Each branch has a computed ceiling; branches below target are dropped
- Each leaf has a done condition containing a number
- Each leaf is small enough to finish in about a day
- Boundaries are seams — the crossing type is written down
- Slices are vertical; at least one goes end to end early
- Highest-uncertainty item is sequenced first and timeboxed
- "What would have to be true" answered for the shakiest assumption
- Parallel branches checked for shared data, schema, ordering, budget, deploy
- Shared resource budgets split explicitly per leaf