Deep Decomposition

Deep Decomposition

Purpose

Turn one intractable task into a sequence of tractable ones. A task is decomposed well when every unit is small enough that you could start it right now and know when it's done — and the units are ordered so that the riskiest unknowns get resolved earliest, not discovered last.

When to use this skill

• A plan-gate Depth-3 task: you can't hold the whole solution in one plan.
• The task spans multiple domains (e.g., schema + API + UI; or research + analysis + writeup).
• You catch yourself writing vague plan steps ("handle the edge cases", "do the integration").
• Research or strategy questions that are really 4–6 questions wearing a trenchcoat.

When NOT to use this skill

• The task fits in a Depth-1 or Depth-2 plan. Decomposing it is procrastination with extra steps.
• The user asked for a quick draft or first pass — decomposition depth should follow effort-calibration, not habit.

Operating procedure

Step 1 — State the end goal in one sentence. If you can't, go back to intent-clarity.

Step 2 — Inventory knowns and unknowns.

• Knowns: what you already have (files, facts, requirements, prior art).
• Unknowns: what you'd have to discover. Mark each unknown cheap (one command/read away) or expensive (needs experimentation or user input).
• Map the domain's dimensionality before building for its first cell. If the task

targets a space (markets, entities, file types, locales, plans), enumerate its axes from the source of truth — an API, a listing, a schema — not from assumption; it is usually one cheap query. Then build the general case (dynamic discovery, config-driven values) rather than hardcoding the first slice. Tell: a hardcoded enumeration (ITEMS = [4 things], a fixed column list) where the real set is queryable and growing. Real case (2026-07-11): a dashboard was built for one entity × one dimension and re-scoped three times by the user; the full entity × dimension × type matrix was enumerable from the platform's API in two calls.

Step 3 — Cut the task into stages. Each stage must have:

• A concrete output (a working function, an answered question, a drafted section) — not an activity ("investigate", "think about").
• A done-check: how you'll know the stage is complete.

Step 4 — Order the stages. Two forces, in priority order:

1. Dependencies: a stage can't precede its inputs.
2. Risk-first: among independent stages, do the one most likely to invalidate the others. Resolve expensive unknowns and bottlenecks early — a bottleneck discovered at stage 5 wastes stages 1–4.

Step 5 — Fill the table:

| # | Stage | Output | Depends on | Unknowns | Risk if wrong | |---|---|---|---|---|---| | 1 | ... | ... | — | ... | ... |

Step 6 — Identify the smallest useful next step. Not the first stage — the first action inside it that produces information or progress. "Read the current auth middleware" beats "Stage 1: understand auth." Then start it.

Quality bar

• No stage's output is described with the words "understand", "explore", "handle", or "deal with" alone — every output is a noun you could point at.
• The riskiest assumption in the whole task is tested by stage 1 or 2, not stage N.
• Any stage estimated at more than ~5 substeps gets decomposed again.

Common failure modes

• Activity-shaped stages: "research the options" with no defined output. Fix: "a table of 3 options with tradeoffs" is an output.
• Happy-path ordering: doing easy stages first for momentum, leaving the make-or-break unknown for last.
• Decomposition as the deliverable: producing a beautiful breakdown and never starting stage 1. Step 6 exists to prevent this — always end decomposition by doing the smallest next step.
• Ignoring cross-stage contracts: stages that each work alone but disagree on interfaces (data shapes, terminology, assumptions). Write the contract down at the boundary.

Example

Task: "Build a CLI tool that syncs bookmarks between two browsers."

| # | Stage | Output | Depends on | Unknowns | Risk if wrong | |---|---|---|---|---|---| | 1 | Read both bookmark storage formats | Documented file paths + formats for both browsers | — | Are formats stable/accessible while browser runs? (expensive) | Whole approach invalid | | 2 | One-way read prototype | Script that dumps browser A's bookmarks as JSON | 1 | — | Low | | 3 | Diff/merge model | Written rule set for conflicts (adds, deletes, moves) | 1 | User's conflict preference (cheap: ask) | Rework of stage 4 | | 4 | Two-way sync core | Function passing round-trip tests | 2, 3 | — | Medium | | 5 | CLI wrapper + docs | Installable command with --dry-run | 4 | — | Low |

Smallest useful next step: locate browser A's bookmarks file and confirm it's readable while the browser is open — the expensive unknown, tested first.

Works with sibling skills

• Invoked by plan-gate at Depth 3; each stage then gets its own lightweight plan.
• live-state-truth resolves the cheap unknowns before they get scheduled as stages.
• effort-calibration caps decomposition depth — critical work earns finer stages.
• debugging-playbook is the specialized decomposition for "why is this broken" tasks; use it instead when the task is a bug.

Provenance and maintenance

Written 2026-07 as part of a portable, project-agnostic quality pack. No repo-specific claims. Re-verify by testing on a real task: if stages come out activity-shaped or the table feels like overhead for your typical task size, tighten the "When NOT to use" thresholds. Keep the example generic or swap in a completed real decomposition from your own history.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ralfyishere
• Source: ralfyishere/rules-with-receipts
• License: MIT

Install and usage instructions live in the source repository linked above.