# Phase 07: Feature Decomposition

## Entry Gate

```bash
devforgeai-validate phase-check ${SOLARCH_ID} --workflow=solution-architecture --from=06 --to=07 --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Proceed to Phase 07 |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — previous phase not complete |

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Decompose the epic into features (`F-NN`), each mapped to the components that realize it and each carrying a feasibility verdict from an independent architecture review. This is the epic-creation work absorbed from `spec-driven-architecture` Phase 11 — EXTENDED, because it is now grounded in the component, contract, data, and integration design of Phases 03–06. **The architect-reviewer feasibility pass is BLOCKING.** |
| **REFERENCE** | `.claude/skills/spec-driven-solution-architecture/references/solution-architecture-output.schema.json` |
| **SUBAGENTS** | `requirements-analyst` (feature decomposition); `architect-reviewer` (feasibility verdicts — BLOCKING) |
| **STEP COUNT** | 5 mandatory steps |

## Phase Exit Criteria

Before this phase can complete, ALL of the following MUST be true:

- [ ] `requirements-analyst` invoked; the epic decomposed into features
- [ ] Each feature assigned an `F-NN` id and mapped to ≥ 1 component
- [ ] `architect-reviewer` invoked and returned a feasibility verdict per feature
- [ ] Every `INFEASIBLE` feature resolved with the user; every `NEEDS_ADR` feature recorded as an open question

**IF any criterion is unmet: HALT. Do NOT proceed to Phase 08.**

---

## Reference Loading

```
Read(file_path=".claude/skills/spec-driven-solution-architecture/references/solution-architecture-output.schema.json")
```

The `$defs.feature` shape (`id`, `name`, `description`, `feasibility`, `risk`,
`components`, `technical_notes`) is exactly what this phase produces. IF the Read
fails: HALT — "Phase 07 output contract not loaded."

Do NOT rely on memory of previous reads. Load fresh every time this phase executes.

---

## Mandatory Steps

### Step 7.1: Invoke requirements-analyst

**EXECUTE:**
```
Task(
  subagent_type="requirements-analyst",
  prompt="Decompose epic ${epic_ref} into features for a Solution Architecture
    Document.

    Inputs:
    - Epic scope: ${epic_scope}  (name, summary, in_scope, out_of_scope, requirement_refs)
    - Components: ${components}
    - Interface contracts: ${interface_contracts}
    - Data model: ${data_model}
    - Integration design: ${integration_design}

    Decompose the epic into the smallest set of independently valuable features
    that fully cover epic_scope.in_scope. Return structured JSON ONLY — do NOT
    write files:
    { features: [ {
        name, description,
        component_refs: [ 'COMP-NNN', ... ],   // components that realize the feature
        requirement_refs: [ 'FR-NNN', ... ] } ] }

    Each feature MUST map to ≥ 1 component. Every epic in-scope capability MUST
    be covered by ≥ 1 feature."
)
```
This is a BLOCKING task. Wait for the result before proceeding.

**VERIFY:**
- Task returned a `features` array with ≥ 1 entry
- Every feature has `name` and ≥ 1 `component_refs` entry

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=07 --step=7.1 --project-root=. 2>&1
```
```json
{ "phase": "07", "step": "7.1", "analyst_features": [ ... ] }
```

---

### Step 7.2: Assign IDs and Map to Components

**EXECUTE:**

For each feature the `requirements-analyst` returned, assign an `F-NN` id:

```
feature = {
  id: "F-01",                    # ^F-[0-9]{2,}$
  name: "<feature name>",
  description: "<what the feature delivers>",
  feasibility: "<set in Step 7.3>",
  risk: "<set in Step 7.3>",
  components: [ "COMP-NNN", ... ],   # MUST be Phase 03 component ids
  technical_notes: "<design notes — contracts/entities involved>"
}
```

Verify every `components[]` entry resolves to a Phase 03 component. Confirm the
union of all features' component refs covers every component that has a
responsibility tied to an in-scope capability — an orphaned component (realized
by no feature) is a decomposition gap.

