---
name: fluent-implementation-map
description: Reverse-engineer an entire Fluent Commerce implementation into a feature inventory with end-to-end flow diagrams, cross-feature dependency maps, customisation scoring, and gap analysis. Triggers on "implementation map", "what's been built", "analyze implementation", "reverse engineer account", "feature inventory", "end to end flows", "map this account", "what exists", "onboard to account".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: --profile PROFILE --retailer RETAILER [--depth summary|detailed] [--focus ENTITY_TYPE] [--include-ootb] [--create-stubs] [--include-runtime]
cursor-tier: auto
---

# Implementation Map

Reverse-engineer an entire Fluent Commerce implementation into a feature inventory with end-to-end flow diagrams, cross-feature dependencies, and gap analysis. This is the **top of the analysis pyramid** — run it first when onboarding to an account you know nothing about.

## Ownership Boundary

This skill owns the **discovery and decomposition** of an entire implementation into logical features with cross-feature dependency mapping.

Source analysis skills (called as needed, not duplicated):
- Per-feature deep dive -> `/fluent-feature-explain`
- Per-workflow structure -> `/fluent-workflow-analyzer`
- Cross-workflow topology -> `/fluent-connection-analysis`
- Source code analysis -> `/fluent-custom-code`
- Convert inventory to lifecycle features -> `/fluent-scope-decompose`
- Start lifecycle for discovered feature -> `/fluent-use-case-discover`
- Production readiness -> `/fluent-rfl-assess`

MCP tools used directly:
- `plugin.list` — Deployed rule inventory (module, version, rule key)
- `graphql.query` — Settings inventory, entity type catalogue
- `workflow.transitions` — Live workflow version confirmation (and user-action visibility checks using the strict contract from `/fluent-workflow-builder` and `/fluent-transition-api`)

## No Planning Gate

This is a **read-only analysis skill**. It writes analysis artifacts to `accounts/<PROFILE>/analysis/implementation-map/` but does not modify workflows, settings, or entities. Same category as `/fluent-feature-explain` and `/fluent-workflow-analyzer`.

## When to Use

- "What has been built on this account?"
- "Map the entire implementation end to end"
- "I'm onboarding — show me everything"
- "Give me a feature inventory with flow diagrams"
- "Analyze this implementation for gaps and risks"
- Pre-engagement discovery, audits, or handover documentation

## Invocation Examples

```bash
/fluent-implementation-map --profile <PROFILE> --retailer "<RETAILER>"
/fluent-implementation-map --profile <PROFILE> --retailer <RETAILER_REF> --depth detailed
/fluent-implementation-map --profile <PROFILE> --retailer <RETAILER_REF> --focus ORDER
```

## Inputs

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--profile` | Yes | Active CLI profile | Fluent CLI profile name |
| `--retailer` | Yes | Profile default | Target retailer ref |
| `--depth` | No | `summary` | `summary` = feature list + high-level flows; `detailed` = full per-feature architecture |
| `--focus` | No | All | Filter to specific entity type (ORDER, FULFILMENT, ARTICLE, WAVE, etc.) |
| `--include-ootb` | No | `false` | Include OOTB-only flows (no customisations) in the map |
| `--create-stubs` | No | `false` | Create `features/<slug>/status.json` for each discovered feature, bridging discovery into the feature lifecycle |
| `--include-runtime` | No | `false` | Collect runtime evidence per feature via `event.flowInspect` and `entity.get` (significantly slower) |

## Progress

Emit this block at each phase transition to show progress:

```
▸ /fluent-implementation-map [1/5]
  ✓ Inventory collection    → Feature identification
  ○ Flow mapping            ○ Gap analysis
  ○ Report generation
