@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-implementation-map/SKILL.md

@@ -0,0 +1,644 @@
+---
+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]
+---
+
+# 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 SAGIRISH --retailer "Module Test"
+/fluent-implementation-map --profile HMDEV --retailer HM_TEST --depth detailed
+/fluent-implementation-map --profile HMDEV --retailer HM_TEST --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>/`.
+
+---
+
+## 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>/
+   ```
+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/` 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.
+
+---
+
+## 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 `/fluent-mermaid-validate` 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/`:
+- 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 `/fluent-mermaid-validate` 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/` 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": "HMDEV",
+  "retailer": "HM_TEST",
+  "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-v1",
+  "feature": "home-delivery",
+  "retailers": ["HM_TEST"],
+  "status": "DISCOVERY",
+  "created": "2026-02-25",
+  "updated": "2026-02-25",
+  "spec": null,
+  "plan": 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/ 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
+```
+
+## 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/ — 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`

package/content/dev/skills/fluent-job-batch/SKILL.md

@@ -2,6 +2,7 @@
 name: fluent-job-batch
 description: Diagnose and monitor JOB/BATCH orchestration entity lifecycles in Fluent Commerce. Covers JOB and BATCH entity workflows, status tracking, failure investigation, and performance monitoring. Distinct from batch data ingestion API. Triggers on "job batch", "batch management", "job lifecycle", "job status", "batch monitoring", "batch operations", "job entity".
 user-invocable: true
+read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--job-id <id>] [--batch-id <id>] [--status ACTIVE|COMPLETED|FAILED]
 ---
@@ -19,6 +20,10 @@ This skill owns JOB/BATCH entity lifecycle diagnostics and monitoring.
 - **Root cause diagnosis** → `/fluent-trace`
 - **Workflow structure** → `/fluent-workflow-analyzer`
 
+## Skill Type: Reference
+
+This is a **reference skill** — it provides diagnostic patterns and monitoring guidance for JOB/BATCH entity lifecycles but does not modify code or environments. Implementation changes (workflow edits, batch API calls) should be delegated to the appropriate skills listed in the Ownership Boundary above.
+
 ## Disambiguation: JOB/BATCH Orchestration vs Batch Ingestion API
 
 | Concept | What It Is | Skill |
@@ -89,6 +94,8 @@ event.list({
 })
 ```
 
+> **Canonical reference:** See `/fluent-event-api` for complete event status values, filter syntax, and query patterns.
+
 ### Query JOB Entity State
 ```graphql
 {
@@ -113,6 +120,9 @@ Note: The `jobs` GraphQL query root may not exist in all Fluent versions. If una
 ## Troubleshooting
 
 ### JOB Stuck in ACTIVE
+
+> **Event filter reference:** For complete filter syntax, see `/fluent-event-api`. The examples below show batch-specific patterns.
+
 1. Check if batches are still processing: query BATCH events for the JOB
 2. Check if auto-close time has passed (midnight UTC)
 3. Check for exceptions: `event.list({ category: "exception", "context.rootEntityType": "JOB", "context.rootEntityId": "<ID>" })`