---
name: fluent-feature-phase
description: Break an approved spec into independently buildable, testable, and deployable delivery phases using vertical slice architecture. Sits between spec approval and feature planning — each phase becomes a scoped input for /fluent-feature-plan. Triggers on "phase this feature", "split into phases", "incremental delivery", "vertical slices", "delivery phases".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: [--profile PROFILE] [--feature SLUG] [--phases N]
cursor-tier: manual
---

# Feature Phasing — Vertical Slice Delivery

Break an approved Business Spec into independently buildable, testable, and deployable **delivery phases** — each phase is a vertical slice that delivers end-to-end value.

## Where This Sits in the Flow

```
/fluent-use-case-discover → spec.md → [user approves]
        ↓
/fluent-feature-phase → phases.md → [user approves]     ← THIS SKILL (optional)
        ↓
/fluent-feature-plan (scoped to Phase 1) → plan.md → [user approves]
        ↓
implement Phase 1 → deploy → test → advance to Phase 2
        ↓
/fluent-feature-plan (scoped to Phase 2) → plan.md → ...
```

**Input:** An approved spec (`spec: "APPROVED"` in status.json).
**Output:** `phases.md` — a phased delivery roadmap.
**Next step:** `/fluent-feature-plan` scoped to Phase 1 artifacts.

This skill is **optional** — small features go straight from spec to plan. Use it when the feature is too large for a single plan-build-deploy cycle.

## Ownership Boundary