```

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

## Output Location

All generated artifacts are written to:

```
accounts/<PROFILE>/analysis/implementation-map/
├── implementation-map.md          # Master document: inventory + cross-feature map
├── features/                      # Per-feature summaries
│   ├── home-delivery.md
│   ├── click-collect.md
│   └── ...
├── diagrams/                      # Mermaid source files
│   ├── feature-dependency.mmd     # Cross-feature dependency graph
│   ├── entity-flow.mmd            # Entity lifecycle overview
│   └── <feature>-flow.mmd         # Per-feature flow diagram
├── gaps.md                        # Gap analysis: orphans, dead ends, missing handlers
└── inventory.json                 # Machine-readable: all workflows, rules, settings, feature clusters
```

**Important:** These are analysis artifacts, NOT feature lifecycle artifacts. They live under `analysis/`, not `features/`. To promote a discovered feature into the lifecycle, run `/fluent-use-case-discover` or `/fluent-feature-explain` to create `features/<slug>/`.

---

## Pre-flight: Project Knowledge Check

Check for project-specific knowledge that should inform implementation mapping:

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

3. Read matching knowledge files — typically:
   - `knowledge/platform/domain-model.md` — use for entity types, cross-domain relationships, orchestrable classification
   - `accounts/<PROFILE>/knowledge/client/business-rules.md` — use for expected business logic patterns
   - `accounts/<PROFILE>/knowledge/client/data-model.md` — use for entity types, subtypes, catalogue structure
4. Apply knowledge silently — do NOT show raw knowledge to user, just use it to inform feature discovery

## Phase 1: Inventory Collection

Collect all raw data from the environment. Sub-steps are parallelisable where noted.

### 1a. Workflows

1. Check if workflows exist at `accounts/<PROFILE>/workflows/<RETAILER>/`.
2. If missing or empty, download them:
   ```bash
   mkdir -p accounts/<PROFILE>/workflows/<RETAILER>/
   fluent workflow download -p <PROFILE> -r <RETAILER> -w all -o accounts/<PROFILE>/workflows/<RETAILER>/
   # If CLI returns 401 or on Windows (:: filename issue), use MCP with outputDir:
   # workflow.list({ retailerId: "<id>", outputDir: "accounts/<PROFILE>/workflows/<RETAILER>" })
   # This downloads ALL workflows to disk in one call (returns summary only, keeps large JSON out of context)
   ```
3. Read all workflow JSON files. For each workflow, extract:
   - Workflow name (e.g., `ORDER::HD`)
   - Entity type and subtype (parse `<ENTITY_TYPE>::<SUBTYPE>` from name; if no `::`, treat as DEFAULT subtype)
   - All statuses, rulesets, triggers, and rules
   - Version number

**Produce:** Complete list of workflows with entity types, subtypes, and ruleset counts.

### 1b. Custom Rules (deployed)

```
MCP: plugin.list (no filter)
```

Produces: All deployed rules with module name, version, fully qualified rule key, description, parameters, and accepted entity types.

### 1c. Custom Rules (source code)

If `accounts/<PROFILE>/SOURCE/backend/` exists:

1. Scan for `resources/module.json` files — extract rule registrations.
2. Scan for `src/main/java/**/*.java` files — extract rule classes, annotations, entity context.
3. Check for existing analysis artifacts at `accounts/<PROFILE>/analysis/code/source-map.json` — reuse if fresh.

**Produce:** Per-rule metadata (class name, entity context, referenced settings, test coverage).

### 1d. Settings

```
MCP: graphql.query — query settings by context (RETAILER, ACCOUNT)
```

Use cascading scope resolution: RETAILER scope first, then ACCOUNT scope.

**Produce:** All settings with keys, values, and contexts.

### 1e. Entity Type Catalogue

```
MCP: graphql.query — list entity types and subtypes in use
```

Query `orderTypes`, `fulfilmentTypes`, `articleTypes`, etc. to determine which entity types and subtypes are configured.

### 1f. Webhook / Integration Inventory

Grep workflow JSONs for integration patterns:
- `SendWebhook` rule invocations (outbound webhooks)
- Setting keys matching `*.url`, `*.endpoint`, `webhook.*` patterns
- `ScheduleEvent` invocations (scheduled automations)
- External event receivers (rulesets with no inbound SendEvent from within the workflow)

**Produce:** Outbound and inbound integration point inventory.

### 1g. UI Customisation Discovery (Mystique Manifests)

Scan `fc.mystique.manifest.*` settings to identify deployed manifest overrides:

```
MCP: graphql.query —
  query { settings(first: 100, filter: { name: { startsWith: "fc.mystique.manifest" } }) {
    edges { node { name context contextId updatedOn } }
  }}
