problem-decomposer

name	problem-decomposer
description	Decompose an aspiration into a lattice of dispatchable bead specs using 5-whys descent + a 7-property dispatchability rubric. Outputs a problem-statement doc (matching TEMPLATE.md), a list of bead specs ready to file via rosary:note, and an honest queue of non-leaves that need further design. Use when starting a new platform / capability / migration / refactor where work needs to be broken down before agents can ship it. Use also to audit an existing backlog for orphan-dispatchable beads that don't trace to a real aspiration.
allowed-tools	Read Write Edit Glob Grep Bash(ls *) Bash(date *) Bash(rg *)
argument-hint	<aspiration-slug> [--input=PATH] [--output-dir=PATH] [--audit=PATH]

/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

Condition	Refuse with
Aspiration is anti-shaped (a deliverable / a constraint / a means)	"That's not an aspiration. . Restate as a state of the world."
TEMPLATE.md or DISPATCHABILITY.md missing	"Skill scaffolding missing; the shape is the value. Restore the files."
Output dir contains a doc with the same slug less than 7 days old	"A decomposition for this slug exists at , dated . Refresh that one instead of overwriting."
User asks for opinion prose	"I emit structured docs, not essays. The decisions are in each leaf's spec; the lattice is in the Mermaid graph."
Asked to decompose without an aspiration text	"Give me the aspiration first. One paragraph describing the state of the world we want to be true. If you don't have one, that's the work — write it before decomposing."

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).