Problem Decomposer

/problem-decomposer — Aspiration → dispatchable lattice

Take an aspiration ("ship a platform, not a collection of repos"), descend it through the 5-whys until each branch reaches leaves that satisfy the 7 dispatchability properties (see DISPATCHABILITY.md), and emit a structured problem-statement doc + bead specs + non-leaves queue.

Arguments

$ARGUMENTS

• <aspiration-slug> — short kebab-case identifier for the aspiration (e.g. substrate-idl, cross-repo-coordination, q3-platform-launch). Becomes the output filename.
• --input=PATH (optional) — path to a doc describing the aspiration + relevant context. If omitted, the skill prompts the user (or the orchestrator) for the aspiration text inline.
• --output-dir=PATH (default: docs/problems/) — where the decomposition doc and bead specs go.
• --audit=PATH (optional) — instead of decomposing a new aspiration, audit an existing doc (or bead backlog) for orphan-dispatchable items. See "Audit mode" below.

Modes

Decompose mode (default)

Take a new aspiration → produce a fresh lattice doc + bead specs.

Audit mode (--audit=PATH)

Take an existing decomposition doc, ADR, or bead backlog → check each leaf against the 7 dispatchability properties + the 5-whys chain. Emit a report listing:

• Leaves that pass all 7 (good)
• Leaves that fail one or more (with which property and why)
• Leaves whose "why?" chain doesn't reach a real aspiration (orphans — candidates for kill or re-parent)
• Non-leaves still in the queue (real work, not yet ready)

What this skill solves

Most decompositions hit one of three failure modes:

1. Too shallow — the breakdown stops at requirements like "design the system" or "improve UX" that aren't actually dispatchable. Agents pick them up, stall, give up.
2. Too unrooted — leaves are concrete but the "why?" chain dead-ends at "because I noticed it." Agent budget burns on work that doesn't compound into a coherent platform.
3. Tree-shaped, not lattice-shaped — work that serves multiple goals gets duplicated (with drift) or shoehorned under one arbitrary parent. The cross-cutting structure is lost.

This skill enforces:

• Descent until dispatchable — every leaf passes all 7 properties from DISPATCHABILITY.md. Anything that doesn't is honestly classified as a non-leaf in the queue.
• Rooted via 5-whys — every leaf has a complete chain to a real aspiration. Orphans are flagged at write-time, not at execution-time.
• Lattice, not tree — leaves can have multiple parents. The doc and the Mermaid graph render this directly.

Hard rules (non-negotiable)

1. Every leaf must pass all 7 dispatchability properties. Score them explicitly in the leaf's spec section. If even one fails, the node is not a leaf — push it to the Non-leaves queue with the failing property named.
2. Every leaf must root to the aspiration via ≤5 whys. If the chain takes more than 5 steps, you've smushed multiple layers — split the requirement.
3. No invented work. Every leaf's problem statement, acceptance criteria, and inputs must trace to real files / repos / specs / ADRs / beads that exist (verifiable via Read / Glob / Grep). Don't fabricate file paths or APIs.
4. Mark [unverified] rather than invent. If you propose a leaf that should touch a specific file but you couldn't confirm the file exists, mark the leaf [unverified] and surface it in the report.
5. Honor the lattice. When a leaf serves multiple parent requirements, give it multiple parents in the lattice table and the Mermaid graph. Don't pick one arbitrarily and lose the cross-cutting signal.
6. The Non-leaves queue is not a punt. Each entry must name (a) what dispatchability property fails today, and (b) what would unblock it. "Needs more thought" is not a valid answer — restate the work or kill it.
7. Refuse on missing TEMPLATE / DISPATCHABILITY. If either is missing from this skill's directory, refuse. The shape is the value.

Workflow

Phase 0 — Validate

1. Resolve --output-dir= (default docs/problems/). Create if missing.
2. Read ${CLAUDE_SKILL_DIR}/TEMPLATE.md and ${CLAUDE_SKILL_DIR}/DISPATCHABILITY.md. Refuse if either is missing or has had its H2 headers renamed.
3. If --audit=PATH, jump to "Audit mode workflow" below. Otherwise:
4. Acquire the aspiration text. If --input=PATH, read it. Otherwise, the aspiration was provided in $ARGUMENTS or the invocation context.
5. Validate the aspiration's shape: it must describe a state of the world (not a deliverable, not a constraint). If the aspiration is anti-shaped (e.g., "migrate to X"), refuse and restate: "That's a means, not an end. What state of the world does migrating to X produce?"

Phase 1 — Surface candidate requirements

Read context broadly to identify what requirements descend from the aspiration:

• The aspiration text itself
• ADRs and design docs in the relevant repo (docs/adr/, docs/plans/)
• Existing CLAUDE.md / README / ARCHITECTURE.md
• Prior decomposition docs in <output-dir>/ (so this one composes with existing work)
• Optionally: prior-art-cartographer output in docs/prior-art/ (decisions about adopt/borrow/skip become requirement constraints)

Produce a flat list of candidate requirements — one line each, no hierarchy yet.

Phase 2 — 5-Whys upward check

For each candidate requirement, walk up the why-chain by asking "why is this required?" Continue until you reach the aspiration or hit a dead-end.

• ≤5 steps to aspiration → requirement is rooted, keep it.
• Dead-end / "because I want to" → requirement is orphan, drop it.
• More than 5 steps → you've collapsed multiple layers; split.

This phase is the filter — drops orphan candidates before they pollute the lattice.

Phase 3 — Build the requirement lattice

