---
name: fluent-use-case-discover
description: Interactive requirements gathering wizard that produces a structured Business Specification. Walks through use cases, actors, business rules, integrations, and acceptance criteria. Supports interactive mode, document analysis mode, and structured PRD template intake. Triggers on "discover use case", "gather requirements", "business spec", "use case discovery", "what are we building", "requirements gathering", "spec wizard", "analyze requirements", "prd intake", "fill prd".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: [--analyze <path-or-paste>] [--prd <path>] [--profile PROFILE] [--retailer RETAILER_REF]
cursor-tier: manual
---

# Use Case Discovery Wizard

Gather structured business requirements through interactive questioning or document analysis. Produces a Business Specification document that feeds directly into `/fluent-feature-plan` for technical implementation planning.

## Pre-flight: Feedback Check

Before starting, check for past learnings from this skill:

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

## Ownership Boundary

This skill owns requirements elicitation, use case definition, business rule capture, and the Business Spec output artifact.

Other skills own:
- Technical implementation planning --> `/fluent-feature-plan`
- Scope document decomposition (ADD format) --> `/fluent-scope-decompose`
- Feature reverse-engineering (existing features) --> `/fluent-feature-explain`
- Workflow building --> `/fluent-workflow-builder`
- Rule scaffolding --> `/fluent-rule-scaffold`

This skill produces the business spec; `/fluent-feature-plan` translates it into a technical plan.

## When to Use

- User has a business need but hasn't structured it into formal requirements
- Starting a new feature and need to capture use cases before planning
- A requirements document exists but needs completeness validation and gap filling
- Before running `/fluent-feature-plan` — to ensure all business context is gathered
- When multiple stakeholders have provided fragmented requirements that need consolidation

**Do NOT use** when:
- Requirements are already structured in ADD scope format → use `/fluent-scope-decompose`
- You need to understand an existing feature → use `/fluent-feature-explain`
- Requirements are clear and you're ready to plan → go directly to `/fluent-feature-plan`

## Template Reference

**The Business Spec output template lives at: `SPEC_TEMPLATE.md` (in this skill directory).**

Read that file before producing any spec. It defines:
- The 13-section structure with traceability matrix
- Section descriptions and worked examples
- Completeness scoring criteria

**The self-critique protocol lives at: `CRITIQUE_PROTOCOL.md` (in this skill directory).**

Read that file before Phase 10b. It defines:
- The automated adversarial review loop (up to 3 rounds)
- Critic rubric (7 criteria: platform accuracy, scope, assumptions, use cases, consistency, feasibility, diagram quality)
- Critic agent prompt template
- Guardrails (max rounds, convergence, evidence requirement)
- Deliberation log format

## Progress

Emit this block at each phase transition to show progress (Mode A — interactive wizard):

```
▸ /fluent-use-case-discover [1/12]
  ✓ Mode detection           → Feature identity
  ○ Actors & triggers        ○ User journey & diagrams
  ○ Entities & data          ○ Business rules
  ○ Integrations             ○ UI & actions
  ○ Constraints & risks      ○ Acceptance criteria
  ○ Review & gap analysis    ○ Self-critique (automated)
```

Update the block as each phase completes — mark completed phases with `✓`, the active phase with `→`, and remaining phases with `○`. Replace `[1/12]` with the current phase number.

## Two Input Modes

### Mode A: Interactive Wizard (default)

Run with `/fluent-use-case-discover` or when the user describes a vague feature idea.

The wizard walks through 12 phases of structured questions, each building on previous answers. Uses progressive disclosure — only asks questions relevant to the feature type.

> **Offline limitation:** If no Fluent profile is connected (`FLUENT_PROFILE` not set), Phase 4 environment discovery is SKIPPED. The spec may contain assumptions about available rules, workflows, and entity types. Feature planning will discover the live environment, but spec completeness will be lower without Phase 4 context. Recommend connecting a profile via `/fluent-profile` before running this wizard.

### Mode B: Document Analysis

Run with `/fluent-use-case-discover --analyze <path>` or when the user pastes/provides an existing requirements document (Jira epic, scope doc, email brief, meeting notes).

The wizard:
1. Reads and parses the provided document
2. Extracts what it can into the spec template sections
3. Scores completeness against the 10-phase framework
4. Presents the extracted spec + gap report to the user
5. Enters interactive mode ONLY for HIGH-priority gaps
6. Produces the same Business Spec output as Mode A

Mode B = "parse what you have" + "ask only what's missing".

### Mode C: Structured PRD Template

Run with `/fluent-use-case-discover --prd <path>` or when the user provides a filled-out PRD using the template from `PRD_TEMPLATE.md`.

**When to use Mode C vs Mode A/B:**
- Mode A: User has a vague idea, needs guided elicitation through 12 phases
- Mode B: User has unstructured docs (Jira, email, meeting notes) — skill extracts and fills gaps
- Mode C: User (or BA/PM) has filled a structured PRD template — skill validates, maps to spec, and only asks about gaps

**How Mode C works:**

1. **Read the PRD** — parse the filled `PRD_TEMPLATE.md` structure
2. **Validate entity orchestrability** — check every entity type in the Entity Types table:
   - Cross-reference `Orchestrable?` column against the known entity list in `knowledge/platform/domain-model.md`
   - If entity is NOT orchestrable but feature assumes workflow processing: **BLOCK** with error
   - If `Orchestrable? = Unknown`: look it up and fill in automatically
3. **Validate workflow existence** (requires connected profile):
   - Query `workflow.list` via MCP to check which entity type + subtype combos have active workflows
   - If PRD claims workflow exists but none found: **WARN**
   - If PRD says `Workflow Exists? = Unknown`: check and fill in automatically
   - If workflow exists but has no active transitions (no rulesets): **WARN** — "Workflow exists but may not be Rubix-enabled (no rulesets configured)"
4. **Run cross-reference checks** (see PRD_TEMPLATE.md validation section):
   - Actors vs User Actions
   - Entity Types vs Business Rules
   - Integrations vs Business Rules
   - Feature Type vs populated sections
5. **Map PRD fields to spec sections** using the mapping table in PRD_TEMPLATE.md
6. **Classify each spec section** as SEEDED / PARTIAL / EMPTY / VALIDATED
7. **Generate gap report** — list sections that need expansion, ordered by priority:
   - **EMPTY + mandatory sections** (S5 Use Cases, S5a Diagrams) → must fill interactively
   - **PARTIAL sections** → ask targeted questions (not full phase, just the gaps)
   - **SEEDED sections** → present for confirmation, no questions
8. **Interactive gap-fill** — for EMPTY and PARTIAL sections only, run the relevant phase questions (abbreviated, not full). Skip phases where the PRD provided enough data.
9. **Produce `spec.md`** — same output as Mode A/B, same template, same critique loop

