---
name: work-decompose
description: Use when an approved PRD must be broken into an epic with story and task files under docs/work/. Triggers — the user asks to decompose a PRD, invokes /work-decompose, or wants a PRD turned into the work tree.
---

# work-decompose

Decompose an `approved` PRD into an epic + story files under `docs/work/epics/`, by dispatching a **decomposer sub-agent** whose role is defined by the existing Sandcastle prompt.

This is the in-session, skill form of `pnpm work decompose --execute`. It adds a path; it changes nothing about `.sandcastle/` or `pnpm work`.

## Single source of truth — do not copy the prompt

The decomposer's role is defined in **`.sandcastle/decomposer.prompt.md`** — the same file `pnpm work decompose --execute` consumes. This skill **reads that file at dispatch time and passes it verbatim**. Never paraphrase, summarise, or inline it here. If this skill and the prompt ever disagree, **the prompt wins** — fix this skill, not the prompt.

## Process

1. **Resolve the PRD.** The user names a PRD (slug or path); otherwise list `docs/work/prds/*.prd.md` and ask which. Read the file.

2. **Refuse drafts.** If the PRD's frontmatter `status:` is not `approved`, **stop** — tell the user to flip it after review. The decomposer refuses drafts; catch it early.

3. **Build the prompt.** Read `.sandcastle/decomposer.prompt.md`. Substitute its `{{PRD_FILE_CONTENT}}` placeholder with the full PRD file contents.

4. **Dispatch the decomposer sub-agent.** Use the Agent tool, `general-purpose`. Its instructions are the substituted prompt, followed by this environment-adaptation note (the note adapts the environment — it is not a prompt edit):

   > **Environment:** you are a Claude Code sub-agent, not running inside Sandcastle. Ignore the `<promise>COMPLETE</promise>` marker instruction — there is no iteration loop; just return your final summary. Write the epic + story files to `docs/work/epics/`. **Do not commit** — leave the files for the human to review and commit, per your own "offer them a chance to review + edit" step.

5. **Report.** Relay the epic folder path the sub-agent created. Remind the user to review/edit the stories, then commit, and that `pnpm work rebuild-state` (or the pre-commit hook) refreshes `_state.json`. The next step in the pipeline is `/work-dispatch`.

## Why a sub-agent

Decomposition is a self-contained, read-heavy job — the whole PRD, the slice-rule reasoning, the file-writing. Running it in a sub-agent keeps all of that out of the main session; you get back only the epic path.

## Quick reference

|                   |                                                                    |
| ----------------- | ------------------------------------------------------------------ |
| Input             | an `approved` PRD in `docs/work/prds/`                             |
| Role prompt       | `.sandcastle/decomposer.prompt.md` — read, never copied            |
| Sub-agent         | one `general-purpose` agent                                        |
| Output            | `docs/work/epics/<epic-id>/` — `_epic.md` + `NN-<story>/_story.md` |
| Upstream          | `to-prd` / `grill-with-docs` produce the PRD                       |
| Downstream        | `/work-dispatch` runs the tasks                                    |
| Sandcastle parity | mirrors `pnpm work decompose --execute`                            |

## Common mistakes

- **Copying the prompt into this skill.** `.sandcastle/decomposer.prompt.md` is the source of truth — read it at dispatch time, every time.
- **Decomposing a `draft` PRD.** Check `status: approved` first.
- **Letting the sub-agent commit.** It writes files; the human reviews and commits.