Feature Decomposition

Feature Decomposition

Purpose

Decomposition commonly earns its cost through work that can be validated independently, work that must be ordered because of a real dependency, and work that will be shared across people or sessions. Outside those, a breakdown is a table of contents for a change that would have been easier to read as a diff.

The output that always matters is the resource list. Child Product/Tech Features above it are optional and must remain valuable, independently decidable/deliverable, and testable; resources are what gets implemented, validated and tracked.

Workflow

1. Test whether to decompose at all. If the feature is one resource, say so and produce a one-line list. That is a complete answer.
2. Produce the resource list first, from the impact map. Each element in the map becomes a resource or joins one; nothing in the map is unaccounted for. Reuse the current map/scope revision. If none exists, record a minimal source-to-resource mapping for the known work; leave material unknowns open rather than inventing files or scope.
3. Give each resource a RES-* identifier, a dependency list and a validation — the fields are in references/resource-catalogue.md. A resource with no stated validation is not finished being defined.
4. Create child features only when the grouping adds an independently valuable outcome. A Product Feature uses PF-*; a Tech Feature uses TF-* and names measurable engineering value.
5. Keep enabling work as resources by default. A migration, component, infrastructure change, or test harness is RES-* unless it independently reduces risk/cost or enables a usable capability with its own acceptance. Do not manufacture a Tech Feature from a phase or layer.
6. Order the resources by their dependencies, and say where the order is forced versus merely convenient. Check missing IDs and cycles. A cycle calls for clarifying a shared contract, splitting a producer from its consumer, or merging inseparable work; do not invent a linear order over it.
7. Say why the shape is what it is — including "not decomposed, because it is one resource".

When to decompose

Splitting one behaviour across a controller story, a service story and a repository story produces three items none of which can be validated alone. That is not decomposition; it is transcription of the layer diagram.

Decision rules

IF a child cannot state independent product or engineering value and its own acceptance
THEN it is not a child feature; keep its work as RES-* under the parent.

IF a resource has many dependencies
THEN verify each necessary input and distinguish implementation, validation and release order.
     A legitimate integration resource may consume many outputs; count alone does not justify a split.

IF two resources always change together and are always validated together
THEN consider merging unless ownership, staged compatibility or a real handoff requires separation.

IF a resource cannot be validated without another resource existing
THEN say so in its validation, and let the order follow from it.

IF a resource lacks a path to in-scope impact and acceptance
THEN identify the missing mapping or scope decision. One impact entry can justify several
     resources, and one resource can satisfy several entries; counts are not a scope test.

IF a resource is "write the tests"
THEN it is misplaced: tests belong to the resource whose behaviour they establish.
     A separate test resource is legitimate only for shared harness or fixture work.

IF the feature is Light
THEN return one concise resource with its validation when it remains one local outcome.
     If material dependencies or boundaries emerge, report the changed driver for reclassification;
     this analysis does not itself authorize implementation.

Constraints

• Do not split to look thorough. Three resources implemented and tracked beat eleven resources of which six are one line each.
• Do not decompose by layer by default. Decompose by behaviour, and let a behaviour touch several layers.
• Every resource traces to the impact map and to scope. A resource that traces to neither is scope creep with an identifier.
• Do not estimate here. Sizes and dates are a separate concern with separate discipline.
• Preserve supplied Java/framework/runtime and compatibility constraints in each affected resource. Decomposition does not choose upgrades or a new technical baseline.

Output

Decomposition   child features and resources | resources only | none
Because         <the signal that decided it>

PF-01  <independently valuable product outcome and BAC-*>
  RES-01  <resource>
  RES-02  <resource>

TF-01  <independently valuable engineering outcome and TC-*>
  RES-03  <resource>

Parent resources (including work not assigned to a child)
  RES-04  <resource>

Dependencies RES-02 needs RES-01's column; RES-03 needs RES-02's contract
Ready first  RES-01, RES-04 (no dependency between them)
Then         RES-02 -> RES-03; RES-04 may proceed independently

Execution consumes resource scope, acceptance, ownership and dependencies together. Independence in the graph permits parallel planning only when shared-file/resource ownership is also resolved. Before handoff, check scope coverage, unique/stable IDs, an acyclic dependency graph and validation for each resource; report unresolved dependencies rather than claiming the breakdown ready.