**VERIFY:**
- Every feature has a unique `id` matching `^F-[0-9]{2,}$`
- Every `components[]` id resolves to a Phase 03 component
- Every epic `in_scope` capability is covered by ≥ 1 feature

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=07 --step=7.2 --project-root=. 2>&1
```
```json
{ "step": "7.2", "features": [ ... ], "coverage_gaps": [ ... ] }
```

---

### Step 7.3: Invoke architect-reviewer for Feasibility (BLOCKING)

**EXECUTE:**
```
Task(
  subagent_type="architect-reviewer",
  prompt="Assess the technical feasibility of each feature in this Solution
    Architecture for epic ${epic_ref}.

    Inputs:
    - Features: ${features}
    - Components (with layers + dependencies): ${components}
    - Interface contracts: ${interface_contracts}
    - Data model: ${data_model}
    - Integration design: ${integration_design}
    - System Architecture handoff + constraints: ${sysarch_handoff}
    - The 6 constitutional context files in devforgeai/specs/context/

    For EACH feature, return a feasibility verdict:
    { verdicts: [ { feature_id: 'F-NN',
        feasibility: 'FEASIBLE' | 'NEEDS_ADR' | 'INFEASIBLE',
        risk: 'Low' | 'Medium' | 'High',
        rationale: '<why>',
        evidence: '<file:line or design reference>' } ] }

    FEASIBLE   — realizable within the current constitution and design.
    NEEDS_ADR  — realizable, but requires a new architecture decision (e.g. a
                 constraint exception, a tech-stack addition).
    INFEASIBLE — cannot be realized as designed; the design must change."
)
```
This is a BLOCKING task. Wait for the result before proceeding.

**VERIFY:**
- Task returned a `verdicts` array with one verdict per feature
- Every verdict has `feature_id`, `feasibility`, `risk`
- Every `feasibility` is one of `FEASIBLE` / `NEEDS_ADR` / `INFEASIBLE`

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=07 --step=7.3 --project-root=. 2>&1
```
```json
{ "step": "7.3", "feasibility_verdicts": [ ... ],
  "verdict_summary": { "FEASIBLE": 0, "NEEDS_ADR": 0, "INFEASIBLE": 0 } }
```

---

### Step 7.4: Reconcile the Verdicts

**EXECUTE:**

Merge each verdict into its feature, then resolve the non-FEASIBLE verdicts:

```
FOR each feature F:
  F.feasibility = verdict.feasibility
  F.risk        = verdict.risk
  Append the verdict rationale/evidence to F.technical_notes.

  IF F.feasibility == "INFEASIBLE":
    AskUserQuestion — the feature cannot be built as designed. Options:
      - Revise the design (return to the relevant phase with user consent — Deviation Protocol)
      - Re-scope the epic to drop the feature (record in epic_scope.out_of_scope)
      - Override with justification (record the user's reasoning)
    An INFEASIBLE feature MUST NOT remain unresolved.

  IF F.feasibility == "NEEDS_ADR":
    Record the required decision as an open question for the Phase 08 handoff —
    /create-development-architecture or an ADR resolves it. This is non-blocking.
```

**VERIFY:**
- Every feature carries a `feasibility` and a `risk` value
- No `INFEASIBLE` feature remains unresolved
- Every `NEEDS_ADR` feature is captured as a handoff open question

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=07 --step=7.4 --project-root=. 2>&1
```
```json
{ "step": "7.4", "infeasible_resolutions": [ ... ], "needs_adr_open_questions": [ ... ] }
```

---

### Step 7.5: Record the Feature Decomposition

**EXECUTE:**
```
Assemble the feature_decomposition array — each entry the full feature object
with id, name, description, feasibility, risk, components, and technical_notes.
```

**VERIFY:**
- `feature_decomposition` is a non-empty array
- Every feature is schema-conformant (id pattern, feasibility enum, risk enum)

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=07 --step=7.5 --project-root=. 2>&1
```
```json
checkpoint.phases["07"] = {
  "status": "completed",
  "feature_decomposition": [
    { "id": "F-01", "name": "...", "description": "...",
      "feasibility": "FEASIBLE", "risk": "Low",
      "components": [ "COMP-NNN", ... ], "technical_notes": "..." }, ...
  ],
  "needs_adr_open_questions": [ ... ]
}
```

---

## Exit Gate

```bash
devforgeai-validate phase-complete ${SOLARCH_ID} --workflow=solution-architecture --phase=07 --checkpoint-passed --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Phase 07 complete — proceed to next phase |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — checkpoint/step validation failed |

---

## Phase Transition Display

```
Display:
  "Phase 07 Complete: Feature Decomposition"
  "Features: {count}  |  FEASIBLE: {n}  NEEDS_ADR: {n}  INFEASIBLE: {n}"
  "All INFEASIBLE features resolved  |  Proceeding to Phase 08: Solution Architecture Document"
```