```

Each ACCOUNT-scoped or RETAILER-scoped override indicates a UI customisation. Fragment overrides (e.g., `fc.mystique.manifest.oms.fragment.orderDetail`) represent page-level UI changes that should be inventoried as frontend artifacts.

**Produce:** List of manifest overrides with app name, fragment name, scope, and last-updated timestamp. Features with manifest overrides are cross-domain (backend + frontend).

---

## Phase 2: Feature Identification

This phase is analytical — no external calls. Group raw inventory into logical features.

### 2a. Primary Grouping: Entity Type + Subtype

Group workflows by entity type:

```
ORDER workflows:       ORDER::HD, ORDER::CC, ORDER::MULTI
FULFILMENT workflows:  FULFILMENT::HD, FULFILMENT::CC
ARTICLE workflows:     ARTICLE::DEFAULT
WAVE workflows:        WAVE::DEFAULT
```

### 2b. Feature Boundary Heuristics

A "feature" is a user-facing business capability that typically spans one or more entity types. Apply these heuristics in order:

1. **Subtype alignment** — An ORDER subtype (e.g., `HD`) usually pairs with a FULFILMENT subtype (e.g., `HD`). Group as one feature "Home Delivery".
2. **Cross-entity events** — If ORDER::HD sends events that FULFILMENT::HD workflows consume, they belong to the same feature.
3. **Shared custom rules** — If a custom rule is referenced by both ORDER::HD and FULFILMENT::HD workflows, they belong to the same feature.
4. **Naming convention** — Subtypes with the same suffix (HD, CC, MULTI) suggest feature families.
5. **Standalone entity types** — WAVE, ARTICLE often serve as shared infrastructure rather than a single feature. Mark as "shared infrastructure".

Each feature cluster carries a **confidence level**:

| Level | Meaning | Trigger |
|-------|---------|---------|
| `HIGH` | Subtype family match + event chain confirmed | Heuristics 1+2 agree |
| `MEDIUM` | Subtype family match only (no event chain confirmation) | Heuristic 1 only |
| `INFERRED` | Naming/rule pattern analysis | Heuristic 3-4 fallback |
| `UNCLUSTERED` | Could not assign to any feature | No heuristic matched |

Report UNCLUSTERED workflows separately — they need manual classification.

### 2c. Feature Classification

Classify each identified feature:

| Category | Definition | Example |
|----------|-----------|---------|
| **Business Feature** | End-to-end customer-facing flow spanning ORDER to FULFILMENT | Home Delivery, Click & Collect |
| **Processing Feature** | Backend automation within a single entity type | Wave management, Article pick/pack |
| **Infrastructure** | Shared services consumed by multiple features | Sourcing, Inventory allocation |
| **Integration** | Outbound/inbound data flows to external systems | Webhook delivery, Batch ingestion |

### 2d. Customisation Depth Scoring

Score each feature on a 0-4 scale:

| Score | Label | Criteria |
|-------|-------|----------|
| 0 | OOTB | All rules are OOTB, no custom settings |
| 1 | Configured | OOTB rules with custom prop values or settings |
| 2 | Extended | Mix of OOTB and custom rules |
| 3 | Custom | >50% of rules in the workflow are custom |
| 4 | Bespoke | All rules are custom, non-standard entity usage |

---

## Phase 3: Flow Mapping

For each identified feature, trace the complete end-to-end flow.

### 3a. Entry Point Identification

Determine for each feature:
- What triggers it? (API call, scheduled event, inbound webhook, batch ingestion)
- What entity is created or modified first?
- What status does the entity start in?

### 3b. Workflow Path Tracing

For each workflow in the feature:

```
For each ruleset:
  - Trigger: status + event name
  - Rules: ordered list (mark OOTB vs CUSTOM)
  - Outcomes: status transitions (success path, error path)
  - Cross-entity handoffs: events sent to other entity types
  - Settings consumed: rule prop references to setting keys
  - Webhooks fired: SendWebhook invocations with target URLs
