agentleFS
ralfyishereralfyishere/rules-with-receipts/.claude/skills/deep-decomposition/SKILL.md

Deep Decomposition

Skill2 starsChanged 4 months agoMITView on GitHub

Break hard tasks into smaller solvable units with explicit dependencies and unknowns. Activate when a task feels too big to plan in one pass — large features, migrations, research questions with many sub-questions, multi-part documents, business analyses, gnarly debugging with several possible fault lines, or anything where the honest answer to "what's step 4?" is "no idea yet". Trigger signals: the user asks for something "end to end", "the whole thing", a system rather than a change, or you notice your plan has steps like "figure out the rest".

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

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

    line 26
  2. Distinctive:

    Step 6 — Identify the smallest useful next step: Not the first stage — the first *action* inside it that produces information or progress.

    line 55
  3. Distinctive:

    No stage's output is described with the words "understand", "explore", "handle", or "deal with" alone — every output is a noun you could …

    line 59

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

#StageOutputDepends onUnknownsRisk 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."

#StageOutputDepends onUnknownsRisk if wrong
1Read both bookmark storage formatsDocumented file paths + formats for both browsers—Are formats stable/accessible while browser runs? (expensive)Whole approach invalid
2One-way read prototypeScript that dumps browser A's bookmarks as JSON1—Low
3Diff/merge modelWritten rule set for conflicts (adds, deletes, moves)1User's conflict preference (cheap: ask)Rework of stage 4
4Two-way sync coreFunction passing round-trip tests2, 3—Medium
5CLI wrapper + docsInstallable command with --dry-run4—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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.