Arrange surviving requirements into a DAG:

• Top: the aspiration (one node).
• Bottom: candidates for dispatchable leaves (one per requirement-with-acceptance-criteria).
• Middle: intermediate requirements that need their own children.

Allow multiple parents per node. The lattice may be a chain in trivial cases or a wide DAG in real ones. Don't force a tree shape.

Phase 4 — Descend until dispatchable

For each candidate leaf, run it through the 7-property checklist in DISPATCHABILITY.md:

1. Self-contained problem statement
2. Falsifiable acceptance criteria
3. Enumerable inputs
4. Shape-predictable output
5. Bounded scope
6. Observable failure
7. Realistic time-box

• All 7 pass: it's a dispatchable leaf. Write its bead spec section in the output doc.
• One or more fail: it's not yet a leaf. Either decompose it further (one more level of children, then re-check), or push to the Non-leaves queue with the failing property named.

Don't force. If a node genuinely isn't dispatchable today (e.g., "design the substrate-IDL trait library" — output shape unknowable until you start), don't shoehorn it into dispatchable shape. Honest non-leaf > performative leaf.

Phase 5 — Emit the doc

Write <output-dir>/<aspiration-slug>.md following ${CLAUDE_SKILL_DIR}/TEMPLATE.md exactly:

• Aspiration — one paragraph.
• 5-Whys descent — one chain per major branch.
• Requirement lattice — table of intermediate nodes with parents/children.
• Dispatchable leaves — one full bead spec per leaf.
• Non-leaves queue — table of real-but-not-yet-dispatchable items + what would unblock.
• Lattice (Mermaid) — rendered DAG. Color aspiration / requirement / leaf differently.
• Action items — short list (file leaves; track non-leaves; refresh after first batch ships).
• Cross-references — related ADRs, beads, prior-art entries, sibling decompositions.

Phase 6 — Report

Output a concise summary (≤300 words):

• Aspiration restated in one line
• Lattice shape (N requirements, M leaves, K non-leaves)
• The 3 leaves most likely to compound (i.e., parents of multiple downstream requirements)
• Anything you couldn't verify ([unverified] count + why)
• Suggested next move: "file these leaves via rosary:note" / "review the lattice with a human before filing" / "this aspiration is malformed, restate"

Audit mode workflow

When --audit=PATH is set, the workflow shifts:

1. Read the target doc / bead-export.
2. For each leaf / bead in the input, score against the 7 dispatchability properties.
3. For each leaf, walk its "why?" chain (from problem statement / labels / parent links) to check rootedness.
4. Classify each as:
   • Rooted-dispatchable (all 7 pass + chain reaches aspiration)
   • Orphan-dispatchable (all 7 pass + chain dead-ends → kill candidate)
   • Non-dispatchable (one or more properties fail → either decompose or restate)
5. Emit an audit report at <output-dir>/audit-<source>-<date>.md with the classification table + suggested actions per item.

Audit mode is read-only — never modifies the source. Output is a recommendation document.

What you don't do

• Don't file beads directly. Output is a doc + bead specs. The user (or rosary:note as a follow-up) does the actual filing.
• Don't invent work. Every leaf must trace to real files / repos. Use Read / Glob / Grep to verify before proposing.
• Don't shoehorn non-leaves into leaf shape. Honest non-leaves > performative leaves.
• Don't compare against external systems. That's prior-art-cartographer's job. This skill consumes prior-art decisions as constraints; doesn't redo the analysis.
• Don't run more than one aspiration per invocation. Multiple aspirations interact in non-obvious ways; do them in sequence, not parallel.

Refusal conditions

Examples

/problem-decomposer substrate-idl
→ Prompt for aspiration text; produce docs/problems/substrate-idl.md

/problem-decomposer cross-repo-coordination --input=docs/specs/substrate-idl.md
→ Read input doc, decompose into docs/problems/cross-repo-coordination.md

/problem-decomposer audit-q3-backlog --audit=docs/beads/q3-export.md
→ Audit mode; produce docs/problems/audit-q3-backlog-<date>.md

/problem-decomposer
→ Refuse: "Pass an aspiration slug + text."

Supporting files in this skill

• TEMPLATE.md — the canonical problem-decomposition doc shape
• DISPATCHABILITY.md — the 7-property checklist (standalone-usable)
• examples/substrate-idl.md — worked example: descend "ship art-substrate as a platform" into bead specs

Mailbox

If a dispatch surfaces meta-level surprises (the dispatchability rubric needs an 8th property, the 5-why limit is wrong for your domain, the Mermaid lattice doesn't render certain shapes), append a structured block to <output-dir>/_clarifications.md:

## YYYY-MM-DD — <slug> — <subject>

- **Surface:** SKILL.md | TEMPLATE.md | DISPATCHABILITY.md | this-doc
- **Surprise:** one paragraph
- **Proposed fix:** one paragraph
- **Severity:** low | medium | high

The orchestrator processes between runs. Same pattern as prior-art-cartographer.

Style notes

• Be terse. Each leaf's spec is ~10-15 lines. Long prose belongs in the linked ADR, not in the bead spec.
• Be specific. Acceptance criteria must be falsifiable. Inputs must be enumerable. Don't hand-wave.
• Be honest about non-leaves. A clear "this is not yet dispatchable because property #4 fails" is more useful than a fake leaf.
• Be reproducible. Two runs on the same aspiration with the same context should produce nearly-identical lattices (modulo lattice-isomorphism — the structure should match even if leaf order differs).