decompose-spec

name	decompose-spec
description	Turn a design spec into an explicit tx task graph with `tx decompose`, then refine the graph using normal tx task and dependency primitives.
argument-hint	<design-doc-ref> [--parent <task-id>] [--runtime <auto|claude|codex>] [--dry-run]

Decompose Spec

Use this skill when the user already has a design spec and wants an explicit tx task graph created from that spec.

Default Path

1. Confirm the source doc is a design spec.

tx doc show <design-doc-ref>

2. Preview the decomposition before writing if the graph shape is still being discussed.

tx decompose <design-doc-ref> --dry-run --json

3. Materialize the graph once the plan looks right.

tx decompose <design-doc-ref>
tx decompose <design-doc-ref> --runtime claude
tx decompose <design-doc-ref> --runtime codex
tx decompose <design-doc-ref> --parent <task-id>

Rules

• Prefer tx decompose over manually creating a large first-pass task graph.
• Use --parent <task-id> when the spec should decompose under an existing task.
• Use --dry-run when you need to inspect or compare graph options before writes.
• Do NOT use --max-tasks unless the user explicitly requests a cap. Artificial limits produce weak decompositions that miss important slices. Let the LLM produce as many tasks as the design doc warrants.
• Be patient. tx decompose makes LLM calls and can take 60–120 seconds. If you launched it, wait for it to finish. Never re-run it because output appears empty — that wastes API credits and risks duplicate subtasks. If it was launched in the background, poll the output file at long intervals (30s+).
• After materialization, tx remains canonical. Refine the graph with:

tx add "Follow-up task"
tx add "Nested subtask" --parent <task-id>
tx dep block <task-id> <blocker-id>
tx dep unblock <task-id> <blocker-id>
tx doc attach <task-id> <doc-name>
tx update <task-id> --status blocked

• If the design doc changes materially, re-run tx decompose --dry-run first and repair the existing graph explicitly instead of creating duplicate work.

Practical Guidance

• Start from a stable design doc, not a vague request or partial note.
• Use tx show <task-id> on the generated root task to inspect linked-doc and blocker state after decomposition.
• If the result has too many tasks, refine by merging or removing tasks after the fact — do not pre-cap with --max-tasks.

Equivalent Surfaces

• REST API: POST /api/decompose
• MCP: tx_decompose
• Agent SDK:

await tx.decompose.run({
  docRef: "<design-doc-ref>",
  runtime: "auto",
  dryRun: true,
})