```

### 3c. Cross-Entity Flow Stitching

Follow the chain across entity types by matching:
- `SendEvent` rule outputs in workflow A to `eventName` triggers in workflow B
- `CreateEntity` rule invocations to entity type + subtype + initial status of the target workflow

Build the full chain: e.g., ORDER::HD (BOOKED) -> CreateFulfilment -> FULFILMENT::HD (CREATED) -> AllocateArticles -> ARTICLE (CREATED).

### 3d. Mermaid Diagram Generation

> **Mandatory:** Validate all Mermaid diagrams against `knowledge/mermaid-syntax-rules.md` rules before writing.

For each feature, generate:

**Sequence diagram** (cross-entity lifecycle):
````markdown
```mermaid
sequenceDiagram
    participant ORD as ORDER::HD
    participant FUL as FULFILMENT::HD
    participant ART as ARTICLE

    ORD->>ORD: CREATED to BOOKED (SourceOrder)
    ORD->>FUL: CreateFulfilment
    FUL->>ART: AllocateArticles
    ART->>ART: CREATED to ACTIVE (AssignLocation)
    ART-->>FUL: ArticleComplete event
    FUL->>ORD: FulfilmentComplete event
```
````

**State diagram** (per entity, when `--depth detailed`):
````markdown
```mermaid
stateDiagram-v2
    [*] --> CREATED
    CREATED --> BOOKED : SourceOrder
    BOOKED --> FULFILLED : AllItemsComplete
    FULFILLED --> COMPLETE : CompleteOrder
```
````

**Cross-feature dependency graph** (always generated):
````markdown
```mermaid
flowchart TD
    HD[Home Delivery] --> SRC[Sourcing]
    CC[Click and Collect] --> SRC
    HD --> INV[Inventory]
    CC --> INV
    HD --> SHIP[Shipping Integration]
    SRC --> INV
```
````

Save Mermaid source files to `diagrams/` directory as `.mmd` files.

---

## Phase 4: Gap Analysis

### 4a. Orphaned Rules

Cross-reference `plugin.list` output against all workflow rule references. Rules deployed but not referenced in any workflow ruleset are orphaned.

### 4b. Unused Settings

Cross-reference settings list against rule prop definitions in workflow JSONs. Settings that exist but are not referenced by any rule prop are potentially unused.

### 4c. Dead-End States

Identify workflow statuses with no outbound transitions that are not marked as terminal/final states. These are potential stuck points.

### 4d. Missing Cross-Entity Handlers

Identify events sent by one workflow that no other workflow has a trigger for. These are broken cross-entity handoffs.

### 4e. Undocumented Customisations

If source code exists under `accounts/<PROFILE>/SOURCE/backend/`:
- Custom rules with no Javadoc or description
- Custom rules with no test class
- Custom rules not documented in any `features/` directory

### Gap Severity

| Severity | Criteria |
|----------|----------|
| HIGH | Missing cross-entity handler, dead-end state on happy path |
| MEDIUM | Orphaned deployed rule, dead-end state on error path |
| LOW | Unused setting, undocumented customisation |
| INFO | OOTB-only flow with no customisation (potential opportunity) |

---

## Phase 5: Report Generation

### Master Document (`implementation-map.md`)

Use this template:

```markdown
# Implementation Map: <RETAILER> on <PROFILE>

Generated: <timestamp>
Environment: <base-url>
Depth: <summary|detailed>
Focus: <entity-type or "all">

## Executive Summary

| Metric | Count |
|--------|-------|
| Workflows | <N> |
| Custom rules (deployed) | <N> |
| Custom rules (source) | <N> |
| Settings | <N> |
| Identified features | <N> |
| Shared infrastructure | <N> |
| Integrations | <N> |
| Customisation depth (avg) | <X.X> / 4 |

## Feature Inventory

| # | Feature | Category | Entity Types | Customisation | Workflows | Custom Rules | Key Integration |
|---|---------|----------|-------------|---------------|-----------|-------------|-----------------|
| 1 | <name> | <category> | <types> | <score> - <label> | <count> | <count> | <integration> |

