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