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".
In this repository38 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- Adversarial VerifySkill
- Change ControlSkill
- Code ReconnaissanceSkill
- Correction PropagationSkill
- Debugging PlaybookSkill
- Delegation DisciplineSkill
- Disclosure Is Not A FixSkill
- Discovery LoopSkill
- Divergent IdeationSkill
- Effort CalibrationSkill
- Empirical ValidationSkill
- Error RecoverySkill
- Extract ApproachSkill
- Failure Mode AwarenessSkill
- ForesightSkill
- Frontier Workflow ModeSkill
- Human HandoffSkill
- Intent ClaritySkill
- Leverage FirstSkill
- Live State TruthSkill
- Memory HygieneSkill
- Open MandateSkill
- Output StructuringSkill
- Plan GateSkill
- Proactive RigorSkill
- Product ThinkingSkill
- Prompt EngineeringSkill
- Publish HygieneSkill
- Research MethodologySkill
- Ruthless EditorSkill
- Scope FenceSkill
- Security Pattern ReviewSkill
- Self-Improvement LoopSkill
- Session OrientationSkill
- Structured ReasoningSkill
- Verification DisciplineSkill
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
- Very specific: line 26
Step 1 — State the end goal in one sentence: If you can't, go back to intent-clarity.
- Distinctive: line 55
Step 6 — Identify the smallest useful next step: Not the first stage — the first *action* inside it that produces information or progress.
- Distinctive: line 59
No stage's output is described with the words "understand", "explore", "handle", or "deal with" alone — every output is a noun you could …
≈ “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.
Files
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-gateDepth-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:
- Dependencies: a stage can't precede its inputs.
- 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-gateat Depth 3; each stage then gets its own lightweight plan. live-state-truthresolves the cheap unknowns before they get scheduled as stages.effort-calibrationcaps decomposition depth — critical work earns finer stages.debugging-playbookis 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.
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
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.