## Cross-Feature Dependency Map

[Mermaid diagram from diagrams/feature-dependency.mmd]

## Per-Feature Summaries

### 1. <Feature Name>

**Category:** <Business Feature | Processing Feature | Infrastructure | Integration>
**Entry point:** <trigger description>
**End state:** <terminal state(s)>
**Flow:** <entity chain summary>
**Custom rules:** <list of custom rule names>
**Settings:** <count> (<key examples>)
**Integrations:** <outbound/inbound descriptions>

[Link to detailed flow: features/<slug>.md]

## Gaps & Risks

| # | Type | Description | Severity | Recommendation |
|---|------|-------------|----------|----------------|
| 1 | <type> | <description> | <severity> | <recommendation> |

[Full gap analysis: gaps.md]
```

### Per-Feature Summaries (`features/<slug>.md`)

For each feature, write a summary containing: overview (category, entity types, customisation score), entry point and terminal states, workflow path trace (rulesets marked OOTB/CUSTOM), cross-entity flow, Mermaid sequence diagram, settings consumed, integration points, and feature-specific gaps. When `--depth detailed`, include full state diagrams per entity and rule-level detail.

### Gap Analysis (`gaps.md`)

Consolidate all gaps from Phase 4 with severity, affected feature, and recommended action.

---

## Quality Checklist

Before writing the master document, verify:

- [ ] All workflows from the workflow list are accounted for (either in a feature or marked as infrastructure)
- [ ] Each identified feature has at least one workflow or an explicit "no dedicated workflow" note (e.g., sourcing runs within ORDER flows)
- [ ] Cross-feature dependencies are bidirectional — if feature A depends on B, B's summary notes A as a dependent
- [ ] Customisation depth scores match the 0-4 criteria (count custom vs OOTB rules per feature)
- [ ] Orphaned rules list excludes OOTB rules (only custom orphans are flagged)
- [ ] Gap findings have severity assigned (HIGH / MEDIUM / LOW / INFO)
- [ ] Mermaid diagrams validated against `knowledge/mermaid-syntax-rules.md` rules (no colons in free text, no unicode arrows, quoted special-char labels)
- [ ] Feature count in Executive Summary matches Feature Inventory table row count
- [ ] Entity type catalogue accounts for all entity types found in workflow names
- [ ] Output directory created with `mkdir -p accounts/<PROFILE>/analysis/implementation-map/`

---

## Worked Example

Given an account with these workflows:
- `ORDER::HD`, `ORDER::CC`, `ORDER::MULTI`
- `FULFILMENT::HD`, `FULFILMENT::CC`
- `ARTICLE::DEFAULT`
- `WAVE::DEFAULT`

And these custom rules (from `plugin.list`):
- `CreateFulfilmentFromSourcingLocation` (ORDER context)
- `CalculateShippingCost` (FULFILMENT context)
- `AutoCompleteOrder` (ORDER context)
- `NotifyCustomerViaWebhook` (FULFILMENT context)
- `BulkArticleStatusUpdate` (ARTICLE context)
- `CustomSourceOrder` (ORDER context)

**Phase 2 identifies these features:**

| Feature | Category | Why |
|---------|----------|-----|
| Home Delivery (HD) | Business Feature | ORDER::HD + FULFILMENT::HD share `HD` subtype; `CreateFulfilmentFromSourcingLocation` bridges them |
| Click & Collect (CC) | Business Feature | ORDER::CC + FULFILMENT::CC share `CC` subtype |
| Multi-Location (MULTI) | Business Feature | ORDER::MULTI — may share fulfilment with HD or have its own |
| Article Management | Processing Feature | ARTICLE::DEFAULT — shared infrastructure, used by HD and CC |
| Wave Management | Processing Feature | WAVE::DEFAULT — shared infrastructure for warehouse operations |
| Sourcing | Infrastructure | No dedicated workflow — `CustomSourceOrder` runs within ORDER flows |
| Shipping Integration | Integration | `CalculateShippingCost` + `NotifyCustomerViaWebhook` + webhook settings |

**Phase 3 for "Home Delivery" produces this flow:**

```
ORDER::HD                    FULFILMENT::HD              ARTICLE
--------                     --------------              -------
CREATED
  | CustomSourceOrder
