/decomposing-work

name: decomposing-work
description: Converts an approved ARCHITECTURE.md into an implementation roadmap of isolated, dependency-ordered chunks. Use when architecture has been approved and work must be decomposed before implementation begins.

Decomposing Work

Converts a confirmed ARCHITECTURE.md into a persistent roadmap of implementation chunks — the decomposition discipline that determines whether developer-agents succeed.

**Position:** architecting-software (ARCHITECTURE.md) → decomposing-work (ROADMAP.md structure) → enriching-roadmap (acceptance criteria, pattern references) → developer-agent.

**Inputs:** a confirmed ARCHITECTURE.md and human confirmation to proceed — do not begin autonomously. If the architecture is ambiguous (missing component boundaries, implicit interfaces, unclear data ownership), flag specific gaps to the human before producing chunks. Inferred boundaries produce misaligned briefs.

**Output:** `ROADMAP.md` in the project root — header block, global Definition of Done, chunks grouped by phase, per the Templates section. Present the draft as "proposed" and write the final file only after the human confirms.

**Not covered:** architecture design, enrichment, orchestration, implementation.

Workflow

Step 1: Read the Architecture

Read ARCHITECTURE.md fully and extract four labelled lists:

• **Components** — named services, modules, packages, domains
• **Integration surfaces** — every API, event contract, shared schema, or data-model interface between components
• **Foundational infrastructure** — what must exist before any feature (project scaffold, CI/CD, database setup, auth skeleton, shared types, logging wiring)
• **Cross-cutting concerns** — logging, error handling, observability, authentication — only those explicitly described in the architecture

Log anything ambiguous or absent as an open question. Do not proceed with unresolved questions that would force you to infer chunk boundaries.

Step 2: Calibrate Scale

Assess project scale (component count, team size, complexity, workflow tier) and set a target chunk range — this prevents over-decomposition, where brief-develop-review overhead exceeds the project's complexity.

| Project scale | Target chunks | Example | |---------------|---------------|---------| | Small (1-2 components, solo dev) | 5-12 | Personal recipe app, CLI tool | | Medium (3-5 components, small team) | 10-20 | SaaS feature, API service | | Large (5+ components, team) | 15-40 | Platform, multi-service system |

Use this as a sanity check after Step 5: if the chunk count significantly exceeds the target, consolidate chunks that form natural vertical slices.

Step 3: Identify the Walking Skeleton (chunk-001)

Non-negotiable, before any other chunk. The Walking Skeleton is the thinnest end-to-end implementation through all major architectural layers — a single request or operation traversing the full system with no real business logic. It validates that the layers connect and establishes the project structure every subsequent chunk plugs into.

State the single traversal (e.g., "HTTP request to `/health` returns 200 from behind the database connection"), the layers it touches, and the infrastructure it establishes. **Always Phase 0, chunk-001, no dependencies; every other chunk depends on it.**

Step 4: Extract Remaining Chunks

Map each element from Step 1 to chunks:

| Architecture element | Chunk type | |---|---| | Component / service / module | One or more `feature` chunks (start with the thinnest viable path through the component) | | API boundary / shared interface / event contract | One `interface` chunk (contract before either side implements) | | Shared data model or schema | One `infrastructure` chunk (schema and migrations before data access) | | Foundation infrastructure (CI, scaffold, auth skeleton, shared types) | `infrastructure` chunks in Phase 0 | | Third-party integration or adapter | One `integration` chunk | | Cross-cutting concern | Scaffold in Phase 0 as `infrastructure`; harden in Phase 3 as `hardening` |

**Granularity: each chunk is a coherent vertical slice** — the smallest unit that produces an independently testable capability end-to-end. Don't split tightly coupled code (a service from its routes) just to reduce file count. Chunks typically touch 2–5 files; beyond 5, verify the files are genuinely coupled, and if not, split. Never split a single file's functionality across chunks unless it genuinely has independent concerns. (A previous hard 1-3 file constraint caused artificial splits — vertical slices aligned with how code is written and tested work better.)

Write a draft entry per chunk using the Templates schema; leave `Depends on` for Step 5.

Step 5: Build the Dependency Graph

Fill `Depends on` for every chunk, applying:

• Interface chunks precede both sides of the integration they define
• Infrastructure chunks precede chunks requiring that infrastructure
• The Walking Skeleton precedes everything
• Feature chunks may depend on their component's interface chunks but not on sibling feature chunks (keep them parallel-safe)

Verify the graph is a DAG — a cycle means the decomposition has a structural problem; resolve it before proceeding. Chunks with no dependencies beyond the Walking Skeleton are the first parallel candidates.

Step 6: Assign Phases

Group by dependency depth:

| Phase | Content | |---|---| | **Phase 0 — Foundation** | Walking Skeleton, CI/CD scaffold, shared types and interfaces, database schema, auth skeleton, logging wiring | | **Phase 1 — Core domains** | Primary capability of each component; no cross-component integration yet | | **Phase 2 — Integration** | Cross-component flows, API composition, third-party adapters, auth flows using the skeleton | | **Phase 3 — Hardening** | Comprehensive error handling, observability, performance-sensitive paths, security hardening |

For simple architectures (one or two components, no distinct integratio