decomposition-guide

# Overview Defines criteria for independently verifiable implementation tasks with explicit responsibility scopes and real dependency edges. Used by the task-decomposer-linear agent during decompose and revise modes. # Task Decomposition Principles ## Value-Unit Definition A value-unit task delivers one coherent, verifiable outcome: - **User-facing value**: A behavior change observable by end users or API consumers. - **System-facing value**: An infrastructure change that enables subsequent user-facing work (shared contract, migration, test harness). Each value-unit task satisfies all of the following: 1. Produces a deployable or mergeable increment when completed. 2. Has an independently observable completion condition. 3. Depends only on deliverables that must exist before its outcome can be completed or verified. ## Task Types | Type | When to use | Example | |------|-------------|---------| | `value_unit` | Delivers one coherent user-facing or system-facing value | "User can submit review from Word add-in" | | `shared_prerequisite` | Two or more later tasks depend on the same missing foundation at a shared boundary | "Define shared API contract for review requests" | ### Shared Prerequisite Extraction Create a `shared_prerequisite` task only when ALL conditions hold: 1. Two or more later value-unit tasks depend on the same missing piece. 2. The piece changes a shared boundary (contract, interface, infrastructure path, test harness). 3. The boundary must stabilize before the earliest dependent value unit can complete and verify its outcome. Limit the prerequisite to what the earliest executable value-unit task needs. When the split is ambiguous, keep the work inside that value-unit task and record the uncertainty in `dependency_notes`. ## Slicing Strategy ### Vertical Slice (Feature-by-Feature) Use by default when each task can deliver and verify one outcome across its affected layers. ### Horizontal Slice (Layer-by-Layer) Use only when a shared foundation is an independently verifiable deliverable that must stabilize before every dependent value unit can execute or verify its outcome. ### Hybrid Use when shared prerequisite work is required and the remaining outcomes can be delivered as vertical value units. ## Granularity Criteria A well-sized task owns one coherent outcome, names its responsibility scope, and has an independently observable completion condition. ### Too Large (Split Further) Indicators: - Contains independently valuable outcomes that can complete and be verified separately. - Spans unrelated responsibility boundaries whose work has independently completable outcomes. - Combines a prerequisite with later value work even though each is independently deliverable. ### Too Small (Merge Upward) Indicators: - Its completion is observable only through a parent task's acceptance criterion. - Its helper or utility has one parent-task consumer. - Its configuration gains meaning only with its parent feature. ## Dependency Mapping ### Dependency Types | Type | Description | Sequencing | |------|-------------|-----------| | **Data dependency** | Task B requires a schema, contract, or interface from Task A | A completes before B starts | | **Build dependency** | Task B requires compiled output or deployed artifact from Task A | A completes before B starts | | **Knowledge relationship** | Task B benefits from insight from Task A but can proceed with a recorded assumption | Record as an assumption rather than a dependency edge | ### Cross-Service Dependencies When a task spans multiple services: - Record each service in `affected_services`. - Map each service's owned part of the outcome in `service_scopes`. - Record inter-service sequencing in `dependency_notes` only when one service deliverable must stabilize before another can execute or verify. ## Documentation Boundary This decomposition records implementation responsibility. The downstream design workflow decides the documentation path because ADR and Design Doc necessity require confirmed implementation scope and repository evidence. Treat an existing approved ADR or Design Doc as governing context. ## Output Field Reference Every task entry uses this fixed field order: | Field | Required | Description | |-------|----------|-------------| | `task_id` | Yes | Sequential identifier (T1, T2, ...) | | `task_type` | Yes | `value_unit` or `shared_prerequisite` | | `title` | Yes | Imperative phrase describing the deliverable | | `goal` | Yes | One sentence stating the observable condition that proves this task complete | | `affected_services` | Yes | List of service names touched by this task | | `service_scopes` | Yes | List of {service, scope} pairs describing implementation responsibility | | `depends_on` | Yes | List of task_ids (empty list if none) | | `dependency_notes` | Yes | List of strings explaining each dependency reason | | `assumptions` | Yes | List of unresolved conditions that materially constrain this task (empty list if none) | | `key_decisions` | Yes | List of user decisions that materially constrain this task (empty list if none) |