# What Can You Do With Fluent AI Skills?

> [!CAUTION]
> **🧪 EXPERIMENTAL — LABS PROJECT**
> This package is not production-ready. No stability guarantees, no support, no warranty. See [README](../README.md) for full disclaimer.

A scenario-based guide to everything your AI assistant can do after installing `@fluentcommerce/ai-skills`. Each scenario shows what to say (natural language or slash command), what happens, and what you get back.

> **Prerequisites:** Skills installed (`npx @fluentcommerce/ai-skills install`), MCP servers configured (`mcp-setup --profile YOUR_PROFILE`), and workspace connected (`/fluent-connect`).

> **New here?** Start with the [Getting Started Guide](getting-started.md) for a step-by-step walkthrough before diving into specific scenarios.

---

## Personas

Not sure where to start? Find your persona and jump to the scenarios that matter most to you. See the [README — Who Is This For?](../README.md#who-is-this-for) for full persona descriptions with example prompts.

| Persona | Start here | Then explore |
|---|---|---|
| 🚀 **New Starter** — just joined, need to understand | [Understand what's built](#scenario-1-i-just-joined-the-project--help-me-understand-whats-built), [Map implementation](#scenario-17-map-whats-been-built-on-this-account) | [Workspace tree](#scenario-21-show-me-the-workspace-structure), [Feature status](#scenario-18-check-feature-status-across-the-workspace) |
| 🔨 **Builder** — implementing features daily | [Gather requirements](#scenario-12-gather-requirements-before-building), [Build feature](#scenario-3-build-a-complete-feature-end-to-end), [Deploy](#scenario-8-deploy-a-workflow-change-safely) | [Preview UI](#scenario-20-preview-what-the-ui-will-look-like-before-building), [Data module](#scenario-16-create-a-data-module-no-java) |
| 🔍 **Investigator** — debugging production issues | [Debug stuck order](#scenario-2-an-order-is-stuck--help-me-debug-it), [Monitor events](#scenario-6-monitor-production-event-processing) | [Rollback](#scenario-19-roll-back-a-failed-deployment), [Event model](#scenario-7-i-need-to-understand-the-event-model) |
| 📋 **Reviewer** — auditing and go-live readiness | [Go-live readiness](#scenario-4-were-going-live-next-week--are-we-ready), [Cross-entity deps](#scenario-13-validate-cross-entity-workflow-dependencies) | [Session audit](#scenario-15-audit-what-happened-in-this-session), [Feature status](#scenario-18-check-feature-status-across-the-workspace) |

---

## Quick Reference: "I want to..."

| I want to... | Say this | Skill | Persona |
|---|---|---|---|
| Connect to a Fluent account | "Set up my workspace" | `/fluent-connect` | 🚀 |
| Create or switch CLI profiles | "Create a profile for production" | `/fluent-profile` | 🚀 🔨 |
| Understand how a feature works | "Explain how Home Delivery works" | `/fluent-feature-explain` | 🚀 📋 |
| Gather requirements for a feature | "Help me define use cases for curbside pickup" | `/fluent-use-case-discover` | 🔨 |
| Plan a multi-artifact feature | "Plan the curbside pickup feature" | `/fluent-feature-plan` | 🔨 |
| Debug why an order is stuck | "Why is order HD-001 stuck in BOOKED?" | `/fluent-trace` | 🔍 |
| Build a new workflow from scratch | "Build an ORDER::RETURN workflow" | `/fluent-workflow-builder` | 🔨 |
| Analyze workflow structure | "Analyze ORDER::HD for orphaned rulesets" | `/fluent-workflow-analyzer` | 🔍 📋 |
| Map cross-entity dependencies | "Show me how ORDER::HD connects to FULFILMENT workflows" | `/fluent-connection-analysis` | 📋 |
| Scaffold a new Java rule | "Create a rule called ValidateReturnWindow" | `/fluent-rule-scaffold` | 🔨 |
| Create a new extension module | "Scaffold a new module called my-returns" | `/fluent-module-scaffold` | 🔨 |
| Create a data-only module | "Create a data module for reference data" | `/fluent-data-module-scaffold` | 🔨 |
| Onboard existing source into module format | "Refactor this code into a Fluent module" | `/fluent-source-onboard` | 🔨 |
| Check module health | "What modules are deployed? Are they valid?" | `/fluent-module-validate` | 📋 |
| Analyze custom plugin source | "Analyze the custom code for this account" | `/fluent-custom-code` | 🚀 📋 |
| Build and package a module | "Build the my-extensions module" | `/fluent-build` | 🔨 |
| Bump module version | "Bump the module version to 1.4.0" | `/fluent-version-manage` | 🔨 |
| Run quality gates before deploying | "Run pre-deploy checks for my-extensions" | `/fluent-pre-deploy-check` | 🔨 |
| Deploy a module | "Deploy my extension module to MY_RETAILER" | `/fluent-module-deploy` | 🔨 |
| Deploy a workflow | "Deploy ORDER::HD to MY_RETAILER" | `/fluent-workflow-deploy` | 🔨 |
| Run an end-to-end test | "Run an E2E test of the HD order flow" | `/fluent-e2e-test` | 🔨 |
| Create test data | "Create a test HD order" | `/fluent-test-data` | 🔨 🔍 |
| Check if we're ready for go-live | "Run an RFL assessment" | `/fluent-rfl-assess` | 📋 |
| Audit settings | "What settings are missing for ORDER::HD?" | `/fluent-settings` | 🔨 📋 |
| Create a location or network | "Set up a warehouse location for testing" | `/fluent-retailer-config` | 🔨 |
| Monitor event health | "Show me event failure rates for the last hour" | `/fluent-system-monitoring` | 🔍 |
| See what actions are available | "What actions can I take on an ORDER in BOOKED status?" | `/fluent-transition-api` | 🔍 🔨 |
| Understand the event model | "How does event routing work in Fluent?" | `/fluent-event-api` | 🚀 |
| Batch ingest data | "Create a batch ingestion job for inventory positions" | `/fluent-job-batch` | 🔨 |
| Set up a new account | "Bootstrap a new Fluent account" | `/fluent-bootstrap` | 🔨 |
| Decompose a scope document | "Break this scope doc into tasks with dependencies" | `/fluent-scope-decompose` | 📋 🔨 |
| Understand sourcing configuration | "How does sourcing work? What criteria are available?" | `/fluent-sourcing` | 🚀 🔨 |
| Configure a sourcing profile | "Create an HD sourcing profile with distance + stock criteria" | `/fluent-sourcing` | 🔨 |
| Debug sourcing decisions | "Why was this location selected for the order?" | `/fluent-sourcing` → `/fluent-trace` | 🔍 |
| Audit what skills and tools ran | "What skills ran this session? Show the decision chain" | `/fluent-session` | 📋 |
| Export audit trail for CI/CD | "Export a JSON audit trail with full provenance" | `/fluent-session export` | 📋 |
| Map what's been built on an account | "What has been built here? Give me a feature inventory" | `/fluent-implementation-map` | 🚀 📋 |
| Check feature status dashboard | "What features are in progress? Show the dashboard" | `/fluent-feature-status` | 📋 🔨 |
| Archive a completed feature | "Archive the return-order feature" | `/fluent-archive` | 🔨 |
| Roll back a deployment | "Roll back ORDER::HD to the previous version" | `/fluent-rollback` | 🔍 🔨 |
| See the workspace structure | "Show me the workspace tree" | `/fluent-workspace-tree` | 🚀 |
| Preview a UI change before building | "Preview what the appeasement card looks like in OMS" | `/fluent-mystique-preview` | 🔨 |
| Build a Mystique UI page | "Build an order detail page" | `/fluent-mystique-builder` | 🔨 |
| Validate a manifest before deploying | "Validate the admin manifest" | `/fluent-mystique-validate` | 🔨 📋 |
| Scaffold a custom SDK component | "Create a custom order tracker component" | `/fluent-mystique-scaffold` | 🔨 |
| Build an SDK component project | "Build the mystique-appeasement project" | `/fluent-frontend-build` | 🔨 |
| Review SDK code quality | "Review the frontend code for issues" | `/fluent-frontend-review` |
| Generate SDK project README | "Generate a readme for the component project" | `/fluent-frontend-readme` |
| Analyze an existing manifest | "What components are used in the admin app?" | `/fluent-mystique-analyze` |
| Verify a deployed page in the browser | "Check that the OMS orders page loads correctly" | `/fluent-ui-test` |
| Record UI walkthrough with annotations | "Record before/after screenshots of the appeasement feature" | `/fluent-ui-record` |
| Set up project knowledge | "Initialize knowledge for this project" | `/fluent-knowledge-init` |
| View skill execution feedback | "Show me the feedback dashboard" | `/fluent-feedback` |
| Build a full-stack feature (backend + UI) | "Build order tracking with a dashboard" | `/fluent-feature-plan` → backend → frontend |

---

## How It Works: The Feature Lifecycle

For the full walkthrough of the feature lifecycle — directory structure, `status.json` fields, step-by-step build sequence, the approval gate, and workspace layout — see [getting-started.md § Building a Feature End-to-End](getting-started.md#5-building-a-feature-end-to-end-the-full-lifecycle).

**Quick summary:** Every feature lives under `accounts/<PROFILE>/features/<slug>/` with `status.json` (lifecycle tracker), `spec.md` (business requirements), `plan.md` (implementation plan), and optionally `architecture.md` (reverse-engineered docs). The AI reads `status.json` to resume where you left off across sessions.

### Reading an Existing Feature (No Plan Needed)

If you want to **understand** a feature rather than **build** one, the AI produces an architecture document instead:

```
Explain how Home Delivery works end-to-end
```

This creates `features/home-delivery/architecture.md` — a read-only document with state machine diagrams, cross-entity sequence diagrams, rules tables, and settings dependencies. No planning gate, no implementation.

---

## Scenario 1: "I just joined the project — help me understand what's built"

**Situation:** You're a new developer onboarding onto an existing Fluent Commerce implementation. You need to understand the workflows, rules, and integrations before making changes.

**Step 1: Connect to the account**
```
/fluent-connect
```
The wizard discovers your CLI profiles, selects the retailer, downloads all workflows, scans for source code, decompiles any JARs, and reports what's available.

**Step 2: Explain the main feature**
```
Explain how the Home Delivery order flow works end-to-end
```
This produces a **Feature Architecture Document** with:
- State machine diagrams (Mermaid) for every entity (ORDER, FULFILMENT_CHOICE, FULFILMENT)
- Cross-entity sequence diagram showing event propagation
- Rules & logic table explaining what each ruleset does
- Settings dependencies with current values
- Integration points (webhooks, scheduled events)
- Analysis confidence levels (HIGH/MEDIUM/LOW per rule)

Output saved to `accounts/<PROFILE>/features/home-delivery/architecture.md`.

> **Artifact:** `accounts/<PROFILE>/features/home-delivery/architecture.md` — a Feature Architecture Document you can share with your team. Includes Mermaid diagrams that render in GitHub, Confluence, and most markdown viewers.

**Step 3: Analyze specific workflows**
```
Analyze ORDER::HD for orphaned rulesets and trigger coverage
```
Returns a status graph, event chains, process flow classification, and any structural issues.

**Step 4: Understand custom code**
```
Analyze the custom code for this account
```
Scans `accounts/<PROFILE>/SOURCE/backend/`, maps rules to workflow rulesets, generates behavior descriptions, and flags any deployed rules without local source.

---

## Scenario 2: "An order is stuck — help me debug it"

**Situation:** A production order `HD-12345` has been in BOOKED status for hours and should have progressed to FULFILLED.

**Step 1: Trace the order**
```
Why is order HD-12345 stuck in BOOKED?
```
Runs `event.flowInspect` on the order, analyzing all orchestration events to find:
- Which events fired and which NO_MATCHed
- Failed webhook deliveries
- Rulesets that should have triggered but didn't
- Timeline of every status change

**Step 2: Check available actions**
```
What actions can I take on this order right now?
```
Queries the Transition API for user actions available at the current status — shows event names, required attributes, and button labels.

**Step 3: Fire a remediation event**
```
Send a RetryFulfilmentAllocation event to order HD-12345
```
Builds and sends the event (with dry-run preview first), then monitors the result.

---

## Scenario 3: "Build a complete feature end-to-end"

**Situation:** Product asks for a new Return Order capability. You need new workflows, custom rules, settings, and deployment — the full lifecycle.

This is the flagship use case. The AI follows the mandatory chain: **requirements → plan → implement → build → deploy → test**. See [How It Works: The Feature Lifecycle](#how-it-works-the-feature-lifecycle) above for the full artifact map.

**Step 1: Gather requirements (if unclear)**
```
Help me define the use cases for a Return Order feature
```
The `/fluent-use-case-discover` wizard runs through 10 phases:
- Entity types involved (ORDER, RETURN_ORDER, FULFILMENT)
- Business rules (return window, item eligibility, refund policies)
- Status lifecycles per entity
- Integration points (WMS, ERP, payment gateway)
- Environment discovery (if profile connected)

Produces a **Business Spec** saved to `accounts/<PROFILE>/features/return-order/spec.md` with a completeness score.

**Step 2: Plan the feature**
```
Plan the Return Order feature
```
`/fluent-feature-plan` checks the spec (must be >= 75% completeness), then produces an 18-section plan:
- Architecture diagrams (Mermaid state machines + sequence diagrams)
- Workflow changes with before/after
- Rules inventory: NEW rules get pseudo-logic contracts, OOTB rules get prop configuration
- Settings, webhooks, cross-entity impacts
- Every artifact tagged as NEW / EXISTING / MODIFIED / REUSED / OOTB
- Deployment sequence, risk assessment, test plan

Plan saved to `accounts/<PROFILE>/features/return-order/plan.md`.

**Waits for your approval.** You can ask questions, request changes, or approve.

> **Your workspace after steps 1-2:**
> ```
> accounts/<PROFILE>/features/return-order/
>   status.json      ← status: PLANNING, plan: PENDING (or APPROVED after you approve)
>   spec.md          ← business requirements with completeness score
>   plan.md          ← 18-section implementation plan with Mermaid diagrams
>   assets/          ← screenshots, recordings, visual evidence (linked from spec/plan)
> ```
> You can close your IDE here. When you come back, the AI reads `status.json`, sees `plan: "APPROVED"` and `next: "/fluent-rule-scaffold"`, and picks up at Step 3.

**Step 3: Scaffold the module (if new)**
```
Create a new module called my-returns
```
`/fluent-module-scaffold` generates the full Maven project: POMs, `module.json`, directory structure, build scripts, `.gitignore`.

**Step 4: Scaffold custom rules**
```
Create the rules from the plan
```
`/fluent-rule-scaffold` generates each rule from the plan: Java class with SDK boilerplate, test skeleton, wired into `module.json`. Each rule emits `-> READY: <path>` and `-> NEXT: /fluent-build` on completion.

**Step 5: Build the workflow**
```
Build the RETURN_ORDER::DEFAULT workflow from the plan
```
`/fluent-workflow-builder` creates the workflow JSON with rulesets, states, triggers, and validates all references. Then `/fluent-workflow-analyzer` runs automatically to catch orphaned rulesets or trigger conflicts.

**Step 6: Build and package**
```
Build the module
```
`/fluent-build` bumps the version, runs `mvn clean install`, packages the ZIP. If compilation fails, reports the error and suggests fixes.

**Step 7: Pre-deploy quality gates**
```
Run pre-deploy checks
```
`/fluent-pre-deploy-check` runs 26 gates across 8 phases: environment reachability, module structure, workflow validity, connection integrity, settings completeness, target environment checks, risk assessment, completeness verification. Reports READY or BLOCKED with specific blockers.

**Step 8: Deploy module + workflow**
```
Deploy everything to MY_RETAILER
```
`/fluent-module-deploy` installs the module ZIP. `/fluent-workflow-deploy` uploads the workflow JSON (tries MCP first, falls back to REST API). Both verify the deployed version matches.

**Step 9: End-to-end test**
```
Run the E2E test from the plan
```
`/fluent-e2e-test` creates test entities dynamically (using `/fluent-test-data` discovery), fires events at each step, polls for status transitions, and reports pass/fail per step. On failure, automatically traces the failed event to find the root cause.

**Step 10: Fix loop (if needed)**

If a test fails, the agent diagnoses the issue (wrong prop value? missing setting? rule bug?), applies the fix, rebuilds, redeploys, and re-tests. This loop continues until all tests pass or an unresolvable blocker is hit.

> **Your workspace after all steps:**
> ```
> accounts/<PROFILE>/
>   features/return-order/
>     status.json                                 ← status: VERIFIED, plan: APPROVED
>     spec.md                                     ← business requirements
>     plan.md                                     ← approved implementation plan
>   SOURCE/backend/fc-module-my-returns/
>     resources/module.json                       ← rule registrations
>     plugins/rules/my-returns/src/main/java/
>       .../ValidateReturnWindow.java             ← custom rule
>       .../ProcessReturnRefund.java              ← custom rule
>     plugins/rules/my-returns/src/test/java/
>       .../ValidateReturnWindowTest.java          ← test skeleton
>     dist/fc-module-my-returns-1.0.0.zip         ← deployed module
>   workflows/<RETAILER_REF>/
>     RETURN_ORDER__DEFAULT.json                  ← deployed workflow
>   reports/module-validate/my-returns.report.json
> ```

**Common issues:**
- "PLAN_REQUIRED" — you tried to scaffold rules without approving the plan first. Say "approved" to continue.
- "PREREQ_MISSING" — the module doesn't exist yet. Run `/fluent-module-scaffold` first.
- Build fails — check the error message. Common causes: missing imports, wrong SDK version, typo in `@ParamString` name.
- Deploy blocked — pre-deploy check found issues. Run `/fluent-pre-deploy-check` to see what's blocking.

### Resuming This Feature

If you close your IDE at any point and come back later:

```
"Continue working on return orders"
```

The AI reads `features/return-order/status.json`, sees the current state and `next` skill, and picks up exactly where you left off. No need to re-explain context.

---

## Scenario 4: "We're going live next week — are we ready?"

**Situation:** Pre-production readiness check before go-live.

**Step 1: Run RFL assessment**
```
Run a Ready For Launch assessment
```
Analyzes:
- All deployed workflows (structure, orphaned rulesets, trigger coverage)
- Custom rules (code quality, test coverage, GraphQL usage)
- Settings (missing keys, invalid values)
- Integration points (webhook configuration)
- Architecture (entity relationships, cross-workflow dependencies)

Produces a scored report with risk ratings and prioritized recommendations.

The RFL assessment produces a scored report covering:
- Workflow health score (0-100)
- Code quality score (0-100)
- Settings completeness score (0-100)
- Integration risk rating (LOW/MEDIUM/HIGH/CRITICAL)
- Prioritized remediation recommendations

Each finding includes severity, affected entity, and a specific fix recommendation.

**Step 2: Audit settings**
```
Audit all settings for ORDER::HD — find any gaps
```
Cross-references workflow rule parameters against deployed settings. Flags missing settings, wrong value formats, and cascading scope issues (RETAILER vs ACCOUNT).

**Step 3: Check event health**
```
Show me event failure rates and NO_MATCH events for the last 24 hours
```
Queries Prometheus metrics or Event API, runs anomaly detection, and reports:
- Failure rate (threshold: >5%)
- NO_MATCH events (any = critical — means workflow gaps)
- PENDING queue buildup
- Single-event dominance (possible runaway loops)

**Step 4: Validate cross-entity connections**
```
Run connection analysis on ORDER::HD with --validate against a real order
```
Compares the static workflow paths (what should happen) against actual runtime events for a real entity (what did happen). Shows gaps, unexpected events, and timing analysis. Flags any rulesets that never fired in production.

---

## Scenario 5: "Set up a fresh environment for testing"

**Situation:** You need a clean retailer environment with locations, networks, inventory, and test data.

**Step 1: Bootstrap (new account)**
```
Bootstrap a new Fluent account from scratch
```
Walks through: profile creation, retailer setup, reference module installation, sample data.

**Or configure an existing retailer:**
```
Set up a warehouse location called "Sydney DC" with 24/7 hours
```
Creates the location via GraphQL with proper `openingSchedule`.

**Step 2: Create test data**
```
Create a test HD order with 2 items
```
Auto-discovers available products, locations, and customers from the live environment. Generates a valid order payload — no hardcoded refs.

**Step 3: Run smoke test**
```
Run an E2E test of the full HD order flow
```
Creates order → fires events through each status → asserts transitions → reports results. On failure, automatically runs event forensics to show exactly where it broke.

---

## Scenario 6: "Monitor production event processing"

**Situation:** Ongoing operational monitoring of event health.

**Quick health check:**
```
Run a health check on event processing
```
Single call that checks failure rates, NO_MATCH events, pending queues, and event dominance.

**Detailed metrics:**
```
Show me the top 20 events by volume in the last 6 hours
```
Aggregates events by name + entity type + status, ranks by volume, shows failure rates per event.

**SLO report:**
```
Generate an SLO report for the last 24 hours
```
Computes event volume, failure/NO_MATCH/pending rates, p95 runtime and inflight latency. Flags any threshold breaches.

**Deep dive on failures:**
```
What are the top failing events? Show me details
```
Lists top failing events with counts, then drills into specific failures with `event.flowInspect`.

---

## Scenario 7: "I need to understand the event model"

**Situation:** You're new to Fluent's event-driven architecture and need to understand how events work.

```
How does event routing work in Fluent? What are the event types and statuses?
```
Explains:
- Event types (ORCHESTRATION, API, ORCHESTRATION_AUDIT)
- Event categories (GENERAL, ACTION, CUSTOMER)
- Event statuses (SUCCESS, FAILED, NO_MATCH, PENDING, SCHEDULED)
- The routing model (how events match to workflow rulesets via triggers)
- Run-once workflows and scheduled events
- How to query and filter events for debugging

---

## Scenario 8: "Deploy a workflow change safely"

**Situation:** You've modified a workflow and need to deploy it without breaking production.

**Step 1: Diff the changes**
```
Compare the current ORDER::HD workflow with my modified version
```
Shows added/removed/modified rulesets, risk assessment (removing rulesets = HIGH risk), and before/after state diagrams.

**Step 2: Validate connections**
```
Run connection analysis on ORDER::HD — check for broken cross-entity links
```
Maps all internal, cross-entity, and cross-workflow connections. Flags any rulesets that emit events with no matching triggers.

**Step 3: Run pre-deploy quality gates**
```
Run pre-deploy checks for this workflow change
```
`/fluent-pre-deploy-check` validates: environment is reachable, workflow structure is valid, no orphaned rulesets, all rule references resolve to deployed modules, settings exist for referenced keys. Reports READY or BLOCKED.

If BLOCKED, shows exactly what to fix (e.g., "Rule `ACCT.returns.ValidateReturnWindow` not found in any deployed module — deploy the module first").

**Step 4: Deploy the workflow**
```
Deploy ORDER::HD to MY_RETAILER
```
`/fluent-workflow-deploy` uploads the workflow. Tries MCP `workflow.upload` first; if that fails (auth issue, size limit), falls back to REST API with automatic token acquisition. Verifies the deployed version matches the uploaded version.

**Step 5: Verify with E2E test**
```
Run an E2E test of the HD flow to verify the deployment
```
Exercises the deployed workflow end-to-end and reports pass/fail. On failure, traces the specific event to pinpoint whether the new workflow change caused the issue.

**Common issues:**
- Diff shows "removed rulesets" — HIGH risk. Verify these rulesets are truly unused before deploying. Run connection analysis to check for incoming triggers from other workflows.
- Pre-deploy reports BLOCKED on rule references — the module containing those rules isn't deployed yet. Deploy the module first.
- Workflow upload fails with 413 — workflow JSON exceeds size limit. The skill automatically falls back to REST API upload.

---

## Scenario 9: "Batch ingest inventory data"

**Situation:** You need to load 10,000 inventory positions from an external system.

**Step 1: Create the batch job**
```
Create a batch ingestion job for inventory positions
```
`/fluent-job-batch` walks through the setup:
- Creates a JOB entity scoped to INVENTORY_POSITION
- Confirms the target catalogue and location refs

**Step 2: Send records in batches**
```
Send the inventory records — here's the CSV/JSON data
```
Splits records into batches (default 100 per batch), sends each via `batch.send`, tracks progress. Shows a running count: "Sent 3,200 / 10,000 records (32%)".

**Step 3: Monitor job status**
```
Check the job status
```
Polls `batch.status` and `batch.batchStatus` to show:
- Overall job progress (PENDING → IN_PROGRESS → COMPLETE)
- Per-batch results (success count, error count, error details)
- Records that failed with specific validation errors

**Step 4: Retry failures**
```
Show me the failed records and retry them
```
Fetches `batch.results` for failed batches, shows the specific records and error messages (e.g., "Location ref WAREHOUSE_99 not found"), and offers to re-send corrected records.

**Common failure patterns:**
| Error | Cause | Fix |
|---|---|---|
| "Entity not found" | Location or catalogue ref doesn't exist | Create the entity first via `/fluent-retailer-config` |
| "Duplicate ref" | Record already exists | Use update mode or skip duplicates |
| "Validation error" | Missing required fields | Fix the source data and resend |
| "Rate limited" | Too many concurrent batches | Reduce batch size or add delays |

---

## Scenario 10: "Decompose a scope document into tasks"

**Situation:** You have a structured scope document (ADD format) describing a new feature and need an executable task plan before writing any code.

**Step 1: Feed the scope document**
```
Decompose this scope document into tasks with dependencies
```
Provide the scope doc (paste it, or point to a file). `/fluent-scope-decompose` parses it and produces:

- **Ordered task list** with IDs (T-001, T-002, ...) and descriptions
- **Dependency DAG** — which tasks block which (e.g., T-003 depends on T-001 and T-002)
- **Skill mappings** — which skill handles each task (e.g., T-001 → `/fluent-module-scaffold`, T-003 → `/fluent-rule-scaffold`)
- **Decision classifications** — SCAFFOLD (new), EXTEND (modify existing), SOURCE_ONBOARD (restructure), CONFIGURE (settings/data)
- **Ambiguity flags** — where the scope is unclear and needs clarification ("T-005: scope says 'custom validation' but doesn't specify what fields to validate")

**Step 2: Resolve ambiguities**
```
For T-005, validate that the return is within 30 days of order completion
```
Clarification updates the task and clears the ambiguity flag.

**Step 3: Generate the feature plan**
```
Now generate a feature plan from these tasks
```
The task list feeds directly into `/fluent-feature-plan`, which produces the full 18-section plan with architecture diagrams, rules inventory, deployment sequence, and test plan. Each plan section cross-references the task IDs.

---

## Scenario 11: "Onboard existing source into a proper module"

**Situation:** You have Java rule classes from another team or a decompiled JAR, but they're not in Fluent Commerce module format. You need a buildable, deployable module.

**Step 1: Onboard the source**
```
Refactor this code into a Fluent module: accounts/MY_PROFILE/SOURCE/backend/.decompiled/fc-module-ext/
```
Or for loose Java files:
```
/fluent-source-onboard ./my-rules/ --module-name my-returns
```

The skill:
1. **Analyzes** the existing layout (decompiled JAR? loose files? Gradle project? partial module?)
2. **Discovers** all rule classes (by `@RuleInfo`, `BaseRule` extension, `run()` methods)
3. **Plans** the target Maven multi-module structure with a full file operations table
4. **Waits for your approval** before changing anything

**Step 2: Review the plan**

The plan shows exactly what will happen:
- Which files move where
- What code changes are needed (package renames, base class fixes, missing annotations)
- Risk assessment (package renames breaking imports, decompiled artifacts, key conflicts)

**Step 3: Execute and validate**

After approval:
- Creates the Maven multi-module directory structure
- Moves and repackages Java files
- Fixes structural issues (wrong base class, missing `@RuleInfo`, etc.)
- Generates `module.json` with all rule registrations
- Generates build scripts, POMs, `.gitignore`
- Generates test skeletons for untested rules
- Runs `/fluent-module-validate` to verify structure
- Attempts a Maven build to verify compilation
- Cross-references against deployed rules

**Supports these input types:**
- Decompiled JAR output (`.decompiled/` directories)
- Loose Java files (no build system)
- Non-standard Maven projects
- Gradle projects (converted to Maven)
- Existing modules with structural issues (repair mode)

---

## Scenario 12: "Gather requirements before building"

**Situation:** Product says "we need curbside pickup" but there are no structured requirements, use cases, or entity definitions.

```
Help me define the use cases for curbside pickup
```

`/fluent-use-case-discover` runs an interactive wizard through 10 phases:

| Phase | What happens | Output |
|---|---|---|
| 1. Scope | Define the feature boundary — what's in, what's out | Scope statement |
| 2. Actors | Identify who interacts (customer, store staff, OMS, WMS) | Actor registry |
| 3. Use cases | Walk through each user journey step by step | Structured use case list |
| 4. Environment discovery | Query live environment for existing workflows, rules, entity types (requires connected profile) | Available infrastructure |
| 5. Entity model | Define entities, subtypes, and relationships | Entity relationship diagram |
| 6. Status lifecycles | Map statuses per entity with allowed transitions | State machine diagrams |
| 7. Business rules | Capture validation rules, constraints, edge cases | Rules inventory |
| 8. Integration points | Webhooks, external systems, scheduled jobs | Integration map |
| 9. Settings | Required configuration keys and values | Settings inventory |
| 10. Gap analysis | Compare requirements against existing environment | Completeness score |

**Output:** A Business Spec saved to `accounts/<PROFILE>/features/curbside-pickup/spec.md` with a completeness score (0-100%). Specs scoring >= 75% can proceed directly to `/fluent-feature-plan`.

> **Offline limitation:** If no Fluent profile is connected, Phase 4 (environment discovery) is skipped. The spec may contain assumptions. Connect a profile via `/fluent-profile` before running the wizard for best results.

---

## Scenario 13: "Validate cross-entity workflow dependencies"

**Situation:** Your ORDER::HD workflow sends events that trigger FULFILMENT and FULFILMENT_OPTIONS workflows. You need to verify all the cross-entity connections are wired correctly.

**Step 1: Map static connections**
```
Run connection analysis on ORDER::HD
```
`/fluent-connection-analysis` maps:
- **Internal connections** — rulesets within ORDER::HD that SendEvent to other ORDER::HD rulesets
- **Cross-entity connections** — SendEvent calls targeting FULFILMENT, FULFILMENT_OPTIONS, ARTICLE entities
- **Cross-workflow connections** — events that leave ORDER::HD and enter another workflow
- **Orphaned rulesets** — rulesets with no incoming trigger
- **Dead-end events** — SendEvent calls with no matching target ruleset

Output includes Mermaid flowcharts showing the full event graph across workflows.

**Step 2: Compare against runtime (--validate)**
```
Run connection analysis on ORDER::HD --validate HD-12345 --entity-type ORDER
```
Compares the static workflow paths against actual runtime events for a real entity. Shows:
- **Expected but not fired** — rulesets that should have triggered but didn't (possible bug)
- **Fired but not expected** — events that occurred outside the static model (dynamic behavior, scheduled events)
- **Timing analysis** — how long each transition took
- **Cross-entity propagation** — traces events across ORDER → FULFILMENT → FULFILMENT_OPTIONS

This is the most thorough validation — it proves the workflow works as designed for real entities.

---

## Scenario 14: "Bump version and prepare a release"

**Situation:** You've finished development and need to version, build, validate, and deploy a module.

**Step 1: Check current version**
```
What version is the my-extensions module?
```
`/fluent-version-manage` reads the version from `module.json`, `pom.xml` (parent + child), and CHANGELOG. Reports any inconsistencies (e.g., POM says 1.3.0 but module.json says 1.2.9).

**Step 2: Bump the version**
```
Bump my-extensions to 1.4.0
```
Updates ALL version references in sync:
- `plugins/pom.xml` (parent version)
- `plugins/rules/<module>/pom.xml` (module + parent version)
- `resources/module.json` (version field)
- `CHANGELOG.md` (moves [Unreleased] entries to [1.4.0])

**Step 3: Build**
```
Build it
```
`/fluent-build` runs `mvn clean install`, packages the ZIP, verifies the output artifact.

**Step 4: Pre-deploy gates**
```
Run pre-deploy checks
```
26 quality gates across 8 phases. If all pass → READY. If any critical gate fails → BLOCKED with specific fix instructions.

**Step 5: Deploy**
```
Deploy to MY_RETAILER
```
Module install + post-deploy verification.

**Common issues:**
- Version mismatch — `module.json` says 1.4.0 but `pom.xml` still says 1.3.0. Run `/fluent-version-manage` to sync all version references.
- Build fails after version bump — stale `dist/` artifacts from the old version. Clean build (`mvn clean install`) resolves this.
- Pre-deploy gate fails on "module already deployed at same version" — bump the version again or use a `-SNAPSHOT` suffix for testing.

---

## Scenario 15: "Audit what happened in this session"

**Situation:** You've been working for an hour — scaffolded rules, edited workflows, deployed a module, ran tests. Now you need to know exactly what changed and what tools were called.

**Quick summary:**
```
What did we change this session?
```
`/fluent-session` shows three tables:

**Skill Invocations:**
| # | Skill | Gate | Outcome | Next |
|---|---|---|---|---|
| 1 | fluent-rule-scaffold | PASS | completed | fluent-build |
| 2 | fluent-build | PASS | completed | fluent-pre-deploy-check |
| 3 | fluent-pre-deploy-check | — | completed (READY) | fluent-module-deploy |
| 4 | fluent-module-deploy | PASS | completed | fluent-e2e-test |

**MCP Tool Calls:**
| # | Tool | Target | Write? | Outcome | Skill |
|---|---|---|---|---|---|
| 1 | entity.create | ORDER/E2E_HD_001 | Yes | ok | fluent-e2e-test |
| 2 | event.send | ORDER/E2E_HD_001 | Yes | ok | fluent-e2e-test |
| 3 | test.assert | ORDER/E2E_HD_001 status=BOOKED | No | ok | fluent-e2e-test |

**Changes:**
| # | Action | File/Entity | Details |
|---|---|---|---|
| 1 | CREATE | src/.../ValidateReturnWindow.java | New rule class |
| 2 | MODIFY | resources/module.json | Registered ValidateReturnWindow |
| 3 | DEPLOY | fc-module-my-returns 1.4.0 | Installed to MY_RETAILER |

**Machine-readable export:**
```
Export a JSON audit trail
```
`/fluent-session export` writes a JSON file to `accounts/<PROFILE>/sessions/` with:
- `skillInvocations[]` — full decision chain with gate results, handoff signals, cross-references
- `toolCalls[]` — every MCP tool call with target, outcome, triggering skill
- `changes[]` — every state mutation with rollback commands
- `decisionTrail[]` — explicit branch decisions with rationale and confidence
- `compliance` — scope traceability matrix, task completion status

The JSON is designed for CI/CD consumption — parse it as a deployment gate, feed it into Jira work logs, or attach to Confluence release pages.

> **Tip:** Run `/fluent-session` regularly during long sessions. The AI tracks changes as they happen — it's easier to review incrementally than reconstruct everything at the end.

---

## Scenario 16: "Create a data module (no Java)"

**Situation:** You need to deploy reference data, workflow fragments, or configuration assets — no custom Java rules.

```
Create a data module called my-reference-data
```
`/fluent-data-module-scaffold` generates:
- `module.json` with module metadata (no `rules` array)
- `assets/` directory structure for workflows, settings, and data files
- `config/` template for module configuration
- Build script that packages the module ZIP without Maven compilation

Data modules are lighter than extension modules — no POMs, no Java source, no test skeletons. They're deployed the same way (`fluent module install`) but only carry assets.

---

## Scenario 17: "Map what's been built on this account"

**Situation:** You're onboarding to a new Fluent Commerce account and need to understand the full implementation — what features exist, how they connect, and where the gaps are.

```
What has been built here? Give me a feature inventory
```

`/fluent-implementation-map` runs a 5-phase analysis:

1. **Inventory Collection** — queries workflows (`workflow.list`), custom rules (`plugin.list`), settings (`graphql.query`), and local source code to build the raw inventory
2. **Feature Identification** — clusters workflows into logical features using subtype alignment, cross-entity events, shared custom rules, and naming conventions
3. **Flow Mapping** — traces cross-feature dependencies and generates Mermaid diagrams (feature dependency graph + entity lifecycle sequence)
4. **Gap Analysis** — identifies missing workflows, orphaned rules, webhook health issues, dead-end risks, and OOTB coverage gaps
5. **Report Generation** — produces the master document plus per-feature summaries

**Output at `accounts/<PROFILE>/analysis/implementation-map/`:**

```
implementation-map.md              ← Master document with executive summary, feature table, diagrams
inventory.json                     ← Machine-readable inventory (workflows, features, gaps, modules)
gaps.md                            ← All identified gaps with severity and remediation
features/
  home-delivery.md                 ← Per-feature summary with workflows, rules, webhooks
  click-collect.md
  inventory-management.md
  ...
diagrams/
  feature-dependency.mmd           ← Cross-feature dependency flowchart
  entity-flow.mmd                  ← Entity lifecycle sequence diagram
```

Each feature gets a **customisation depth score** (0-4: OOTB → Configured → Extended → Custom → Bespoke) and a **confidence rating** (HIGH/MEDIUM/LOW) based on evidence quality.

Read-only — no planning gate, no environment changes. Great as a first step before `/fluent-feature-explain` on specific features.

---

## Scenario 18: "Check feature status across the workspace"

**Situation:** You have multiple features in various lifecycle stages and need a dashboard view.

```
What features are in progress? Show the dashboard
```

`/fluent-feature-status` scans all `accounts/<PROFILE>/features/*/status.json` files and presents a consolidated table:

| Feature | Retailer | Status | Spec | Plan | Rev | Next Step |
|---------|----------|--------|------|------|-----|-----------|
| curbside-pickup | MY_RETAILER | IN_PROGRESS | APPROVED | APPROVED | 2 | /fluent-build |
| return-order | MY_RETAILER | VERIFIED | APPROVED | APPROVED | 1 | — |
| loyalty-points | MY_RETAILER | PLANNING | APPROVED | DRAFT | 1 | /fluent-feature-plan |

**Filtering:** Ask for specific states:
```
Show only IN_PROGRESS features
```

**Attention items** are highlighted automatically:
- Features stuck in PLANNING for more than 7 days
- Features with `plan: "PENDING"` but `status: "IN_PROGRESS"` (skipped approval?)
- Features with `basedOn` links to non-existent features

Read-only — no planning gate, no environment changes. Use this when resuming a session to see where you left off.

---

## Scenario 19: "Roll back a failed deployment"

**Situation:** You deployed a new workflow version and it's causing event failures. You need to revert to the previous version.

```
Roll back ORDER::HD to the previous version
```

`/fluent-rollback` follows a structured process:

**Step 1: Planning gate** — presents a rollback plan showing:
- Current deployed version vs target version
- Source of the rollback artifact (pre-deploy backup, local cache, or git history)
- What will change and what won't
- Irreversible operations that can't be rolled back (already-processed events, sent webhooks)

**Step 2: Dry run** (recommended for production):
```
Roll back ORDER::HD --dry-run
```
Shows exactly what would happen without making changes.

**Step 3: Execute** — after plan approval, uploads the previous workflow version as a new version.

**Three artifact types supported:**

| Artifact | Rollback method | Source resolution |
|----------|----------------|-------------------|
| Workflow | Re-upload previous JSON as new version | Pre-deploy backup → local cache → git history |
| Module | Redeploy prior module ZIP | Local dist → git tag → artifact repository |
| Settings | Restore prior values via GraphQL | Session export → settings audit → pre-deploy report |

**Cannot roll back:** Entity state changes, sent events, batch ingestion data, webhook deliveries. The skill refuses these and suggests compensating alternatives.

---

## Scenario 20: "Preview what the UI will look like before building"

**Situation:** You've planned a new UI component or manifest change and want to verify how it will look in the live app before committing to the full build cycle.

```
Preview what the appeasement card looks like on the order detail page
```

`/fluent-mystique-preview` operates in three modes:

| Mode | What it does | When to use |
|------|-------------|-------------|
| **ADD** | Injects a new component into the live app via JavaScript | You're building a new section/card |
| **MODIFY** | Overlays changes on an existing component | You're updating an existing page element |
| **REMOVE** | Hides an existing component temporarily | You're removing a section |

**What happens:**

1. **AI builds a preview spec** — component type, data sources, layout, and injection point
2. **Reads live app DOM** — `take_snapshot` maps the current page structure
3. **Injects preview via JavaScript** — no manifest changes, no deploy required
4. **Takes before/after screenshots** — annotated with green (ADD), amber (MODIFY), red (REMOVE) glow
5. **Iterative refinement loop** — you give feedback ("move it above the status bar", "change the label"), AI adjusts and re-injects
6. **Approval or skip** — `preview: "APPROVED"` in status.json gates the manifest build

**Artifacts created:**

| Artifact | Path |
|----------|------|
| Before screenshot | `accounts/<PROFILE>/reports/preview/before-<timestamp>.png` |
| After screenshot | `accounts/<PROFILE>/reports/preview/after-<timestamp>.png` |
| Preview spec | `accounts/<PROFILE>/reports/preview/preview-spec.json` |
| Status updated | `features/<slug>/status.json` → `preview: "APPROVED"` |

**Skill chain:** `fluent-mystique-preview` → (on approval) → `fluent-mystique-builder` → `fluent-mystique-validate`

Read-only phase (preview) has no planning gate. The manifest build that follows requires an approved plan.

---

## Scenario 21: "Show me the workspace structure"

**Situation:** You want to see what's in the workspace — features, workflows, source code, reports — with counts and annotations.

```
Show me the workspace tree
```

`/fluent-workspace-tree` produces an annotated directory listing:

```
accounts/MY_PROFILE/
  SOURCE/                           (2 backend repos)
    backend/
      fc-module-my-extensions/      (97 rules, v1.4.0)
      fc-module-my-returns/         (3 rules, v1.0.0)
    frontend/                       (SDK component projects)
  workflows/MY_RETAILER/            (17 workflows)
    ORDER__HD.json                  (v1.51, 64 rulesets)
    ORDER__CC.json                  (v1.12, 50 rulesets)
    ...
  features/                         (4 features)
    curbside-pickup/                IN_PROGRESS (plan rev 2)
    return-order/                   VERIFIED
    home-delivery/                  architecture only
    loyalty-points/                 PLANNING
  reports/                          (3 reports)
    pre-deploy/my-returns.json      2026-02-24
  analysis/
    implementation-map/             (11 features mapped)
    code/                           (source-map, behavior-map)
```

Read-only — no planning gate, no environment changes. Useful for orientation when starting a new session or after running multiple skills.

---

## Frontend / Mystique UI Scenarios

### Scenario: Build a New UI Page

**You say:** "Build an order detail page showing order summary, customer info, items, and fulfilments"

**What happens:**
1. `/fluent-mystique-builder` analyzes the requirement against OOTB components
2. Presents a plan: route structure, component tree, data query, composition pattern
3. On approval: generates manifest JSON with `fc.page` → `fc.card.attribute` (summary) + `fc.card.attribute` (customer) + `fc.tabs.card` (items/fulfilments)
4. Auto-runs `/fluent-mystique-validate` to verify structure

**You get:** A complete manifest JSON page definition ready to deploy as a Fluent setting.

### Scenario: Validate Before Deploying

**You say:** "Validate the admin manifest before I deploy it"

**What happens:**
1. `/fluent-mystique-validate` runs 49 rules across 6 phases
2. Checks schema compliance, component aliases, GraphQL queries, template strings, prop completeness, cross-manifest references
3. Reports issues by severity (CRITICAL/HIGH/MEDIUM/LOW)

**You get:** A validation report with pass/fail and specific fix suggestions for any issues found.

### Scenario: Custom Component When OOTB Falls Short

**You say:** "I need a drag-and-drop pick list interface for warehouse staff"

**What happens:**
1. `/fluent-mystique-builder` evaluates the Build vs Configure decision framework
2. Determines OOTB components can't handle drag-and-drop → escalates to Step 4 (custom component)
3. `/fluent-mystique-scaffold` creates a complete SDK project: webpack config, TypeScript setup, component boilerplate, Storybook stories, Jest tests
4. Manifest is updated with `plugins[]` reference to the custom bundle

**You get:** A buildable SDK project with `ComponentRegistry.register()` wiring and a manifest referencing the custom component.

### Scenario: Analyze What's Built in an App

**You say:** "What components are used in the admin manifest? Any complexity issues?"

**What happens:**
1. `/fluent-mystique-analyze` runs 7-dimension analysis: component census, route mapping, complexity scoring (weighted 0-100), data query analysis, i18n coverage, pattern detection, Mermaid diagrams

**You get:** A comprehensive analysis report with component counts, unused components, complexity hotspots, and optimization recommendations.

### Scenario: Full-Stack Feature (Backend + Frontend)

**You say:** "Build order tracking with a customer-facing status page"

**What happens:**
1. `/fluent-feature-plan` creates a unified plan covering both backend (workflow rules, settings) and frontend (manifest pages, components)
2. On approval: backend agent builds rules → workflows → settings first
3. Then frontend agent builds manifest → validates → deploys
4. `/fluent-e2e-test` runs cross-cutting tests

**You get:** Complete backend logic AND UI pages deployed and verified end-to-end.

### Scenario: Verify a Deployed Manifest in the Browser

**You say:** "Test the OMS orders page in the browser"

**What happens:**
1. `/fluent-ui-test` checks that Chrome DevTools MCP is connected (the `chrome-devtools` server must be configured in `.mcp.json`)
2. Navigates to the OMS app URL, handles login if needed (asks you for credentials)
3. Navigates to the `/oms/orders` route
4. Takes a DOM snapshot to verify: page loads without errors, list component renders with data, pagination controls present, search/filter functional
5. Checks `list_console_messages` for React or GraphQL errors
6. Captures a screenshot for visual confirmation

**You get:** A pass/fail report with checks (login, page load, data load, component rendering) and screenshot evidence. Issues are reported with severity (CRITICAL for page errors, MEDIUM for missing components, LOW for stale cache).

**Prerequisites:** Chrome DevTools MCP configured in `.mcp.json`, manifest already deployed via `setting.upsert`, `FLUENT_USERNAME` and `FLUENT_PASSWORD` set as environment variables.

---

## What Happens Behind the Scenes

When you ask your AI assistant to perform these tasks, it doesn't just generate text — it **executes real operations** against your Fluent environment:

| Layer | What it does |
|-------|-------------|
| **AI Skills** (knowledge layer) | Teach the AI *how* to do Fluent tasks — patterns, decision trees, best practices |
| **MCP Extension Server** (execution layer) | 45 tools for real API operations — GraphQL queries, event dispatch, metrics, batch ingestion, workflow fetch, cache |
| **Official MCP Server** (CLI layer) | Workflow listing, downloading, GraphQL validation via the Fluent CLI |
| **Chrome DevTools MCP** (browser layer) | Browser automation for UI testing — login, navigate, snapshot, screenshot (optional, for `/fluent-ui-test`) |
| **Fluent Commerce API** (platform) | The actual REST/GraphQL endpoints being called |

### Planning Gate

Before any implementation work, the AI presents a structured plan and **waits for your explicit approval**. This isn't optional — it's enforced by every implementation skill. You can ask questions, request changes, or reject the plan entirely. No code is written, no entities are created, and no deployments happen without your say-so.

### Progress Visualization

Multi-phase skills show a live progress block as they work, so you always know where the AI is in the process:

```
▸ /fluent-pre-deploy-check [3/8]
  ✓ Environment              ✓ Module structure
  ✓ Workflow validity         → Connections
  ○ Settings                  ○ Target environment
  ○ Risk assessment           ○ Completeness
```

- `✓` completed — `→` currently running — `○` pending
- The block updates at each phase transition

Available on the 10 most-used skills: `/fluent-feature-plan`, `/fluent-trace`, `/fluent-e2e-test`, `/fluent-implementation-map`, `/fluent-feature-explain`, `/fluent-build`, `/fluent-pre-deploy-check`, `/fluent-connection-analysis`, `/fluent-use-case-discover`, `/fluent-workflow-builder`.

### Skill Chains and Handoff Signals

Skills communicate via handoff signals:
- `-> READY: <path>` — "I'm done, here's what I produced"
- `-> NEXT: /fluent-build` — "The next step is this skill"
- `-> BLOCKED: No module found` — "I can't proceed; here's why and what to do"
- `-> SKIP: No settings changes` — "This step doesn't apply"

These signals chain skills together automatically. When `/fluent-rule-scaffold` finishes, it emits `-> NEXT: /fluent-build`. The agent follows the chain without you having to spell out each step.

### Error Taxonomy

When something goes wrong, skills report structured error codes:
- `PLAN_REQUIRED` — you tried to implement without an approved plan
- `PREREQ_MISSING` — a dependency doesn't exist yet (e.g., no module to add rules to)
- `VALIDATION_FAILED` — input failed structural or semantic checks
- `ENV_UNREACHABLE` — can't connect to the Fluent environment
- `DEPLOYMENT_BLOCKED` — pre-deploy gates failed

Each error code comes with a recovery action (which skill to run to fix it).

### Three-Level Pre-Flight Chain

For multi-artifact features, enforcement happens at three levels:
1. **Requirements check** — `/fluent-feature-plan` verifies a Business Spec exists (or structured requirements are provided). If not → redirects to `/fluent-use-case-discover`.
2. **Plan verification** — each implementation skill checks for an approved plan. If not → redirects to `/fluent-feature-plan`.
3. **Dependency checks** — each skill checks that its prerequisites exist (e.g., rule-scaffold checks the module exists). If not → redirects to the prerequisite skill.

This creates an enforced chain: **requirements → plan → implementation**. No step can be skipped without explicit user override.

### Session Tracking

Every skill invocation, MCP tool call, and state change is tracked during the session. At any point you can ask "what did we change?" for a structured report, or export a JSON audit trail for CI/CD pipelines.

---

## Evidence and Confidence

Analysis outputs include confidence levels based on available evidence:

| Evidence available | Confidence | What you get |
|---|---|---|
| Workflow JSON + `plugin.list` only | LOW-MEDIUM | Structure is accurate; rule behavior is inferred from descriptions |
| + Decompiled JAR (bytecode) | MEDIUM-HIGH | Implementation logic visible but variable names may be synthetic |
| + Original source code | HIGH | Full logic, test coverage, and prop validation |
| + Runtime evidence (real entity trace) | HIGHEST | Static analysis validated against actual execution |

When evidence is incomplete, the AI flags it explicitly and recommends how to get higher confidence (provide source, run a test entity, etc.).

---

## Known Limitations

| Capability | Status | Workaround |
|-----------|--------|-----------|
| Live log tailing / real-time event streaming | Not supported | Use `event.list` with time filters for polling |
| Multi-retailer operations in single command | Not supported | Switch retailer context between operations |
| Visual workflow editor (GUI) | Not supported | Edit workflow JSON directly via `/fluent-workflow-builder` |
| Anonymous mode (no credentials) | Not supported | MCP tools require profile auth or OAuth credentials |
| Decompiled source modification | Read-only | Analyze decompiled code but can't edit it; provide original source or scaffold a new module via `/fluent-source-onboard` |
| Windows `::` in workflow filenames | Auto-handled | CLI and skills auto-sanitize to `__` and maintain `workflow-file-map.json` |
| `fluent workflow merge` upload bug | Known CLI bug | Skills use REST API upload as fallback automatically |
| `workflow.simulate` runtime execution | Static only | Simulates by matching status + event + subtype; does not execute Java rules or check runtime state |
| Java rule execution | Not supported | Skills can scaffold, build, and deploy rules but cannot execute them locally; use E2E tests against the live environment |

---

## Troubleshooting

### Skill Gate Errors

These errors come from the skill enforcement chain. Each one tells you exactly what's missing and which skill to run.

| Error code | What happened | Fix |
|---|---|---|
| `PLAN_REQUIRED` | You asked a skill to implement something but there's no approved plan | Run `/fluent-feature-plan` (multi-artifact) or let the skill create a task plan (single artifact). Approve it, then retry. |
| `PREREQ_MISSING` | A skill needs something that doesn't exist yet | Follow the redirect. Common cases: `/fluent-rule-scaffold` needs a module → run `/fluent-module-scaffold`. `/fluent-workflow-builder` needs deployed rules → run `/fluent-build` then `/fluent-module-deploy`. `/fluent-build` needs a validation report → run `/fluent-module-validate`. |
| `VALIDATION_FAILED` | Input data failed structural or semantic checks | Read the error details — they specify which field or structure is wrong. Fix and retry. |
| `ENV_UNREACHABLE` | Can't connect to the Fluent environment | Run `config.validate` and `connection.test` via MCP to diagnose. Common causes: expired credentials, wrong profile, VPN not connected. |
| `DEPLOYMENT_BLOCKED` | Pre-deploy quality gates failed | Run `/fluent-pre-deploy-check` to see the full gate report. Each blocked gate explains what to fix. |

If you want to bypass a gate, say **"skip planning"** or **"just do it"** — the override is logged as `USER_OVERRIDE`.

### MCP Tool Errors

These errors come from the MCP extension server when calling Fluent Commerce APIs. Every tool response includes `ok: true` or `ok: false` with a typed error code.

| Error code | What it means | What to do |
|---|---|---|
| `CONFIG_ERROR` | Environment variables are missing or invalid | Check `.mcp.json` — verify `FLUENT_PROFILE` is set (or OAuth credentials if not using profile auth). Restart IDE after editing `.mcp.json`. |
| `AUTH_ERROR` | Credentials are wrong or expired | For profile auth: run `fluent profile update YOUR_PROFILE --username <user> --password <new-pass>` to refresh credentials. For OAuth: verify `FLUENT_CLIENT_ID`/`FLUENT_CLIENT_SECRET`/`FLUENT_USERNAME`/`FLUENT_PASSWORD` environment variables are set correctly. |
| `TIMEOUT_ERROR` | Request took longer than 30 seconds (default) | For large queries, increase `FLUENT_REQUEST_TIMEOUT_MS` in `.mcp.json` env block (e.g., `"60000"` for 60s). |
| `RATE_LIMIT` | Too many API requests | Wait a moment and retry. The server uses exponential backoff automatically for read operations. |
| `UPSTREAM_UNAVAILABLE` | Fluent API returned 502/503/504 | The platform may be under maintenance. Check Fluent status page. Reads retry automatically (up to 3 attempts with backoff). |
| `NETWORK_ERROR` | Can't reach the API endpoint at all | Check VPN, network connectivity, firewall. Verify the base URL in your profile is correct. |
| `SDK_ERROR` | Fluent SDK returned an unexpected error | Usually a bug or unsupported operation. Check the error message for details. |

### Common Setup Problems

**"I typed a slash command but nothing happened"**
- Skills must be installed first: `npx @fluentcommerce/ai-skills install`
- Slash commands (`/fluent-*`) only work in Claude Code. Other IDEs use natural language prompts that trigger the same skills.

**"MCP tools aren't available"**
- Run `npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE` to generate `.mcp.json`
- Restart your IDE after creating or editing `.mcp.json` — MCP servers are loaded at startup
- Verify with `config.validate` → `health.ping` → `connection.test` (in that order)

**"Workflow download fails or returns empty"**
- Check you have the right profile and retailer: `fluent workflow list -p YOUR_PROFILE -r YOUR_RETAILER`
- Fluent CLI must be installed: see [install guide](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package)
- The profile must have the retailer associated — verify with `fluent profile retailers YOUR_PROFILE`

**"The AI keeps asking me to approve a plan"**
- This is by design — the planning gate prevents unreviewed changes. Say **"approved"**, **"yes"**, or **"go ahead"** to proceed. Or say **"just do it"** or **"skip planning"** to bypass.

**"I came back to a session and the AI lost context"**
- Check `accounts/<PROFILE>/features/*/status.json` — the AI reads these to resume where you left off
- If `status.json` shows `next: "/fluent-rule-scaffold"`, the AI knows to continue with that skill
- If files are missing, re-run `/fluent-connect` to rebuild workspace state

**"Response is truncated or summarized"**
- Large API responses are auto-summarized (not truncated) when they exceed 50,000 characters. The summary includes record counts, field inventory, distributions, and sample records.
- To get full raw data, set `FLUENT_RESPONSE_BUDGET_CHARS=0` in `.mcp.json` env block. This disables the budget and returns everything.

---

## Further Reading

- [index.md](index.md) — Docs hub and recommended reading order
- [README.md](../README.md) — Installation, setup, CLI reference
- [dev-workflow.md](dev-workflow.md) — Full development lifecycle with all phases
- [Agents & Skills Guide](agents-and-skills-guide.md) — What each agent and skill does, how to invoke it, when to use it, and where it fits in the SDLC
- [Operational Reference](fluent-ai-skills-reference.md) — Architecture, MCP tools, feature lifecycle, deployment runbook, CLI reference
- [Capability Map](capability-map.md) — Which skill owns what capability
- [Chrome DevTools MCP](chrome-devtools-mcp-reference.md) — Browser automation and UI testing reference
- [Deployment Runbook](deployment-promotion-runbook.md) — Step-by-step deployment and environment promotion
