@fluentcommerce/ai-skills 0.2.0 → 0.3.0

package/content/dev/skills/fluent-use-case-discover/SKILL.md

@@ -1,471 +1,593 @@
----
-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 and document analysis mode. Triggers on "discover use case", "gather requirements", "business spec", "use case discovery", "what are we building", "requirements gathering", "spec wizard", "analyze requirements".
-user-invocable: true
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep
-argument-hint: [--analyze <path-or-paste>] [--profile PROFILE] [--retailer RETAILER_REF]
----
-
-# 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.
-
-## 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
-
-## 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 10 phases of structured questions, each building on previous answers. Uses progressive disclosure — only asks questions relevant to the feature type.
-
-### Mode B: Document Analysis
-
-Run with `/fluent-use-case-discover --analyze <path>` or when the user pastes/provides an existing requirements document (PRD, 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".
-
----
-
-## Phase 0: Mode Detection & Setup
-
-**Detect mode:**
-- If `--analyze` flag or user provided a 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 existing specs:**
-```bash
-ls accounts/<PROFILE>/analysis/specs/
-```
-If related specs exist → show to user, ask if this is an update or new spec.
-
----
-
-## 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. Confirm with the user before proceeding.
-
----
-
-## 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: Admin Console, Service Point (store app), Fluent OMS App, No UI (backend only) | | |
-| 2.4 | **Is this feature retailer-specific or account-wide?** | Selection | YES |
-|     | Options: Single retailer, All retailers (account-wide) | | |
-
-**WAIT gate:** Present actors + 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>
-```
-
-**WAIT gate:** Present the use case list. Ask: "Are these use cases 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, query the connected Fluent environment:
-
-```
-environment.discover include=workflows,locations,settings
-workflow.transitions triggers=[{type: "<ENTITY>", subtype: "<SUBTYPE>", retailerId: "<ID>"}]
-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.
-```
-
----
-
-## 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.
-**Feeds → Spec:** §9 User Actions
-**CONDITIONAL:** Skip if no human actors (backend-only feature).
-
-| # | 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?** | Yes/No + describe | If applicable |
-|     | Probe: Which roles can see/use each action? Admin only? Store manager? Any associate? | | |
-
----
-
-## 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`)
-
-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 | 20% | Happy path + 1 exception = full; happy path only = half |
-| 4. Entities & Data | 15% | All entities identified with subtypes = full |
-| 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 |
-| 7. UI Actions | 5% | Actions per actor = 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. **Write the spec to file:**
-   ```
-   accounts/<PROFILE>/analysis/specs/<YYYY-MM-DD>-<slug>.md
-   ```
-   Use the SPEC_TEMPLATE.md format. Set status = DRAFT.
-
-8. **Present the spec to the user** with completeness score and recommendation.
-
-**WAIT gate:** Ask the user to review the spec. When they approve, update status to APPROVED.
-
----
-
-## 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 user stories, scenarios, workflows → §5
-- Look for system names, APIs, webhooks → §8
-- Look for acceptance criteria, test cases → §13
-- Look for entity references (order, fulfilment, inventory) → §6
-
-### 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 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: 52% (Partial)
-Gaps requiring follow-up: Phases 3 (exceptions), 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.6: Produce Spec
-Same output as Mode A — complete Business Spec written to file.
-
----
-
-## Output Conventions
-
-### File Path
-```
-accounts/<PROFILE>/analysis/specs/<YYYY-MM-DD>-<slug>.md
-```
-- `<PROFILE>` — active Fluent CLI profile
-- `<YYYY-MM-DD>` — today's date
-- `<slug>` — 2-4 word kebab-case from feature title (e.g., `curbside-pickup`, `return-order-flow`, `wms-integration`)
-
-If no profile is connected, use:
-```
-.fluent-ai-skills/specs/<YYYY-MM-DD>-<slug>.md
-```
-
-### Handoff to Feature Plan
-
-When the spec is APPROVED, the user can run:
-```
-/fluent-feature-plan --spec accounts/<PROFILE>/analysis/specs/<YYYY-MM-DD>-<slug>.md
-```
-
-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 |
-| §6 Entity Model | → §4 Workflows, §12 GraphQL, §13 Cross-Entity |
-| §7 Business Rules | → §6 Rulesets, §7 Rules Inventory, §8 Detailed Design |
-| §8 Integrations | → §10 Webhooks, §9 Settings, §11 Scheduled Events |
-| §9 User Actions | → §4 Workflows (user actions), §5 Statuses |
-| §10 Constraints & Risks | → §2 Scope, §15 Risks, §18 Rollback |
-| §11 Assumptions | → §15 Risks |
-| §12 Open Questions | → blocks feature plan until resolved |
-| §13 Acceptance Criteria | → §16 Test Plan |
-| Traceability Matrix | → §14 Files, §17 Deployment |
-
----
-
-## Planning Gate
-
-This skill does NOT modify code or Fluent environments — it only produces a spec document. No Planning Gate is required for this skill itself. However, the spec it produces is a prerequisite for the Planning Gate in `/fluent-feature-plan`.
+---
+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 and document analysis mode. Triggers on "discover use case", "gather requirements", "business spec", "use case discovery", "what are we building", "requirements gathering", "spec wizard", "analyze requirements".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: [--analyze <path-or-paste>] [--profile PROFILE] [--retailer RETAILER_REF]
+---
+
+# 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.
+
+## 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
+
+## Progress
+
+Emit this block at each phase transition to show progress (Mode A — interactive wizard):
+
+```
+▸ /fluent-use-case-discover [1/11]
+  ✓ Mode detection           → Feature identity
+  ○ Actors & triggers        ○ User journey
+  ○ Entities & data          ○ Business rules
+  ○ Integrations             ○ UI & actions
+  ○ Constraints & risks      ○ Acceptance criteria
+  ○ Review & gap analysis
+```
+
+Update the block as each phase completes — mark completed phases with `✓`, the active phase with `→`, and remaining phases with `○`. Replace `[1/11]` 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 10 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 (PRD, 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".
+
+---
+
+## Phase 0: Mode Detection & Setup
+
+**Detect mode:**
+- If `--analyze` flag or user provided a 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 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: Admin Console, Service Point (store app), Fluent OMS App, No UI (backend only) | | |
+| 2.4 | **Is this feature retailer-specific or account-wide?** | Selection | YES |
+|     | Options: Single retailer, All retailers (account-wide) | | |
+
+**WAIT gate:** Present actors + 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>
+```
+
+**WAIT gate:** Present the use case list. Ask: "Are these use cases 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 Types
+
+After the user identifies entity types in their use cases (ORDER, FULFILMENT, ARTICLE, etc.), validate they exist in the connected environment:
+
+1. Query available workflows to extract supported entity types:
+   ```
+   workflow.list (MCP fluent-mcp-extn or fluent-mcp)
+   ```
+2. Extract unique entity types from workflow names (format: `ENTITY_TYPE::SUBTYPE`)
+3. Cross-reference against entity types mentioned in the user's use cases
+4. **If an entity type has NO matching workflows:** WARN the user: "Entity type `<TYPE>` has no workflows in this environment. This may indicate a missing module or incorrect entity type. Verify before proceeding."
+5. **If all entity types match:** Confirm: "All referenced entity types have active workflows."
+
+This prevents use cases from referencing entity types that don't exist in the target environment, which would cause downstream skill failures during workflow building and deployment.
+
+---
+
+## 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.
+**Feeds → Spec:** §9 User Actions
+**CONDITIONAL:** Skip if no human actors (backend-only feature).
+
+| # | 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?** | Yes/No + describe | If applicable |
+|     | Probe: Which roles can see/use each action? Admin only? Store manager? Any associate? | | |
+
+### 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 are valid against `fc.mystique.apps`.
+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`.
+
+---
+
+## 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`)
+
+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 | 20% | Happy path + 1 exception = full; happy path only = half |
+| 4. Entities & Data | 15% | All entities identified with subtypes = full |
+| 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 |
+| 7. UI Actions | 5% | Actions per actor = 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. **Present the spec to the user** with completeness score and recommendation.
+
+10. **Update status.json** — set `status: "PLANNING"`, `spec: "DRAFT"`, `next: "/fluent-feature-plan"`.
+
+**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"`
+   - Emit: `→ READY: accounts/<PROFILE>/features/<slug>/spec.md`
+   - 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 user stories, scenarios, workflows → §5
+- Look for system names, APIs, webhooks → §8
+- Look for acceptance criteria, test cases → §13
+- Look for entity references (order, fulfilment, inventory) → §6
+
+### 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 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: 52% (Partial)
+Gaps requiring follow-up: Phases 3 (exceptions), 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.6: Produce Spec
+Same output as Mode A — complete Business Spec written to file.
+
+---
+
+## 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 |
+| §6 Entity Model | → §4 Workflows, §12 GraphQL, §13 Cross-Entity |
+| §7 Business Rules | → §6 Rulesets, §7 Rules Inventory, §8 Detailed Design |
+| §8 Integrations | → §10 Webhooks, §9 Settings, §11 Scheduled Events |
+| §9 User Actions | → §4 Workflows (user actions), §5 Statuses |
+| §10 Constraints & Risks | → §2 Scope, §15 Risks, §18 Rollback |
+| §11 Assumptions | → §15 Risks |
+| §12 Open Questions | → blocks feature plan until resolved |
+| §13 Acceptance Criteria | → §16 Test Plan |
+| Traceability Matrix | → §14 Files, §17 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.