Canonical: https://decompose.aunysillyme.dev/docs/how-it-works/

From [README.md](https://github.com/aunysillyme-dev/aunx-decompose/blob/b46c48d5e00610aab09ae2f611b65ed718be8413/README.md) · [b46c48d](https://github.com/aunysillyme-dev/aunx-decompose/tree/b46c48d5e00610aab09ae2f611b65ed718be8413) · Built 2026-11-17

# How it works

Split the ask into numbered clauses and tag every unit with the clauses it serves. A clause with no unit is flagged.

Break the job into the smallest units, each with its own inputs, outputs and verifier. N similar items become N units.

Give each unit one of 14 types (coding, reasoning, research, writing, four creative types, design, vision, review, data, agentic, cyber) and one of 3 speeds (fast, standard, frontier).

Draw only real data edges: a unit depends on another only when it reads that unit's output. False and missing edges are rejected. Checks that can kill the plan run first.

Build parallel waves, count how many units read each output, and raise importance with that count.

Choose a dispatch shape per group: one call per unit, an agent's own subagents, a bulk prompt fan-out, an agent fan-out, or split worktrees for disjoint writes. The thresholds are tunable defaults.

Send big or serial maps to an advisor review before any picks, and apply its patch (split, cut edges, re-tier, change the shape or the needs) all or nothing.

Pick a model and a machine per unit with a written method: type first, then speed, family spread within a wave, context as a scored key, effort set apart from tier, and the smallest machine that fits.

Print one plan table with the waves, the critical path and clause coverage.

## Unit map example

From the root of this repository:



```
python3 skills/decompose/scripts/decompose.py --plan skills/decompose/examples/plan.json
```


The bundled map compares three CSV libraries on speed and license, then recommends one. Actual output, exit 0 (table trimmed to four rows):



```
PLAN valid

Advisor review: REQUIRED before picks (S1 read by 3 units)

| unit | parent | clause | type x speed | wave | group | shape | model | machine | runner-up |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| S1 (invalidator) | - | C1 | data x fast | 0 | W0 | single | - | - | - |
| S3.1 | S3 | C2 | research x fast | 0 | W0 | single | - | - | - |
| S2.1 | S2 | C1 | coding x standard | 1 | W1 | single | - | - | - |
| S4 | - | C3 | writing x standard | 2 | - | single | - | - | - |

Waves:
  W0: S1, S3.1, S3.2, S3.3
  W1: S2.1, S2.2, S2.3
  W2: S4
Critical path (minutes): S1 -> S2.3 -> S4, length 11
Serial estimate: 29 minutes. Both figures come from the units' own needs.minutes.
Clause coverage:
  C1 (compare on speed): S1, S2.1, S2.2, S2.3
  C2 (compare on license): S3.1, S3.2, S3.3
  C3 (recommend one): S4
```


The advisor gate fired because S1 is read by three units. The bundled `patch.json` is a sample review: it splits S4 into a draft and a citation check. Apply it with `--apply-patch skills/decompose/examples/patch.json`. Add `--json` for machine-readable output. The model, machine and runner-up columns stay empty until you pick them by the method in [references/picking.md](https://github.com/aunysillyme-dev/aunx-decompose/blob/main/skills/decompose/references/picking.md).

Unit map exit codes: `0` valid, `2` every error listed, including unknown types or speeds, clause gaps, false or missing edges, cycles, substeps more than one level deep, and overlapping writes between units that could run at the same time. Dispatch and gate thresholds live under `plan_defaults` in the bundled `recipes.json`; override any of them in your own recipe store.

## The full method

The skill file holds every step the agent follows, with the dispatch table and the plan schema.

[Read the full method in SKILL.md](https://github.com/aunysillyme-dev/aunx-decompose/blob/main/skills/decompose/SKILL.md)

## Model and machine picks

The helper never picks or calls a model or a machine. Picking is a written method for the agent.

[Read the picking method](https://github.com/aunysillyme-dev/aunx-decompose/blob/main/skills/decompose/references/picking.md)

## Current recipe defaults



```
{
  "advisor_max_steps": 5,
  "advisor_min_units": 12,
  "advisor_serial_min_steps": 4,
  "advisor_serial_ratio": 0.75,
  "advisor_min_readers": 3,
  "high_importance_readers": 3,
  "agent_fanout_min": 10,
  "bulk_prompt_min": 2,
  "subagents_min": 4
}
```