BOOKED
  | CreateFulfilmentFromSL
  |------------------------> CREATED
                               | AllocateArticles
                               |------------------------> CREATED
                                                           | AssignLocation
                                                         ACTIVE
                                                           | PickArticle
                                                         PICKED
                                                           |---------------> ArticleComplete
                               FULFILLED <--------------
                               | CalculateShippingCost
                               | NotifyCustomerViaWebhook
                             COMPLETE
  | AutoCompleteOrder <------
COMPLETE
```

---

## Graceful Degradation

When MCP tools are unavailable, the skill degrades gracefully:

| MCP Tool | Used For | Fallback |
|----------|----------|----------|
| `plugin.list` | Deployed rule inventory | Scan `accounts/<PROFILE>/SOURCE/backend/` for `module.json` rule registrations. Report coverage as "source-only, deployed state unknown". |
| `graphql.query` | Settings, entity types | Use CLI: `fluent setting list -p <PROFILE> -r <RETAILER> -q '*'`. If CLI also unavailable, skip settings inventory and note in report. |
| `workflow.transitions` | Live workflow versions and user-action visibility checks | Use local workflow JSON only. Note versions may be stale; user-action runtime visibility cannot be confirmed without live transitions. |

When operating in degraded mode, complete all phases that can run from local files, add a **"Data Sources"** section to the master document listing which sources were available vs skipped, and flag reduced confidence for features relying on missing data.

---

## Machine-Readable Output (`inventory.json`)

Write `inventory.json` alongside the markdown report. This enables downstream tooling, diffing, and lifecycle bridging:

```json
{
  "generated": "2026-02-25T14:30:00Z",
  "profile": "<PROFILE>",
  "retailer": "<RETAILER_REF>",
  "features": [
    {
      "slug": "home-delivery",
      "confidence": "HIGH",
      "clusterMethod": "subtype-family + event-chain",
      "category": "Business Feature",
      "customisationScore": 3,
      "workflows": ["ORDER::HD", "FULFILMENT::HD"],
      "primaryEntity": "ORDER::HD",
      "entryEvents": ["CreateOrder"],
      "terminalStatuses": ["COMPLETE", "CANCELLED"],
      "crossEntityEvents": ["CreateFulfilment", "FulfilmentComplete"],
      "ruleCount": { "custom": 12, "ootb": 34 },
      "settingsReferenced": ["WEBHOOK_ENDPOINT_ORDER_BOOK"],
      "webhooks": ["NotifyWarehouse"],
      "scheduledEvents": ["RetryAllocation"]
    }
  ],
  "unclustered": [
    { "workflow": "VIRTUAL_CATALOGUE::DEFAULT", "reason": "Standalone entity, no event connections" }
  ],
  "crossFeatureConnections": [
    { "from": "home-delivery", "to": "inventory-management", "via": "UpdateInventory", "direction": "outbound" }
  ]
}
```

---

## Feature Stub Creation (`--create-stubs`)

When `--create-stubs` is passed, create `features/<slug>/status.json` for each discovered feature:

```json
{
  "$schema": "feature-status-v2",
  "feature": "home-delivery",
  "retailers": ["<RETAILER_REF>"],
  "status": "DISCOVERY",
  "created": "2026-02-25",
  "updated": "2026-02-25",
  "spec": null,
  "plan": null,
  "build": null,
  "deploy": null,
  "planRevision": null,
  "architecture": false,
  "basedOn": null,
  "next": "/fluent-feature-explain",
  "sessions": [],
  "_discoveredBy": "/fluent-implementation-map",
  "_workflows": ["ORDER::HD", "FULFILMENT::HD"],
  "_confidence": "HIGH"
}
```

Fields prefixed with `_` are discovery metadata (not part of the standard schema). Downstream skills like `/fluent-feature-explain` can read `_workflows` to know which workflows to analyze.

**Lifecycle bridge:** After `--create-stubs`, the user can:
- Run `/fluent-feature-status` to see all discovered features
- Run `/fluent-feature-explain <slug>` on any feature (reads `_workflows`)
- Start the planning chain on any feature via `/fluent-use-case-discover`

---

## Edge Cases

| Case | Handling |
|------|----------|
| Account with 0 workflows | Report "No workflows found" with guidance to deploy |
| Account with 1 workflow | Single-feature output (no clustering needed) |
| All workflows same entity type | Cluster by subtype only; if same subtype, single feature |
| Workflow with no subtype (e.g., `ORDER::ORDER`) | Use heuristic 3-4 or mark as UNCLUSTERED |
| 50+ workflows | Recommend `--depth summary` + `--focus` filter; paginate output |
| No custom rules (pure OOTB) | Still valid; customisation score = 0 for all features |
| No SOURCE/backend/ directory | Skip code analysis; note in gap analysis |
| Circular event chains | Detect and flag as cross-feature loops (not errors) |
| Multiple retailers sharing workflows | Analyze per-retailer; note shared patterns |

---

## Handoff Protocol

On completion:

```
-> READY: accounts/<PROFILE>/analysis/implementation-map/implementation-map.md
-> NEXT: /fluent-feature-explain --feature "<slug>" (for any feature needing deeper analysis)
-> NEXT: /fluent-scope-decompose (to convert inventory into lifecycle features)
-> NEXT: /fluent-rfl-assess (for production readiness check)
-> NEXT: /fluent-connection-analysis --validate (for runtime validation of flows)
-> BLOCKED: No workflows found. Download first: fluent workflow download -p <PROFILE> -r <RETAILER> -w all (or MCP: workflow.list + workflow.get)
```

## Error Reporting

| Error Type | Phase | Severity | Recovery |
|------------|-------|----------|----------|
| `PREREQ_MISSING` | 1a | CRITICAL | No workflows found — download workflows first |
| `ENV_UNREACHABLE` | 1b, 1d, 1e | HIGH | MCP unavailable — fall back to local files |
| `VALIDATION_FAILED` | 1a | MEDIUM | Workflow JSON parse error — skip workflow, continue |
| `PREREQ_MISSING` | 1c | LOW | No source code under SOURCE/backend/ — proceed without source analysis |

## Learning Capture

This is an analysis skill — follow the **Learning Capture Protocol** (see CLAUDE.md Cross-Skill Conventions). After mapping the implementation, when the user confirms or corrects findings about feature inventory, cross-feature dependencies, or account-specific conventions, write the confirmed learning to the `implementation-learnings.md` auto-memory file under the relevant account heading.

## Session Tracking

Track: files written (`implementation-map.md`, `features/*.md`, `diagrams/*.mmd`, `gaps.md`), MCP tools called (`plugin.list`, `graphql.query`, `workflow.transitions` — all read-only). No environment mutations.

## Integration with Other Skills

| User Request After Map | Skill to Invoke |
|------------------------|-----------------|
| "Explain feature X in detail" | `/fluent-feature-explain --feature <slug>` |
| "I want to extend feature X" | `/fluent-use-case-discover` (with context from the map) |
| "Turn this into lifecycle features" | `/fluent-scope-decompose` (from the feature inventory) |
| "Show the full connection topology" | `/fluent-connection-analysis --deep --mermaid` |
| "Analyze the custom code" | `/fluent-custom-code` |
| "Is this production-ready?" | `/fluent-rfl-assess` |
| "Show me the workspace structure" | `/fluent-workspace-tree` |

## Cross-References

- Per-feature deep dive: `/fluent-feature-explain`
- Workflow structure: `/fluent-workflow-analyzer`
- Connection topology: `/fluent-connection-analysis`
- Custom code behavior: `/fluent-custom-code`
- Settings audit: `/fluent-settings`
- Scope decomposition: `/fluent-scope-decompose`
- Production readiness: `/fluent-rfl-assess`
- MCP tool reference: `/fluent-mcp-tools` -> `plugin.list`, `graphql.query`, `workflow.transitions`
