Decomposing a Master PRD

A Master PRD Is Not a Build Plan

A master PRD describes the complete feature: what it does, who it serves, what it replaces, what success looks like. It is written at the level of "the /ship meta-orchestrator coordinates eight phases from preflight to compounding loop." It does not describe how Phase C (Build) coordinates with Phase D (Quality Gate) at the implementation level.

The decomposition step bridges this gap. /prd-writer --decompose takes a master PRD and splits it into per-phase and per-feature PRDs, each with its own acceptance criteria, consumer contracts, and definition of done. The per-phase PRDs are what agents actually receive before they build.

The /ship Decomposition Example

The /ship meta-orchestrator is one of the most complex features in Knox's stack. Its master PRD covers eight phases. Here is what the decomposition looks like:

The structure reveals two important properties:

Phase A (Preflight) has no dependencies — it can be specced and implemented first. Phase B depends on Phase A completing — the security scan needs to know what the preflight found. This dependency order is not implicit; it is written explicitly in the per-phase PRD for Phase B: "Requires: Phase A complete, host-check result available."

The decomposition also reveals which phases can be specced simultaneously. Phase C (Build) and Phase D (Quality Gate) specs can be written in parallel — they are independent documents. The Phase C spec describes what agents will build. The Phase D spec describes what the quality gate will check. Neither spec depends on the other being written first.

The Sequencing Decision

The hardest part of decomposition is deciding which phases serialize and which parallelize. Five factors drive this decision:

The most important row in this matrix is Resource Conflict. Shared registry files (index.ts, tracks.ts, tiers.ts) serialize. Always. Even when the phases themselves have no data dependency, two agents editing the same file will produce a last-writer-wins collision.

The solution Knox uses in parallel dispatch sessions: each agent produces a diff file (their additions as text), and the orchestrator makes a single atomic edit to the shared registry after all agents complete. One edit, no conflicts. This pattern is covered in the parallel-agent-dispatch track; the spec-driven corollary is that your per-phase PRDs must explicitly state which files each phase may touch — and shared registry files must be marked as "orchestrator only."

The Successor Ticket Rule

Here is the rule that gets violated most often during decomposition: every spec-phase completion must explicitly queue its implementation task, in the same conversation.

When you merge a per-phase spec, you feel a sense of progress. The work is documented. The acceptance criteria are clear. The implementation will obviously follow. This feeling is false. Three sessions pass. The context of what "Phase A spec complete" meant is gone. The feature never ships.

The rule prevents this: when you merge the Phase A spec (or even when you write it), create ticket impl-ship-phase-a immediately. Kanban-state.json is the source of truth. The ticket must reference the PRD: "Implements: docs/prd/ship-phase-a.md." No ticket = no guarantee of implementation.

This pattern is drawn directly from Knox's MEMORY.md lesson: "Spec merged ≠ implementation queued — every spec-completion must explicitly queue its impl task; decoupling-for-sequencing must cut the successor ticket same conversation."

What the Per-Phase PRD Contains

A per-phase PRD is a smaller version of the master PRD with three key additions:

1. Phase number and dependency list — explicit "Requires: Phase X complete"
2. File ownership — which files this phase may touch, which are off-limits (shared registries)
3. Handoff contract — what the next phase expects to receive from this one

The file ownership section is the handoff from decomposition to parallel dispatch. When Phase C (Build) and Phase D (Quality Gate) run simultaneously, Phase C's PRD says "may write: src/features/ship/*.ts, tests/ship/*" and Phase D's PRD says "may write: nothing — reads only, generates report." Zero collision risk because the PRDs define the file boundaries before agents start.

Now do the split yourself: take a master PRD, cut it into standalone per-feature PRDs with explicit dependency lines and file ownership, and write down the rationale for where you placed the seams.

What's Next

The next lesson covers the handoff from decomposed PRDs to the build phase: how to feed a per-phase PRD to an agent, the five-field dispatch contract, and the consumer-contract check that must happen before any output shape is finalized.