This skill **produces `phases.md` only**. It does NOT:
- Generate implementation plans (that's `/fluent-feature-plan`, run per phase)
- Scaffold code, rules, or modules (downstream skills)
- Deploy anything (deployment skills)

Other skills own:
- Implementation planning → `/fluent-feature-plan` (run once per phase)
- Rule scaffolding → `/fluent-rule-scaffold`
- Workflow building → `/fluent-workflow-builder`
- Module scaffolding → `/fluent-module-scaffold`
- Build orchestration → `/fluent-build`
- Deployment → `/fluent-module-deploy`, `/fluent-workflow-deploy`
- Testing → `/fluent-e2e-test`

## When to Use

Use `/fluent-feature-phase` when:
- **Large features** — 8+ rules, 3+ workflows, or multiple entity types
- **Cross-domain features** — spanning ORDER → FULFILMENT → LOCATION → INVENTORY
- **Incremental delivery needed** — stakeholders want value sooner, not a big-bang release
- **Risk mitigation** — complex integrations where deploying everything at once is risky
- **Multi-team coordination** — backend/frontend/integration teams working in parallel
- **Long implementation timelines** — features spanning multiple sessions/sprints

## When NOT to Use

- **Small features** — fewer than 5 rules, 1 workflow, single entity type → go straight to `/fluent-feature-plan`
- **Single-artifact changes** — settings update, one workflow edit, one rule → these still go through the mandatory spec → plan → approval gate (per CLAUDE.md), but phasing adds no value
- **Already phased** — if the spec naturally has clear independent sections
- **Read-only work** — analysis, explain, trace → no phases needed (exempt from planning gate entirely)

## Inputs

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--profile` | No | Active profile | Target Fluent profile |
| `--feature` | No | Auto-detect | Feature slug under `accounts/<PROFILE>/features/` |
| `--phases` | No | Auto (complexity-scaled) | Override the number of phases (2-6) |

## Progress

Emit this block at each phase transition:

```
▸ /fluent-feature-phase [1/5]
  ✓ Pre-flight checks         → Analyze scope
  ○ Identify vertical slices   ○ Order by dependencies
  ○ Write phases.md & approval
```

Update the block as each phase completes — mark completed with `✓`, active with `→`, remaining with `○`.

## Pre-flight: Project Knowledge Check

Check for project-specific knowledge that should inform phasing:

1. Check if `accounts/<PROFILE>/knowledge/` exists
2. If yes, read it and find files where `relevant-skills` includes `fluent-feature-phase`
   **Account knowledge:** Read from `accounts/<PROFILE>/knowledge/` when `FLUENT_PROFILE` is set. These contain project-specific conventions.

3. Read matching knowledge files — typically:
   - `knowledge/platform/domain-model.md` — entity types, cross-domain relationships, orchestrable classification
   - `accounts/<PROFILE>/knowledge/client/business-rules.md` — business constraints that affect phase ordering
   - `accounts/<PROFILE>/knowledge/client/data-model.md` — entity types, subtypes, dependency chains
   - `accounts/<PROFILE>/knowledge/client/integrations.md` — external system dependencies that affect phase boundaries
4. Apply knowledge silently — do NOT show raw knowledge to user, just use it to inform phasing

## Pre-flight: Approved Spec Verification (MANDATORY)

This skill requires an **approved spec**. It does NOT accept plans as input — plans come *after* phasing.

### Step 1: Check for approved spec

```bash
cat accounts/<PROFILE>/features/<slug>/status.json   # look for "spec": "APPROVED"
```

**If spec is APPROVED:**
- Read `features/<slug>/spec.md`
- Proceed to Phase 1

### Step 2: No approved spec → BLOCKED

If no approved spec exists:
- **STOP.** Do not proceed.
- Inform: *"No approved Business Spec found. A spec is required before phasing. Run `/fluent-use-case-discover` to produce a spec first."*
- Signal: `→ BLOCKED: PREREQ_MISSING — No approved spec. Run /fluent-use-case-discover`

### User override (explicit only)

User can bypass with "skip spec check" or similar explicit instruction. Log the override in `phases.md` header.

## Phase 1: Analyze Scope

Parse `spec.md` to build an artifact inventory.

### 1.1 Extract artifact counts

Count each artifact type mentioned in the spec:

| Artifact Type | Count Method |
|---------------|-------------|
| **Rules** (Java) | Count rules mentioned in spec acceptance criteria |
| **Rulesets** | Count distinct rulesets / workflow states with logic |
| **Workflows** | Count distinct workflow types (ORDER::HD, FULFILMENT::HD, etc.) |
| **Entity types** | Count distinct entity types involved (ORDER, FULFILMENT, LOCATION, etc.) |
| **Settings** | Count settings mentioned or implied |
| **User Actions** | Count UI buttons / user-triggered events |
| **Integrations** | Count external system touchpoints (webhooks, APIs) |
| **Manifest changes** | Count UI pages, routes, components |

### 1.2 Classify complexity tier

Use artifact counts to classify:

| Tier | Rules | Workflows | Entities | Recommended Phases |
|------|-------|-----------|----------|--------------------|
| **SIMPLE** | 1-3 | 1 | 1-2 | 2 |
| **MEDIUM** | 4-8 | 1-2 | 2-3 | 3-4 |
| **COMPLEX** | 9-15 | 3-4 | 3-5 | 4-5 |
| **VERY COMPLEX** | 16+ | 5+ | 5+ | 5-6 |

If `--phases N` is provided, use that number (clamped to 2-6) regardless of tier.

### 1.3 Build artifact dependency graph

Map dependencies between artifacts:

```
Entity types → Base statuses → Rules → Rulesets → Workflows → User Actions → UI
Settings → Rules (that read them)
Integrations → Rules (that call external APIs)
```

Key dependency rules:
- **Entity subtypes** before anything else (workflow needs entitySubtype)
- **Base statuses** before transition rulesets
- **OOTB/EXISTING rules** before custom rules that extend them
- **Settings** before rules that read them via `context.getProp()`
- **Backend** before frontend (user actions need workflow rulesets deployed first)
- **Happy path** before exception handling
- **Core flow** before optional features

## Phase 2: Identify Vertical Slices

A **vertical slice** is a set of artifacts that together deliver a testable, deployable unit of functionality. Each slice should:

1. **Be independently deployable** — can be pushed to environment without other phases
2. **Be testable end-to-end** — has a trigger event and an observable outcome
3. **Not break existing functionality** — no half-deployed states
4. **Deliver business value** — stakeholder can see/use something new

### 2.1 Apply decomposition pattern

Select the best-fit pattern from `DECOMPOSITION_PATTERNS.md` based on the feature's primary domain. Read that file now.

### 2.2 Map use cases to slices

For each use case in the spec:
1. Identify the **minimal artifact set** needed for end-to-end execution
2. Group use cases that share artifacts into the same slice
3. Ensure no slice has orphaned artifacts (rules without rulesets, rulesets without workflows)

### 2.3 Identify the core happy path

The **first phase MUST always be the core happy path** — the simplest end-to-end flow. This establishes:
- Base entity types and subtypes
- Core workflow structure and status graph
- Essential OOTB rules and minimal custom rules
- Basic settings

Everything else layers on top.

### 2.4 Validate slice independence

For each proposed slice, verify:
- [ ] Can be deployed to a clean environment with only prior phases deployed
- [ ] Has at least one testable scenario (event in → state change out)
- [ ] Does not partially implement a workflow transition (either the full transition or nothing)
- [ ] User actions (if any) reference only rulesets deployed in this or prior phases
- [ ] No circular dependencies with other slices

## Phase 3: Order by Dependencies

### 3.1 Apply dependency ordering rules

Order phases following these precedence rules:

1. **Infrastructure first** — entity subtypes, base workflow structure, core settings
2. **Happy path** — the primary use case end-to-end
3. **Variations** — additional subtypes, routing branches, conditional logic
4. **Exception handling** — error states, compensation flows, retry logic
5. **User interface** — user actions, manifest changes, custom components
6. **Integration** — external webhooks, batch jobs, notifications
7. **Optimizations** — performance tuning, caching, batch operations

### 3.2 Check for phase boundary conflicts

A **phase boundary conflict** occurs when splitting artifacts would leave an incomplete state:

| Conflict | Resolution |
|----------|------------|
| Rule A sends event that Rule B handles, both NEW | Keep A and B in same phase |
| Workflow status used by user action, both NEW | User action in same phase as the status |
| Setting read by rule, both NEW | Setting in same or earlier phase than rule |
| Parent entity creates child, both new workflows | Child creation in same phase as parent dispatch |

### 3.3 Handle cross-entity boundaries

When a feature spans multiple entity types (e.g., ORDER → FULFILMENT → CONSIGNMENT):
- Phase 1: Parent entity workflow (ORDER) — up to the dispatch point
- Phase 2: Child entity creation + workflow (FULFILMENT) — from dispatch to completion
- Phase 3: Grandchild or sibling entities (CONSIGNMENT)
- Phase N: Cross-entity sync rules, cascading status updates

Exception: If parent→child creation is tightly coupled (e.g., ORDER creates FULFILMENT in one ruleset), keep them in the same phase.

## Phase 4: Write `phases.md`

### 4.1 Read the template

Read `PHASE_TEMPLATE.md` in this skill directory. It defines the structure for `phases.md`.

### 4.2 Write the file

Write `phases.md` to `accounts/<PROFILE>/features/<slug>/phases.md`.

### 4.3 Content requirements

For each phase, include:
- **Summary** — 2-3 sentence description of what this phase delivers
- **Artifacts table** — every artifact in the phase with Type, Name, Source classification (NEW/EXISTING/MODIFIED/REUSED/OOTB), and description
- **Dependencies** — what must be deployed before this phase
- **Acceptance criteria** — testable conditions proving the phase works (checkboxes)
- **Skills to run** — ordered list of skills to execute this phase
- **Deployment notes** — any special deployment considerations
- **Risk assessment** — what could go wrong, mitigation

### 4.4 Artifact completeness check

After writing all phases, verify:
- Every artifact from the spec appears in exactly one phase
- No artifact is duplicated across phases (except EXISTING references for context)
- The union of all phases equals the full spec scope
- No orphaned artifacts (rule without ruleset, ruleset without workflow, etc.)

### 4.5 Update status.json

Add optional phasing fields to `status.json` (backward-compatible):

```json
{
  "currentPhase": null,
  "totalPhases": 4,
  "phasesApproved": false
}
```

These fields are optional — existing tools ignore them if absent. `currentPhase` starts as `null` (no phase started), then tracks which phase is active during implementation.

## Phase 5: Present for Approval

### 5.1 Present phase overview

Show the user a summary table:

```markdown
| Phase | Name | New Artifacts | Modified | OOTB | Est. Complexity |
|-------|------|---------------|----------|------|-----------------|
| 1 | Core Order Flow | 3 rules, 1 workflow | 0 | 4 rules | LOW |
| 2 | Fulfilment Creation | 2 rules, 1 workflow | 1 ruleset | 2 rules | MEDIUM |
| 3 | User Actions & UI | 0 rules | 2 workflows | 0 | LOW |
| 4 | Exception Handling | 3 rules | 1 workflow | 1 rule | HIGH |
```

### 5.2 Explain phasing rationale

For each phase boundary, explain **why** it's split there:
- "Phase 1 ends at order validation because that's the first testable milestone — you can verify orders reach VALIDATED status."
- "Phase 2 starts with fulfilment creation because it depends on the ORDER workflow being deployed in Phase 1."

### 5.3 Wait for approval

**STOP and WAIT** for user approval. The user may:
- **Approve** → update `status.json`: `phasesApproved: true`, emit `→ READY: phases.md`
- **Request changes** → revise phases, re-present
- **Merge phases** → "combine 2 and 3" → update phases.md, re-present
- **Split phases** → "break phase 2 into two" → update phases.md, re-present
- **Reject** → phases not appropriate for this feature, emit `→ SKIP: User rejected phasing`

### 5.4 Handoff

After approval:

```
→ READY: accounts/<PROFILE>/features/<slug>/phases.md
→ NEXT: /fluent-feature-plan --feature <slug> (Phase 1)
```

Translate for user: *"Phases approved. Next step: run `/fluent-feature-plan --feature <slug>` scoped to Phase 1 artifacts. Or say 'start phase 1' and I'll begin."*

## Vertical Slice Principles

### What makes a good vertical slice

A good slice satisfies the **INVEST-D** criteria:
- **I**ndependent — deployable without pending phases
- **N**o regressions — doesn't break existing behavior
- **V**aluable — delivers observable business value
- **E**nd-to-end — has a trigger and an outcome
- **S**mall — smallest unit that satisfies the above
- **T**estable — has concrete acceptance criteria
- **D**eployable — can be pushed to target environment

### Anti-patterns to avoid

| Anti-pattern | Problem | Fix |
|-------------|---------|-----|
| **Horizontal slicing** | "Phase 1: all rules, Phase 2: all workflows" → nothing works until all phases done | Use vertical slices — each phase has rules + rulesets + workflow changes |
| **Infrastructure-only phase** | Phase 1 is just settings and empty workflows → no testable outcome | Combine infrastructure with the first use case that needs it |
| **UI-first phase** | Phase 1 builds the UI but backend isn't ready → buttons do nothing | Backend (rules + workflow) before frontend (user actions + manifest) |
| **Big-bang final phase** | "Phase 4: everything else" → defeats the purpose | Redistribute; the last phase should be small (polishing, edge cases) |
| **Shared artifact conflict** | Same rule modified in Phase 2 and Phase 4 → merge conflicts | Each artifact appears in exactly ONE phase as NEW or MODIFIED |

### Phase sizing guidelines

| Phase size | Artifacts | Guideline |
|-----------|-----------|-----------|
| **Too small** | 1-2 artifacts | Merge with adjacent phase |
| **Right size** | 3-8 artifacts | Deployable unit with clear acceptance criteria |
| **Too large** | 15+ artifacts | Split into two phases |

## Cross-Entity Decomposition Patterns

See `DECOMPOSITION_PATTERNS.md` for the full library of 6 proven patterns (ORDER, Fulfilment, Returns, UI/Manifest, Integration, Multi-Entity) with phase structures, ordering rules, and a decision tree for choosing the right pattern.

## Integration with Feature Lifecycle

### How phases interact with status.json

The overall feature status progresses normally:
```
DISCOVERY → PLANNING → APPROVED → IN_PROGRESS → BUILT → DEPLOYED → VERIFIED
```

Phases are **sub-steps within the PLANNING → APPROVED → IN_PROGRESS cycle**:
1. Spec approved (`spec: "APPROVED"`)
2. `/fluent-feature-phase` produces `phases.md` → user approves (`phasesApproved: true`)
3. `/fluent-feature-plan` per phase → each phase gets its own plan cycle
4. Implement, deploy, test each phase → advance `currentPhase`
5. All phases done → overall status progresses to BUILT → DEPLOYED → VERIFIED

### Per-phase workflow

For each phase:
1. `/fluent-feature-plan --feature <slug>` — scoped to current phase's artifacts
2. User approves the phase plan
3. Implement with downstream skills (scaffold, build, deploy)
4. Test against phase acceptance criteria
5. Advance `currentPhase` in status.json
6. Repeat for next phase

### Dashboard integration

The feature dashboard (`fluent-ai-skills/tools/generate-feature-dashboard.mjs`) reads `currentPhase`, `totalPhases`, and `phasesApproved` from `status.json`. When present:
- **Docs Ready** ring counts phases.md as a canonical doc (4 total instead of 3)
- **Status Details** table shows "Phase N of M" and phases approval state
- **Delivery Phases** card renders a step progress bar (completed / current / pending)

## Error Handling

| Error | Severity | Recovery |
|-------|----------|----------|
| No spec found | CRITICAL | `→ BLOCKED: PREREQ_MISSING` — run `/fluent-use-case-discover` |
| Spec exists but not approved | CRITICAL | `→ BLOCKED: PREREQ_MISSING` — spec needs user approval before phasing |
| Circular dependency detected between slices | HIGH | Merge the conflicting slices into one phase |
| Artifact not assignable to any phase | MEDIUM | Create a "Phase 0: Infrastructure" for orphaned artifacts |
| `--phases` count doesn't match complexity | LOW | Warn but proceed with user's requested count |

## Handoff Signals

| Signal | Condition |
|--------|-----------|
| `→ REVIEW: accounts/<PROFILE>/features/<slug>/phases.md` | Phases written, awaiting approval |
| `→ READY: accounts/<PROFILE>/features/<slug>/phases.md` | Phases approved |
| `→ NEXT: /fluent-feature-plan --feature <slug> (Phase 1)` | Start planning first phase |
| `→ BLOCKED: PREREQ_MISSING — No approved spec` | No approved spec |
| `→ SKIP: User rejected phasing` | User decided not to phase |

**Always translate signals to natural language for the user.** Raw signals are for agent-to-agent coordination only.

## Examples

### Example 1: ORDER::HD with fulfilment and returns

**Input:** Approved spec for home delivery with fulfilment creation, pick/pack, shipping, and return handling.

**Complexity:** COMPLEX (12 rules, 3 workflows, 4 entity types)

**Phases:**

| Phase | Name | Key Artifacts |
|-------|------|---------------|
| 1 | Core Order Flow | ORDER::HD workflow, validation rules, base statuses |
| 2 | Fulfilment Creation | FULFILMENT::HD workflow, creation rules, routing |
| 3 | Pick/Pack/Ship | Fulfilment state rules, shipping integration |
| 4 | Returns | RETURN_ORDER workflow, refund rules, restock |
| 5 | User Actions & UI | All user action rulesets, manifest pages |

### Example 2: Appeasement feature

**Input:** Approved spec for CREDIT_MEMO::APPEASEMENT with OMS buttons and approval flow.

**Complexity:** MEDIUM (6 rules, 1 workflow, 2 entity types)

**Phases:**

| Phase | Name | Key Artifacts |
|-------|------|---------------|
| 1 | Core Appeasement Flow | CREDIT_MEMO workflow, creation rule, base statuses |
| 2 | Approval & Completion | Approval rules, status transitions, ORDER link |
| 3 | UI Integration | User actions on ORDER, OMS manifest pages |

### Example 3: Multi-location sourcing

**Input:** Approved spec for responsive sourcing across multiple locations with inventory checks.

**Complexity:** COMPLEX (10 rules, 2 workflows, 5 entity types)

**Phases:**

| Phase | Name | Key Artifacts |
|-------|------|---------------|
| 1 | Basic Sourcing | FULFILMENT_CHOICE workflow, sourcing profile settings |
| 2 | Inventory Integration | INVENTORY_POSITION queries, availability rules |
| 3 | Multi-location Routing | Location scoring, capacity rules, split logic |
| 4 | Exception Handling | Fallback rules, no-stock handling, notifications |

## Pre-flight: Feedback Check

Before starting, check for past learnings from this skill:

1. Check if `accounts/<PROFILE>/feedback/fluent-feature-phase.jsonl` exists
2. If yes, read last 20 records
3. Filter to: same entity type/subtype if known, FAILURE or USER_CORRECTED outcomes, confidence = CONFIRMED or PROMOTED
4. Extract top 3 relevant learnings — use as internal "WATCH OUT" guidance during execution
5. Do NOT show raw feedback to the user — silently adjust approach based on past issues

Common patterns from prior runs:
- "Phase boundaries at entity type transitions work best"
- "Always include settings in the same phase as rules that read them"
- "User actions should be last — they're the most visible to stakeholders"

## Post-Execution Feedback Capture

After completion, append a feedback record:

```jsonl
{"schema":"feedback-record-v1","skill":"fluent-feature-phase","timestamp":"<ISO>","outcome":"SUCCESS|PARTIAL_SUCCESS|FAILURE|USER_CORRECTED","feature":"<slug>","phases":<N>,"tier":"SIMPLE|MEDIUM|COMPLEX|VERY_COMPLEX","adjustments":"<user changes if any>","learning":"<key insight>","confidence":"OBSERVED"}
```

Capture especially when the user merges or splits phases — this reveals where the algorithm's phase boundaries diverge from human preference.

## Known Pitfalls
<!-- feedback-promoted: managed section, updated by feedback loop -->

_(No promoted learnings yet.)_

<!-- end feedback-promoted -->