**Mode C output:** Same `spec.md` as Mode A/B. The PRD is the intake; the spec is the deliverable. The PRD itself is NOT stored as an artifact — its content is absorbed into the spec.

**Key advantage:** Mode C typically skips 60-80% of the interactive questions because the PRD pre-answers them. The skill focuses on validation (especially entity orchestrability) and gap-filling rather than full elicitation.

---

## Pre-flight: Project Knowledge Check

Check for project-specific knowledge that should inform requirements gathering:

1. Check if `accounts/<PROFILE>/knowledge/` exists
2. If yes, read it and find files where `relevant-skills` includes `fluent-use-case-discover`
   **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` — use for entity types, valid relationships, orchestrable entities
   - `knowledge/platform/roles-and-permissions.md` — use for RBAC model, context types, enforcement layers
   - `accounts/<PROFILE>/knowledge/client/business-rules.md` — use for existing constraints, routing, exception handling
   - `accounts/<PROFILE>/knowledge/client/integrations.md` — use for known external systems and data flows
   - `accounts/<PROFILE>/knowledge/client/data-model.md` — use for existing entity types, attributes, catalogues
4. Also check `accounts/<PROFILE>/knowledge/client/roles-and-permissions.md` — pre-downloaded role catalog with permissions and context assignments. Use to pre-populate Phase 2.5 role questions.
5. Apply knowledge silently — do NOT show raw knowledge to user, just use it to ask better questions and validate requirements

## Phase 0: Mode Detection & Setup

**Detect mode:**
- If `--prd` flag or user provides a filled PRD template → Mode C
- If `--analyze` flag or user provided an unstructured document → Mode B
- Otherwise → Mode A

**Check profile connection:**
```
environment.discover include=retailer
```
If connected → note profile + retailer for Phase 4 live discovery.
If not connected → skip live discovery, note in output as limitation.

**Check for project knowledge:**

1. Check if `accounts/<PROFILE>/knowledge/` exists
2. If yes, read files where `relevant-skills` includes `fluent-use-case-discover`:
   - `accounts/<PROFILE>/knowledge/client/business-rules.md` — pre-populate known constraints and routing rules
   - `accounts/<PROFILE>/knowledge/client/integrations.md` — pre-populate integration touchpoints
   - `accounts/<PROFILE>/knowledge/client/data-model.md` — pre-populate entity types and attributes
3. Also check `accounts/<PROFILE>/knowledge/templates/spec-addendum.md` — if it exists, append its sections to the spec
4. Use knowledge to ask smarter, more targeted questions in the wizard (skip questions already answered by knowledge files)

**Check for existing specs:**
```bash
ls accounts/<PROFILE>/features/*/spec.md
```
If related specs exist → show to user, ask if this is an update or new spec.

**Slug handling protocol:**
- The slug is NOT asked upfront — it's auto-generated from the feature name in Phase 10 after the full spec is gathered
- If `--feature <slug>` is provided, use that slug (for resuming an existing spec)
- If no slug is provided, generate one automatically in Phase 10 after the feature is fully understood
- Users should NEVER need to memorize slug naming rules — the wizard handles this

---

## Phase 1: Feature Identity

**Purpose:** Establish what we're building and why.
**Feeds → Spec:** §1 Problem Statement, §2 Feature Summary, §3 Scope

Ask these questions (all at once or conversationally based on user engagement):

| # | Question | Type | Required |
|---|----------|------|----------|
| 1.1 | **What is the feature in one sentence?** | Open | YES |
| 1.2 | **What business problem does this solve?** Why is it needed? What pain exists today? | Open | YES |
| 1.3 | **What type of change is this?** | Selection | YES |
|     | Options: New capability / Enhancement to existing / Bug fix / External integration / Data migration / Process change | | |
| 1.4 | **Who requested this and why now?** Stakeholder, team, or business driver. | Open | No |
| 1.5 | **How will you measure success?** What KPIs or metrics prove the feature works? | Open | YES |
| 1.6 | **What is explicitly OUT of scope?** What should this feature NOT do? | Open | Recommended |

**Conditional branching after Phase 1:**
- Type = "Bug fix" → shortened flow: skip Phases 5-7, focus on root cause + fix scenario
- Type = "External integration" → Phase 6 (Integrations) becomes REQUIRED
- Type = "Data migration" → add batch/volume questions to Phase 8

**WAIT gate:** Summarize the feature identity and confirm with the user before proceeding to Phase 2. The slug is NOT generated here — it is auto-generated in Phase 10 after the full spec is gathered.

If the feature builds on an existing one (user said "extend X" or "add to X"):
- Set `basedOn: "<parent-slug>"` in the eventual status.json
- Note this for the §3a Existing State section

---

## Phase 2: Actors & Triggers

**Purpose:** Who's involved and what starts the process.
**Feeds → Spec:** §4 Actors & Triggers

| # | Question | Type | Required |
|---|----------|------|----------|
| 2.1 | **Who are the actors involved?** Who interacts with or is affected by this feature? | Multi-select + open | YES |
|     | Suggest from: Store associate, Warehouse picker/packer, Admin/operations, Customer, External system (OMS/WMS/ERP/TMS), Scheduled job, Automated workflow | | |
| 2.2 | **What triggers this feature?** What event or action kicks it off? | Selection + open | YES |
|     | Suggest from: New order placed, User clicks a button, External system sends data, Scheduled time/cron, Entity reaches a specific status, Manual batch upload, Customer action (app/web) | | |
| 2.3 | **Which Fluent UI modules are involved?** | Multi-select | If human actors |
|     | Options: OMS App, Store App, No UI (backend only) | | |
| 2.4 | **Is this feature retailer-specific or account-wide?** | Selection | YES |
|     | Options: Single retailer, All retailers (account-wide) | | |
| 2.5 | **What user roles are involved?** | Multi-select + open | YES (if human actors) |
|     | Pre-populate from account knowledge (`roles-and-permissions.md`) if available. Probe: Which existing roles interact? Are new roles needed? Do different roles have different capabilities (approval tiers, dollar limits)? | | |
| 2.6 | **How should permissions be enforced?** | Selection | If role-gated |
|     | Options: Platform permissions only (Transition API), Custom role-check in rules (label-only roles), Manifest visibility (hasRole), Combination | | |

### Live Role Discovery

If a Fluent profile is connected, query the role catalog to pre-populate Q2.5:

```graphql
{ roles(first: 100) { edges { node { id name permissions { name } } } } }
```

Also check `accounts/<PROFILE>/knowledge/client/roles-and-permissions.md` for a pre-downloaded snapshot. Present existing roles as selectable options.

If custom label-only roles exist (permissions = []), highlight them: "These roles have no platform permissions — they're checked in custom rule code. Does your feature need similar role-based logic?"

**WAIT gate:** Present actors + roles + trigger summary as a table. Confirm before proceeding.

---

## Phase 3: User Journey & Use Cases

**Purpose:** Define the actual scenarios — the core of the spec.
**Feeds → Spec:** §5 Use Cases, §13 Acceptance Criteria

This is the most important phase. Take time here.

| # | Question | Type | Required |
|---|----------|------|----------|
| 3.1 | **Walk me through the happy path.** Step by step: what happens from trigger to completion? | Open | YES |
| 3.2 | **Are there alternative paths?** Conditions where the flow branches differently? | Open | If applicable |
|     | Probe: What condition causes the branch? What's different about the outcome? | | |
| 3.3 | **What are the failure/exception scenarios?** | Open | YES |
|     | Probe with domain-aware questions based on Phase 1 type: | | |
|     | - Order flow: What if stock is unavailable? What if payment fails? What if address is invalid? | | |
|     | - Fulfilment: What if the item can't be found? What if the carrier rejects it? | | |
|     | - Integration: What if the external system is down? What if data format is wrong? | | |
|     | - General: What if the user cancels midway? Can this be partially completed? | | |
| 3.4 | **Are there time-sensitive aspects?** | Open | If applicable |
|     | Probe: Auto-cancel after X hours? SLA deadlines? Scheduled retries? Escalation rules? | | |
| 3.5 | **Can this be triggered multiple times for the same entity?** Should it be idempotent? | Yes/No + explain | Recommended |

**Output:** After gathering answers, synthesize into numbered use cases:
```
UC-01: [Happy Path] <title> — <one-line summary>
UC-02: [Alternative] <title> — <one-line summary>
UC-03: [Exception] <title> — <one-line summary>
UC-04: [Edge Case] <title> — <one-line summary>
```

### Phase 3b: User Journey Diagrams

**Purpose:** Visualize actor–system interactions at a high level. Diagrams ground the spec in real user workflows and make it reviewable by non-technical stakeholders.

**When to include:** ALWAYS for features with human actors. SKIP only for pure backend/automated features with no UI touchpoints.

**Diagram types (pick the most appropriate):**

| Type | When to Use | Mermaid Syntax |
|------|-------------|----------------|
| **Sequence diagram** | Multi-actor interactions with clear request/response flow | `sequenceDiagram` |
| **User journey** | Single actor's experience across touchpoints | `journey` |
| **Flowchart** | Decision-heavy flows with branching paths | `flowchart TD` |

**Required elements in every diagram:**
1. **Actors** — name and role (e.g., "Ops Staff", "OMS App", "Fluent Platform", "External System")
2. **Trigger** — what starts the flow (annotated on the first interaction)
3. **Happy path** — the primary flow from trigger to outcome
4. **Key decision points** — where the flow branches (alt/opt blocks in sequence diagrams)
5. **Outcome** — the end state for each path

**Rules:**
- One diagram per primary use case (UC-01) at minimum. Add diagrams for alternative/exception paths only if the flow is materially different (not just a different error message).
- Keep diagrams HIGH-LEVEL — 5-10 interactions max. Implementation detail (GraphQL fields, attribute names, CSS) belongs in the plan, not the spec.
- Use Mermaid syntax — validated by `knowledge/mermaid-syntax-rules.md`.
- Diagrams go in spec §5a (after use cases, before entity model).

**Example — read-only UI feature:**
```mermaid
sequenceDiagram
    actor Ops as Ops Staff
    participant OMS as OMS App
    participant API as Fluent GraphQL
    participant WF as Workflow Engine

    Ops->>OMS: Open order detail page
    OMS->>API: orderById(id) { attributes }
    API-->>OMS: Order data + fcOrderStatusHistory
    OMS->>OMS: Render Status Timeline card
    Note over OMS: Shows CREATED then RECEIVED then COMPLETE with timestamps

    alt No history attribute
        OMS->>OMS: Render "No status history available"
    end
```

**Example — interactive workflow feature:**
```mermaid
sequenceDiagram
    actor Staff as Store Associate
    participant Store as Store App
    participant API as Fluent API
    participant WF as Workflow Engine
    participant WMS as External WMS

    Staff->>Store: Click "Start Pick" on fulfilment
    Store->>API: POST /event/sync (StartPick)
    API->>WF: Trigger StartPick ruleset
    WF->>WF: Validate stock, update status to PICKING
    WF-->>Store: Status updated
    Store->>Store: Show pick list UI

    Staff->>Store: Confirm all items picked
    Store->>API: POST /event/sync (ConfirmPick)
    API->>WF: Trigger ConfirmPick ruleset
    WF->>WMS: Webhook: fulfilment ready for pack

    alt Partial pick
        Staff->>Store: Mark items as short-picked
        Store->>API: POST /event/sync (ShortPick)
        WF->>WF: Create exception, escalate
    end
```

**Clarifying questions to ask when the flow is unclear:**
- "Who initiates this — a person clicking a button, or an automated event?"
- "What does the user SEE after this step — a confirmation, a new page, or nothing visible?"
- "If this fails, does the user get an error, or does it silently retry?"
- "Are there any approval gates where someone else must act before the flow continues?"

**WAIT gate:** Present the use case list AND the journey diagram(s). Ask: "Are these use cases and flows complete? Any missing scenarios?"

---

## Phase 4: Entities & Data

**Purpose:** Map use cases to Fluent's entity model.
**Feeds → Spec:** §6 Entity Model

| # | Question | Type | Required |
|---|----------|------|----------|
| 4.1 | **Which entity types are involved?** | Multi-select | YES |
|     | Options: Order, Fulfilment, Fulfilment Options / Fulfilment Choice, Article, Location, Inventory Position, Wave, Consignment, Return Order, Product, Customer, Carrier, Virtual Catalogue | | |
| 4.2 | **For each entity — what subtypes?** | Per-entity | YES |
|     | Common subtypes: HD (home delivery), CC (click & collect), SFS (ship from store), RETURN, DEFAULT | | |
| 4.3 | **Are any new entity subtypes needed?** Something that doesn't exist today? | Yes/No + describe | If applicable |
| 4.4 | **What custom data (attributes) needs to be stored on each entity?** | Per-entity open | Recommended |
|     | Probe: Set at creation or updated later? Where does the value come from (user input, calculated, external system)? What data type? | | |
| 4.5 | **How do entities relate in this feature?** | Open | If multi-entity |
|     | Probe: Does the order create fulfilments? Does a fulfilment update the order? Are there parent-child event chains? | | |

### Live Environment Discovery

After the user answers 4.1 and 4.2, **validate entity types against the live environment** before proceeding:

```
environment.discover include=workflows,locations,settings
```

For each entity type + subtype selected by the user, query workflows to confirm they exist:

```
workflow.transitions triggers=[{type: "<ENTITY>", subtype: "<SUBTYPE>", retailerId: "<ID>"}]
```

If a selected entity type has **no workflow** in the live environment:
- Flag it clearly: "No workflow found for `<ENTITY>::<SUBTYPE>`. This means a new workflow must be created."
- Ask the user to confirm: "Is this a new entity type that doesn't exist yet, or did you mean a different subtype?"

This prevents assumptions about existing workflows that don't actually exist, which would lead to invalid feature plans downstream.

Also query the rule registry:
```
plugin.list compact=true
```

Present findings to the user:

```
--- Environment Context ---

ORDER::HD workflow:
  Status: EXISTS (v12, 14 rulesets)
  Current statuses: CREATED → BOOKED → IN_PROGRESS → FULFILLED → COMPLETE
  User actions at CREATED: ConfirmOrder, CancelOrder

FULFILMENT::HD_WH workflow:
  Status: EXISTS (v8, 10 rulesets)
  Current statuses: CREATED → ASSIGNED → PICKING → PACKED → SHIPPED → DELIVERED

Available OOTB rules: 47 total (12 match ORDER, 9 match FULFILMENT)
Locations: 3 warehouses, 12 stores
Settings: 8 relevant (WEBHOOK_*, ALLOCATION_*)
---
```

This context helps the user in Phases 5-7. They can say "reuse the existing allocation" or "add a new status between PICKING and PACKED" instead of describing from scratch.

If no profile is connected, skip discovery and note:
```
Note: No Fluent profile connected. Environment discovery skipped.
The feature plan phase will discover the live environment.
```

#### 4.3 Validate Entity Orchestrability & Rubix-Enabled Status

After the user identifies entity types in their use cases, run a three-layer validation:

**Layer 1: Orchestrability Check (offline — no profile needed)**

Cross-reference each entity type against `knowledge/platform/domain-model.md` to confirm it is orchestrable (can have Rubix workflows):

Orchestrable entity types (can have workflows):
`ORDER`, `FULFILMENT`, `FULFILMENT_CHOICE`, `ARTICLE`, `RETURN_ORDER`, `RETURN_FULFILMENT`, `CONSIGNMENT`, `WAVE`, `LOCATION`, `CARRIER`, `CARRIER_CONSIGNMENT`, `BILLING_ACCOUNT`, `INVOICE`, `CREDIT_MEMO`, `PAYMENT`, `PRODUCT_CATALOGUE`, `CATEGORY`, `STANDARD_PRODUCT`, `VARIANT_PRODUCT`, `VIRTUAL_CATALOGUE`, `VIRTUAL_POSITION`, `INVENTORY_POSITION`, `INVENTORY_QUANTITY`, `FULFILMENT_OPTION`, `FULFILMENT_PLAN`, `FINANCIAL_TRANSACTION`, `CONTROL_GROUP`

Non-orchestrable entity types (NO workflows possible):
`CUSTOMER`, `USER`, `ROLE`, `PERMISSION`, `RETAILER`, `NETWORK`, `SETTING`

- If a non-orchestrable entity type is referenced AND the feature expects workflow-driven status transitions on it: **ERROR** — "Entity type `CUSTOMER` is not orchestrable. It cannot have Rubix workflows or status transitions. Your feature cannot use workflow-driven processing on this entity. Consider an alternative approach."
- If the entity type is not in either list: **WARN** — "Entity type `<TYPE>` is not in the known entity list. Verify it exists in the Fluent schema."

**Layer 2: Workflow Existence Check (requires connected profile)**

Query available workflows to check which entity type + subtype combos have deployed workflows:

```
workflow.list (MCP fluent-mcp-extn or fluent-mcp)
```

Extract unique entity types from workflow names (format: `ENTITY_TYPE::SUBTYPE`) and cross-reference:

- **If entity type is orchestrable but has NO workflow deployed:** WARN — "Entity type `WAVE::PICK_WAVE` is orchestrable but has no workflow in this environment. A new workflow must be created as part of this feature."
- **If all entity types have matching workflows:** Confirm: "All referenced entity types have active workflows."

**Layer 3: Rubix-Enabled Validation (requires connected profile)**

For each entity type + subtype that has a workflow, verify it is actively Rubix-enabled (has rulesets configured and transitions available):

```
workflow.transitions triggers=[{type: "<ENTITY>", subtype: "<SUBTYPE>", retailerId: "<ID>"}]
```

- **If transitions return empty despite workflow existing:** WARN — "Workflow for `WAVE::DEFAULT` exists but has no active transitions. The workflow may not be Rubix-enabled — it exists as a definition but has no rulesets or triggers configured. Verify the workflow is fully deployed with rulesets before building features that depend on it."
- **If transitions exist:** Confirm and show the current status graph:
  ```
  WAVE::DEFAULT workflow: Rubix-enabled
    Statuses: CREATED -> ASSIGNED -> IN_PROGRESS -> COMPLETE
    User actions at CREATED: AssignWave, CancelWave
  ```

Present the combined validation results:

```
--- Entity Orchestrability & Workflow Validation ---

ORDER::HD
  Orchestrable: YES
  Workflow: EXISTS (v12, 14 rulesets)
  Rubix-enabled: YES (transitions active)
  Statuses: CREATED -> BOOKED -> IN_PROGRESS -> FULFILLED -> COMPLETE

WAVE::PICK_WAVE
  Orchestrable: YES
  Workflow: NOT FOUND
  Rubix-enabled: N/A (no workflow)
  Action needed: New workflow must be created

CUSTOMER
  Orchestrable: NO
  Workflow: N/A (not orchestrable)
  Note: Cannot have workflow-driven status transitions
---
```

If no profile is connected, run only Layer 1 (orchestrability check) and note:
```
Note: No Fluent profile connected. Only orchestrability validated (offline).
Workflow existence and Rubix-enabled status will be checked during feature planning.
```

---

## Phase 5: Business Rules & Conditions

**Purpose:** Capture the decision logic.
**Feeds → Spec:** §7 Business Rules
**CONDITIONAL:** Skip if type = "Bug fix" or no decision points emerged in Phase 3.

| # | Question | Type | Required |
|---|----------|------|----------|
| 5.1 | **What conditions determine the flow?** List each decision point. | Open | YES |
|     | Probe: Based on order type? Location type? Item attributes? Customer segment? Monetary threshold? External data? | | |
| 5.2 | **Are there validation rules?** What must be true before proceeding? | Open | If applicable |
|     | Probe: Stock check? Address validation? Payment confirmed? Minimum order value? Weight/dimension limits? | | |
| 5.3 | **Are there calculations or allocations?** | Open | If applicable |
|     | Probe: Inventory allocation strategy? Fulfilment splitting logic? Location selection/routing? Shipping cost calculation? | | |
| 5.4 | **Are there approval or review gates?** | Yes/No + describe | If applicable |
|     | Probe: Manager approval? Fraud review? Quality check? | | |
| 5.5 | **Are there automated time-based actions?** | Yes/No + describe | If applicable |
|     | Examples: Auto-cancel after 2 hours, retry webhook every 15 min, daily reconciliation batch, SLA escalation | | |

**Entity-aware smart probing** (based on Phase 4 selections):
- ORDER selected → also ask about: payment validation, fraud check, order splitting, customer notification
- FULFILMENT selected → also ask about: pick/pack logic, carrier selection, label generation, partial fulfilment
- INVENTORY selected → also ask about: reservation strategy, safety stock, recount triggers, virtual position updates
- LOCATION selected → also ask about: capacity rules, operating hours, zone routing, store-vs-warehouse logic

---

## Phase 6: Integrations

**Purpose:** External system touchpoints.
**Feeds → Spec:** §8 Integrations
**CONDITIONAL:** Skip if no external systems identified in Phase 2. REQUIRED if type = "External integration".

| # | Question | Type | Required |
|---|----------|------|----------|
| 6.1 | **Which external systems interact with this feature?** | Multi-select + open | YES |
|     | Suggest: OMS, WMS, TMS/Carrier, ERP/Finance, Payment gateway, Notification service (email/SMS/push), Analytics/BI, Custom middleware, POS | | |
| 6.2 | **For each system — what direction is the data flow?** | Per-system | YES |
|     | Options: Fluent → External (outbound push), External → Fluent (inbound receive), Bidirectional | | |
| 6.3 | **For each system — what integration method?** | Per-system | YES |
|     | Options: Webhook (real-time push), REST API call (pull on demand), Batch file upload/download, Event/message queue, GraphQL mutation from external | | |
| 6.4 | **What happens when an external system is unavailable?** | Per-system | YES |
|     | Options: Retry automatically, Skip and continue, Fail the whole process, Queue for manual retry, Alert the operator | | |
| 6.5 | **Is there an existing integration to reuse or extend?** | Yes/No + describe | Recommended |

---

## Phase 7: User Interface & Actions

**Purpose:** What humans see and do in Fluent UI — both layout/pages and interactive actions.
**Feeds → Spec:** §9 User Actions, §9a UI / Frontend Requirements
**CONDITIONAL:** Skip if no human actors (backend-only feature).

### Part A: User Actions (buttons, events)

| # | Question | Type | Required |
|---|----------|------|----------|
| 7.1 | **What actions can users take?** List each button or action. | Open | YES |
|     | Probe: What's the button label? When is it available (at which status)? Does it need a confirmation dialog? | | |
| 7.2 | **Does the user fill in data when taking an action?** | Per-action | If applicable |
|     | Probe: What fields? Required or optional? Dropdowns, free text, date picker, number? | | |
| 7.3 | **Are there bulk actions?** Acting on multiple items at once? | Yes/No + describe | If applicable |
| 7.4 | **Should any actions be restricted by user role?** | Per-action | If applicable |
|     | Probe: Which roles can see/use each action? Admin only? Store manager? Any associate? | | |
|     | Probe: Is this platform-level (Transition API filters by permission) or application-level (rule checks `me.roles`)? | | |
|     | Probe: Does the backend rule need to know WHO clicked? If yes, we need `actionedBy` via `{{me.username}}`. | | |
|     | Cross-ref Phase 2.5 roles. If label-only roles identified there, ask: "Which tier/role gets which actions?" | | |

### Strict User Action Capture (Anti-Hallucination)

When gathering UI action requirements, capture this contract explicitly for each action:

1. **`eventName`** — exact event to send (do not infer from button label).
2. **Scope alignment** — intended `type`, `subtype`, and `flexType` branch where the action appears.
3. **`context[]` contract** — `label`, `type` (`PRIMARY` or `SECONDARY`), `modules[]`, optional `confirm`.
4. **`attributes[]` contract** — each field name, type, mandatory flag, and optional `source/options`.
5. **Module visibility** — if module-specific, confirm expected modules correspond to existing manifest settings (`fc.mystique.manifest.<module>` → `<module>`).
6. **Schema discipline** — do not introduce undocumented user-action keys.

If any of the above is unknown, mark it as an open question in the spec before handoff to `/fluent-feature-plan`.

### Part B: UI / Frontend Layout (pages, components, navigation)

**CONDITIONAL:** Skip if the feature has no visible UI impact (pure backend workflow changes, no new pages/columns/cards).

| # | Question | Type | Required |
|---|----------|------|----------|
| 7.5 | **Is this adding to an existing app or does it need a new one?** | Selection | YES (if UI work) |
|     | Options: Add to OMS App (existing), Add to Store App (existing), New app (new manifest root + navigation), Not sure | | |
|     | Probe: If new app — what's the audience? What entity types does it manage? If existing — which section/fragment? | | |
| 7.5a | **What pages or views need to exist?** | Open | YES (if UI work) |
|     | Probe: New list page? New detail page section? New tab? Modification to existing page? | | |
| 7.6 | **What information should be displayed and where?** | Per-page | YES (if UI work) |
|     | Probe for list pages: What columns? What filters? What search fields? Sort order? | | |
|     | Probe for detail pages: What cards/sections? What data in each card? What tabs? | | |
|     | Probe for both: Any conditional display (show/hide based on status, role, or data)? | | |
| 7.7 | **Where does this appear in navigation?** | Open | If new page |
|     | Probe: Sidebar menu entry? Tab within existing page? Link from another entity? Sub-route under existing page? | | |
| 7.8 | **Can standard Fluent components handle this, or is something custom needed?** | Selection | Recommended |
|     | Options: Standard OOTB components (lists, cards, tabs) / Needs custom visualization (map, chart, timeline, drag-drop) / Not sure | | |
| 7.9 | **Do you need any custom display formatting or template helpers?** | Selection | If custom SDK work |
|     | Probe: Custom currency/number formatting? Custom date display? Computed display values (e.g., weight with units, percentage calculations)? These map to TemplateRegistry helpers in an SDK project. Built-in helpers (currency, dateFormat, i18n, eq, hasRole) cover most cases — only ask if standard formatting is insufficient. | | |
| 7.10 | **Are there specific layout or UX requirements?** | Open | If applicable |
|     | Probe: Mobile responsive? Specific column widths? Inline editing? Real-time updates? Print-friendly? | | |
| 7.11 | **What data does each page need to fetch?** | Per-page | Recommended |
|      | Probe: Which entity types? Which fields (attributes, connections)? Any secondary queries (related entities, settings)? Pagination needed for lists? | | |
| 7.12 | **Are any pages or views restricted by role?** | Per-page | If applicable |
|      | Probe: Admin-only pages? Role-restricted actions within pages? Different views for different roles? | | |

**Smart probing based on Phase 4 entities:**
- ORDER selected → ask about: order list columns, order detail cards, order timeline, fulfilment section within order detail
- FULFILMENT selected → ask about: fulfilment list, pick/pack UI, carrier/tracking section, item verification
- LOCATION selected → ask about: location list, capacity dashboard, operating hours display
- INVENTORY selected → ask about: inventory grid, position counts, reservation display
- CREDIT_MEMO selected → ask about: appeasement list, amount display, line items, linked order reference

---

## Phase 8: Constraints & Risks

**Purpose:** Boundaries, assumptions, and concerns.
**Feeds → Spec:** §10 Constraints & Risks, §11 Assumptions
**RECOMMENDED:** Always ask briefly, even if answers are "none".

| # | Question | Type | Required |
|---|----------|------|----------|
| 8.1 | **Volume/scale expectations?** | Open | Recommended |
|     | Probe: Orders per day? Concurrent users? Inventory positions? Peak vs normal? | | |
| 8.2 | **Must this work alongside existing features without breaking them?** | Yes/No + describe | Recommended |
| 8.3 | **Is there data to migrate from an old process?** | Yes/No + describe | If applicable |
| 8.4 | **Are there known risks or concerns?** | Open | Recommended |
| 8.5 | **What assumptions are you making?** What do you believe is true but haven't confirmed? | Open | Recommended |

---

## Phase 9: Acceptance Criteria

**Purpose:** Testable success criteria for every use case.
**Feeds → Spec:** §13 Acceptance Criteria Summary

| # | Question | Type | Required |
|---|----------|------|----------|
| 9.1 | **For each use case — what's the acceptance criterion?** | Structured | YES |
|     | Guide the user into Given/When/Then format: | | |
|     | Given [precondition], When [action/event], Then [expected result] | | |
| 9.2 | **Which criteria are must-have vs nice-to-have?** | Categorize | YES |
| 9.3 | **Are there non-functional requirements?** | Open | If applicable |
|     | Probe: Response time expectations? Uptime requirements? Data retention? Audit trail needs? Compliance requirements? | | |

If the user struggles with Given/When/Then, help them by converting their natural language descriptions:
- "The order should be fulfilled within 4 hours" → Given an order in BOOKED status, When 4 hours elapse without fulfilment completion, Then escalate to operations team

---

## Phase 10: Review & Gap Analysis

**Purpose:** Automated completeness assessment and gap identification.

This phase is generated by the wizard, not asked to the user.

### Steps:

1. **Compile all gathered information** into the spec template sections (read `SPEC_TEMPLATE.md`)

1b. **Generate user journey diagrams** (§5a) from the gathered information:

   **What to generate (auto-derived from phases 2–5):**
   - **Actor Map table:** Built from §4 actors. Every actor from Phase 2 appears with type, interaction channel, and primary actions.
   - **User Journey Flow** (REQUIRED when 2+ actors OR 2+ use cases): Mermaid `flowchart TD` auto-generated from §5 use cases. Each use case path becomes a branch. Subgraphs group by actor. Decisions map to branching conditions. Annotate edges with UC references when covering multiple paths.
   - **Actor Interaction Sequence** (CONDITIONAL — 3+ actors): Mermaid `sequenceDiagram` showing timeline of handoffs. Derive from the step-by-step flows in UC-01 and UC-02.
   - **Decision Flow** (CONDITIONAL — 3+ branching conditions in §7): Mermaid `flowchart TD` showing the decision tree. Each diamond references a BR-XX rule.

   **Abstraction level:** Business language only — "Order placed", "Pick items", "Notify customer". NO workflow states, rulesets, GraphQL, or technical implementation. These diagrams are for stakeholder validation.

   **Validation:** Before writing any Mermaid block, validate syntax per `knowledge/mermaid-syntax-rules.md`. Common pitfalls: missing direction in flowcharts (`flowchart TD` not `flowchart`), spaces in node IDs, unquoted special characters.

   **Coverage check after generating:**
   - Every actor from §4 appears in at least one diagram
   - Every use case from §5 is traceable in at least one diagram
   - Decision points align with business rules from §7
   - If any UC or actor is missing → add them or note why excluded

   **Skip §5a ONLY when:** Single actor AND single use case AND no branching conditions (extremely rare).

2. **Score completeness** using this rubric:

| Phase | Weight | Scoring |
|-------|--------|---------|
| 1. Feature Identity | 15% | All REQUIRED answered = full marks |
| 2. Actors & Triggers | 10% | At least 1 actor + 1 trigger = full marks |
| 3. Use Cases | 15% | Happy path + 1 exception = full; happy path only = half |
| 3b. User Journey Diagrams | 5% | Journey flow + actor map = full; journey flow only = half; no diagrams = zero. 0% if N/A (single-actor, single-UC, no-branching) |
| 4. Entities & Data | 15% | All entities with subtypes + orchestrability validated + workflow status = full; entities listed without orchestrability check = half |
| 5. Business Rules | 15% | Decision points per UC branch = full; 0% if N/A |
| 6. Integrations | 5% | All systems identified = full; 0% if N/A |
| 7a. UI Actions | 3% | Actions per actor = full; 0% if N/A (backend-only) |
| 7b. UI/Frontend Layout | 2% | Pages + display + navigation = full; 0% if N/A (backend-only) |
| 8. Constraints | 5% | Risks or assumptions documented = full |
| 9. Acceptance Criteria | 10% | AC per use case = full; happy path only = half |

3. **Generate the recommendation:**
   - Score >= 75%: "Ready for `/fluent-feature-plan`"
   - Score 50-74%: "Can proceed but sections [X, Y] will rely on assumptions"
   - Score < 50%: "Address gaps [X, Y, Z] before proceeding"

4. **List open questions** (things that came up but weren't answered)

5. **List assumptions** (things inferred from context but not explicitly confirmed)

6. **Build the traceability matrix** (UC → entities → rules → integrations → actions)

7. **Generate feature slug** from the feature title (Phase 1, question 1.1):

   **Slug generation rules:**
   - Take the one-sentence feature description from Q1.1
   - Extract 2-4 key nouns/verbs (drop articles, prepositions, generic words like "feature", "flow", "process")
   - Convert to lowercase kebab-case
   - Max 4 words, no dates, no skill prefixes

   **Examples:**
   | Feature Description | Generated Slug |
   |---|---|
   | "Curbside pickup for click and collect orders" | `curbside-pickup` |
   | "Return order processing with refund automation" | `return-order-refund` |
   | "Multi-location inventory allocation" | `multi-location-allocation` |
   | "Send SMS notifications when order ships" | `sms-ship-notify` |

   **Present to user for confirmation:**
   ```
   Suggested feature slug: `curbside-pickup`
   This will create: accounts/<PROFILE>/features/curbside-pickup/

   Accept this slug or provide a different one? [Enter to accept]
   ```

   If user provides a different slug, validate it:
   - Must be lowercase kebab-case
   - Max 4 words
   - No dates, no skill prefixes
   - If invalid, explain the rules and re-suggest

   **Check for collisions:**
   ```bash
   ls accounts/<PROFILE>/features/
   ```
   If the slug already exists, warn: "Feature `<slug>` already exists (status: <status>). Options: (1) Update the existing spec (2) Choose a different slug"

8. **Write the spec to file:**
   ```
   accounts/<PROFILE>/features/<slug>/spec.md
   ```
   Use the SPEC_TEMPLATE.md format. Set status = DRAFT.

9. **Embed visual mocks** (if available):
   Check `features/<slug>/assets/` for before/after screenshots (saved by `/fluent-ui-record`, `/fluent-mystique-preview`, `/fluent-ui-test`). If found, insert a "### Visual Mocks" subsection in §9a with relative-path image embeds:
   ```markdown
   ### Visual Mocks (Live OMS Injection)

   **Before** — [current page state]:

   ![Before](assets/before.png)

   **After** — [proposed change]:

   ![After](assets/after.png)

   > [How the mock was produced]
   ```
   The feature dashboard generator resolves these relative paths to base64 data URIs at build time, so they render inline in the self-contained HTML dashboard. If no mocks exist, include the empty "### Visual Mocks" template from SPEC_TEMPLATE.md (conditional — only if §9a exists).

---

### Phase 10b: Self-Critique Loop (Automated)

**The full protocol, rubric, critic prompts, runtime adaptation table, guardrails, and deliberation log format live in `CRITIQUE_PROTOCOL.md`. Read that file and follow it exactly.**

After writing the initial spec, refine it through automated adversarial review before presenting to the user. This phase is fully automated — no user interaction. All user Q&A (Phases 1–9) is complete.

#### Orchestration Steps (Claude Code)

1. **Read** `CRITIQUE_PROTOCOL.md` (sibling file)
2. **Pre-Critique Feedback Check** — Read `accounts/<PROFILE>/feedback/fluent-use-case-discover.jsonl` (last 10 records). Extract top 3 pitfalls from FAILURE/USER_CORRECTED outcomes. Build `{feedback_pitfalls}` string (empty if no records).
3. **Assess complexity** — Count entity types in §6, use cases in §5, integrations in §8. If HIGH complexity (4+ entities OR 6+ use cases OR 3+ integrations), set `maxRounds=5` and enable multi-critic. Otherwise `maxRounds=3`, single critic.
4. **Build Round 1 critic prompt** — From CRITIQUE_PROTOCOL.md template, inject: `{spec_path}`, knowledge file paths (if they exist), `{feedback_pitfalls}`.
5. **Spawn critic(s):**
   - **Standard:** `Agent(subagent_type: "general-purpose", name: "spec-critic-r1", prompt: <round1_prompt>)`
   - **Multi-critic (HIGH):** Spawn TWO agents in parallel — `spec-platform-critic-r1` (CR-1, CR-6) and `spec-reqs-critic-r1` (CR-2, CR-3, CR-4, CR-5). Merge findings.
6. **Evaluate findings** — For each finding, apply verdict: ACCEPTED (apply fix to spec) / REJECTED (log reason) / DEFERRED (log for user).
7. **Convergence check** — If 0 new CRITICAL/HIGH findings → exit loop. Otherwise continue.
8. **Rounds 2+** — Build round N prompt from CRITIQUE_PROTOCOL.md template, inject prior deliberation context. Spawn critic(s) again. Apply same evaluation. If a CRITICAL finding is rejected twice with new evidence both times → mark ESCALATED.
9. **Append deliberation log** to spec file (between Traceability Matrix and Recommendation).
10. **Build user-facing summary** — Key changes, deferred items, escalated items.

#### Revision Mode

When a spec is revised after initial approval, re-run critique on CHANGED sections only. Max 2 rounds. Critic receives the diff + original deliberation log.

#### Fallback (Non-Claude-Code runtimes)

If no Agent tool is available, perform inline self-critique using the rubric in CRITIQUE_PROTOCOL.md. Run all rounds inline.

**After Phase 10b completes**, continue to step 9 with the refined spec. Include the user-facing summary when presenting (e.g., "3 rounds of self-critique: 5 findings, 3 applied, 1 rejected, 1 deferred").

---

9. **Present the spec to the user** with completeness score, recommendation, and a summary of the deliberation log (e.g., "3 rounds of self-critique: 5 findings, 3 applied, 1 rejected, 1 deferred").

10. **Update status.json** — set `status: "PLANNING"`, `spec: "DRAFT"`, `next: "/fluent-feature-plan"`, and write a `summary` field: one sentence (≤160 chars) describing what the feature does and why. This is the canonical description shown in the dashboard — write it to be understood without reading the spec. Example: `"Add role-based approval for appeasements — agents submit requests, supervisors approve or reject before a credit memo is issued."` Also initialize gate fields: `build: null`, `deploy: null`, `test: null` (these are updated by build, deploy, and test skills respectively as the feature progresses).

    **Write provenance** — record which skill and mode produced this artifact:
    ```json
    "provenance": {
      "spec": {
        "skill": "fluent-use-case-discover",
        "mode": "A | B | C",
        "timestamp": "<ISO-8601>",
        "completeness": <score>,
        "critiqueRounds": <N>,
        "entityValidation": "full | orchestrability-only | skipped"
      }
    }
    ```
    - `mode`: "A" (interactive wizard), "B" (document analysis), or "C" (structured PRD template)
    - `completeness`: the Phase 10 completeness score (0-100)
    - `critiqueRounds`: how many self-critique rounds ran in Phase 10b
    - `entityValidation`: "full" (all 3 layers ran), "orchestrability-only" (no profile connected), or "skipped" (no entities identified)

    This provenance is consumed by `/fluent-feature-status` for dashboard display and by `/fluent-session export` for compliance trails. It persists across sessions — unlike session-scoped tracking, this lives with the feature.

**MANDATORY REVIEW GATE — STOP HERE AND WAIT:**

The agent MUST stop and wait for explicit user approval before proceeding. This gate is non-negotiable.

1. Present the spec to the user with the completeness score
2. Ask: *"Please review this Business Spec. When you're satisfied, say 'approved' and I'll proceed to feature planning."*
3. **WAIT.** Do not proceed to `/fluent-feature-plan` or any other skill.
4. If the user asks questions → answer them, keep waiting
5. If the user requests changes → apply them, re-present, keep waiting
6. Only when the user explicitly says "approved", "looks good", "go ahead", or similar affirmative:
   - Update `status.json` to `spec: "APPROVED"` (also write/update `summary` if not already set)
   - Emit: `→ READY: accounts/<PROFILE>/features/<slug>/spec.md`
   - Assess complexity: if spec describes 8+ rules, 3+ workflows, or 3+ entity types, recommend phasing first:
     `→ NEXT: /fluent-feature-phase --feature <slug>` *(complex — phase before planning)*
   - Otherwise recommend: `→ NEXT: /fluent-feature-plan --feature <slug>`
7. **NEVER auto-advance** past this gate. The spec approval decision belongs to the user.

---

## Mode B: Document Analysis Flow

When analyzing an existing document:

### Step B.1: Read the Document
Read the file at the provided path, or accept pasted content.

### Step B.2: Extract Into Template
Map document content to spec sections:
- Look for problem statements, objectives, goals → §1, §2
- Look for actor/role descriptions, trigger events → §4
- Look for user stories, scenarios, workflows → §5
- Look for flow diagrams, process maps, swimlanes, sequence flows → §5a (extract actors, steps, decision points)
- Look for entity references (order, fulfilment, inventory) → §6
- Look for system names, APIs, webhooks → §8
- Look for acceptance criteria, test cases → §13

### Step B.3: Score Completeness
Apply the same 10-phase scoring rubric. Identify which phases have:
- **Full coverage** (enough detail extracted)
- **Partial coverage** (some info but gaps)
- **No coverage** (phase not addressed in document)

### Step B.4: Present Gap Report
```
Document Analysis: "PRD - Curbside Pickup v2.docx"

Extracted:
  Phase 1 (Identity):       FULL    — clear problem statement and success metrics
  Phase 2 (Actors):         FULL    — store associate + customer identified
  Phase 3 (Use Cases):      PARTIAL — happy path clear, no exception scenarios
  Phase 3b (Journey Diags): NONE    — no flow diagrams found in document
  Phase 4 (Entities):       PARTIAL — mentions orders and fulfilments, no subtypes
  Phase 5 (Rules):          NONE    — no business rules documented
  Phase 6 (Integrations):   PARTIAL — mentions POS but no failure handling
  Phase 7 (UI Actions):     NONE    — no UI requirements
  Phase 8 (Constraints):    PARTIAL — volume mentioned, no risks
  Phase 9 (Acceptance):     PARTIAL — 2 criteria, need more

Completeness: 48% (Partial)
Gaps requiring follow-up: Phases 3 (exceptions), 3b (diagrams), 4 (subtypes), 5 (rules), 7 (UI), 9 (AC)
```

### Step B.5: Interactive Follow-Up
Enter interactive mode ONLY for phases with NONE or PARTIAL coverage. Ask targeted questions — not the full phase, just what's missing.

### Step B.5b: Generate User Journey Diagrams
After interactive follow-up, generate §5a diagrams using the same rules as Phase 3b (Mode A):
- Build Actor Map from §4 actors
- Generate User Journey Flow (flowchart TD) from §5 use cases — REQUIRED when 2+ actors OR 2+ use cases
- Generate Actor Interaction Sequence (sequenceDiagram) if 3+ actors collaborate
- Generate Decision Flow (flowchart TD) if 3+ branching conditions exist in §7

If the source document contained flow diagrams or process maps, use them as a starting point — translate into Mermaid syntax and validate with `knowledge/mermaid-syntax-rules.md` rules. Ensure business language only (no technical implementation details).

### Step B.6: Produce Spec
Same output as Mode A — complete Business Spec written to file, including §5a diagrams.

---

## Output Conventions

### File Path
```
accounts/<PROFILE>/features/<slug>/spec.md
```
- `<PROFILE>` — active Fluent CLI profile
- `<slug>` — auto-generated from the feature title in Phase 10 step 7 and confirmed by the user. Rules: lowercase kebab-case, 2-4 words, no dates, no skill prefixes. The slug is IMMUTABLE after spec approval — changing it would break all downstream references.

If no profile is connected, use:
```
.fluent-ai-skills/features/<slug>/spec.md
```

### Handoff to Feature Plan

**Only after the user has explicitly approved the spec**, recommend:
```
/fluent-feature-plan --feature <slug>
```
The agent MUST NOT auto-invoke `/fluent-feature-plan` — present the recommendation and let the user decide when to proceed.

The feature plan skill reads the spec and maps sections:

| Spec Section | Feature Plan Section(s) |
|---|---|
| §1 Problem Statement | → §1 Business Context |
| §2 Feature Summary | → §1 Business Context, §2 Scope |
| §3 Scope | → §2 Scope |
| §4 Actors & Triggers | → §3 Architecture, §16 Test Plan |
| §5 Use Cases | → §4 Workflows, §5 Statuses, §6 Rulesets, §16 Test Plan |
| §5a User Journey Diagrams | → §3 Architecture & Diagrams (refined from business-level to technical-level) |
| §6 Entity Model | → §4 Workflows, §13 GraphQL, §14 Cross-Entity |
| §7 Business Rules | → §6 Rulesets, §7 Rules Inventory, §8 Detailed Design |
| §8 Integrations | → §11 Webhooks, §9 Settings, §12 Scheduled Events |
| §9 User Actions | → §4 Workflows (user actions), §5 Statuses |
| §9a UI / Frontend Requirements | → §10 UI / Manifest Artifacts |
| §10 Constraints & Risks | → §2 Scope, §16 Risks, §19 Rollback |
| §11 Assumptions | → §16 Risks |
| §12 Open Questions | → blocks feature plan until resolved |
| §13 Acceptance Criteria | → §17 Test Plan |
| Traceability Matrix | → §15 Files, §18 Deployment |

---

## Planning Gate

This skill has a **MANDATORY REVIEW GATE** (not a Planning Gate in the implementation sense). It does not modify code or Fluent environments — it produces a Business Spec document. At the end of Phase 10, the spec must receive explicit user approval before any handoff occurs. The spec approval is both this skill's final gate and a mandatory prerequisite for `/fluent-feature-plan`'s Pre-flight Requirements Check.

## Post-Execution: Feedback Capture

After completing this skill (whether success or failure), write a feedback record:

1. **Classify outcome:** `SUCCESS` (completed cleanly), `PARTIAL_SUCCESS` (completed after fixing issues), `FAILURE` (could not complete), `BLOCKED` (prereq missing), `USER_CORRECTED` (user overrode approach)
2. **Build record:** Create a `feedback-record-v1` JSON object with:
   - `skill`: `"fluent-use-case-discover"`
   - `feature`: feature slug if applicable, null otherwise
   - `phases`: trace of each phase with PASS/FAIL/SKIP
   - `learnings`: any gotchas discovered during execution
   - `userCorrections`: any corrections the user provided
3. **Redact secrets:** Strip tokens, passwords, API keys. Keep business identifiers.
4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-use-case-discover.jsonl`
5. **Update** `accounts/<PROFILE>/feedback/index.json` counters (create with `mkdir -p` if missing)

**Skip capture if:** The execution was trivially simple (e.g., user asked a question, no actual write operation happened).

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

_(No promoted learnings yet.)_

<!-- end feedback-promoted -->
