@fluentcommerce/ai-skills 0.1.0

package/content/dev/skills/fluent-scope-decompose/SKILL.md

@@ -0,0 +1,1021 @@
+---
+name: fluent-scope-decompose
+description: Decompose a structured scope document into an ordered task list with dependencies, skill mappings, and ambiguity detection. Converts ADD scope packs into executable agent work plans. Triggers on "decompose scope", "plan from scope", "task breakdown", "scope to tasks", "parse scope document".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <scope-file-path> [--output-format json|markdown] [--validate-only]
+---
+
+# Scope-to-Task Decomposition
+
+Parse a structured scope document (Markdown following the ADD template) and produce a JSON task list with dependency ordering, skill mappings, and ambiguity flags. This bridges the gap between human-authored scope and agent-executable work — ADD Phase 2: Agent Planning.
+
+## Ownership Boundary
+
+This skill owns scope document parsing, task generation, dependency DAG construction, ambiguity detection, and the output task list artifact.
+
+Other skills own:
+- Module scaffolding execution --> `/fluent-module-scaffold`
+- Rule scaffolding execution --> `/fluent-rule-scaffold`
+- Workflow editing --> `/fluent-workflow-builder`
+- Build orchestration --> `/fluent-build`
+- Deployment --> `/fluent-module-deploy`
+- Session orchestration across tasks --> `/fluent-dev` agent
+
+This skill produces the plan; other skills execute it.
+
+## When to Use
+
+- A structured scope document (ADD template) exists and needs to be converted into an actionable work plan
+- Starting a new module development cycle and need to know what tasks are required
+- Validating a scope document for completeness before agent work begins
+- Generating a traceability matrix from stories to tasks
+- Identifying ambiguities or gaps in a scope document that need human resolution before agents can proceed
+
+## Inputs
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `scope-file-path` | Yes | -- | Path to the scope document (Markdown) |
+| `--output-format` | No | `json` | Output format: `json` (machine-readable) or `markdown` (human-readable) |
+| `--validate-only` | No | `false` | Only validate the scope document structure without generating tasks |
+| `--profile` | No | Active profile | Target Fluent profile for environment-aware decomposition |
+
+## Scope Document Format
+
+The skill expects a Markdown document with sections following the ADD template. All section headings are case-insensitive. Sections may appear in any order. The `Module` and `Objective` sections are required; all others are optional but recommended.
+
+```markdown
+# Module
+<module-identifier>
+
+## Objective
+<business context and goal>
+
+## User stories
+- [US-NNN] As a <role>, I can <action>
+- [US-NNN] As a <role>, I can <action>
+
+## Acceptance criteria
+- Given <condition>, when <trigger>, then <outcome>
+- Given <condition>, when <trigger>, then <outcome>
+
+## Non-functional requirements
+- <requirement with measurable threshold>
+
+## Constraints
+- <constraint_keyword>
+
+## Interfaces
+- <system/module name> (<details>)
+
+## Conventions
+- <convention>
+
+## Artifacts requested
+- <artifact-type> (<details>)
+
+## Deployment targets
+- <target-account/retailer>
+- feature flag: <flag.name>
+```
+
+### Section Extraction Rules
+
+Each section maps to specific task properties during decomposition:
+
+| Section | Extraction Logic | Maps To |
+|---------|-----------------|---------|
+| `Module` | First non-empty line after heading | `task.module` for all generated tasks; used as directory/file name stem |
+| `Objective` | All text until next heading | `task.context` — injected as business context into every generated task description |
+| `User stories` | Parse lines matching `[US-NNN]` pattern; extract identifier + role + action | Individual task groups — each story generates one or more tasks |
+| `Acceptance criteria` | Parse Given/When/Then triples (single-line or multi-line Gherkin) | `task.acceptanceCriteria[]` on the corresponding TEST tasks |
+| `Non-functional requirements` | Parse as constraint list; extract numeric thresholds where present | Quality gate parameters on BUILD, TEST_E2E, and CHECKLIST tasks |
+| `Constraints` | Keyword extraction (`backward_compatible`, `no_pii_in_logs`, etc.) | `constraints` object — applied as guard rails across all generated tasks |
+| `Interfaces` | System/module names with optional details | Dependency declarations; flag as ambiguity if no skill mapping exists |
+| `Conventions` | Free text conventions | Injected into SCAFFOLD and BUILD task descriptions |
+| `Artifacts requested` | Artifact type keywords (Code, Workflow, Tests, Docs, etc.) | Drive task type assignments — each artifact maps to one or more task types |
+| `Deployment targets` | Account/retailer refs and feature flags | DEPLOY and CONFIG task targets |
+
+### Story Identifier Parsing
+
+Story identifiers follow the pattern `[US-NNN]` where NNN is any alphanumeric sequence. The parser:
+
+1. Scans each bullet line under `## User stories` for a `[` prefix
+2. Extracts the identifier between `[` and `]`
+3. Extracts the description after the `]` (trimmed)
+4. Deduplicates by identifier — if the same ID appears twice, flag as ambiguity
+
+### Acceptance Criteria Parsing
+
+Acceptance criteria follow Given/When/Then structure. The parser supports:
+
+- **Single-line:** `Given X, when Y, then Z`
+- **Multi-line Gherkin:**
+  ```
+  - Given multiple profile variants and a traffic split
+    When requests are routed
+    Then variants receive traffic according to the split within +/-1% error
+  ```
+- **Free-form:** Lines not matching Given/When/Then are treated as unstructured criteria and attached verbatim
+
+Criteria are linked to stories by proximity or explicit `[US-NNN]` references within the criteria text.
+
+## Task List JSON Schema
+
+The output is a JSON document containing the full decomposition:
+
+```json
+{
+  "schema": "scope-decomposition-v1",
+  "scopeDocument": "path/to/scope.md",
+  "module": "fcx.sourcing.abtesting",
+  "generatedAt": "2026-02-23T10:00:00Z",
+  "profile": "HMDEV",
+  "tasks": [
+    {
+      "id": "T-001",
+      "type": "SCAFFOLD",
+      "title": "Scaffold module fcx.sourcing.abtesting",
+      "description": "Create module skeleton with entity types ORDER, FULFILMENT",
+      "skill": "fluent-module-scaffold",
+      "dependsOn": [],
+      "storyRef": null,
+      "inputs": {
+        "module-name": "sourcing-abtesting",
+        "entity-types": ["ORDER"]
+      },
+      "acceptanceCriteria": [],
+      "priority": 1,
+      "status": "pending"
+    }
+  ],
+  "ambiguities": [],
+  "constraints": {},
+  "traceabilityMatrix": {},
+  "nfrs": [],
+  "deploymentTargets": []
+}
+```
+
+### Task Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier, pattern `T-NNN` (zero-padded, assigned in topological order) |
+| `type` | string | One of the task types from the Task Types table below |
+| `title` | string | Human-readable summary of what this task does |
+| `description` | string | Detailed description including business context from Objective |
+| `skill` | string | The exact skill name to invoke for execution (e.g., `fluent-rule-scaffold`) |
+| `dependsOn` | string[] | Array of task IDs that must complete before this task can start |
+| `storyRef` | string or null | The `[US-NNN]` identifier this task traces to, or null for infrastructure tasks |
+| `inputs` | object | Key-value pairs passed to the skill at execution time |
+| `acceptanceCriteria` | string[] | Given/When/Then triples that define done for this task |
+| `priority` | number | Execution order (1 = first); derived from topological sort position |
+| `status` | string | Always `"pending"` at generation time |
+
+## Task Types
+
+Every task has a type that determines which skill executes it and what its default dependencies are.
+
+| Type | Skill Mapping | Description | Typical Dependencies |
+|------|--------------|-------------|---------------------|
+| `SCAFFOLD` | `fluent-module-scaffold` | Create new module skeleton with Maven structure, module.json, build scripts | None (always first for new modules) |
+| `EXTEND` | `fluent-rule-scaffold` | Add rules/functionality to an existing module whose source is already in `SOURCE/` | SOURCE_ONBOARD (if source was missing) or none (if source already present) |
+| `SOURCE_ONBOARD` | `fluent-custom-code` | Clone repo or obtain source code for an existing deployed module into `accounts/<PROFILE>/SOURCE/` and analyze it | None (always first for extending existing modules) |
+| `RULE` | `fluent-rule-scaffold` | Scaffold a new Rubix rule class with @RuleInfo, parameters, and test skeleton | SCAFFOLD or EXTEND |
+| `WORKFLOW` | `fluent-workflow-builder` | Create or modify workflow JSON — add rulesets, statuses, triggers | RULE (rules must exist before wiring into rulesets) |
+| `SETTING` | `fluent-settings` | Create or update retailer/account settings required by rules | SCAFFOLD or EXTEND |
+| `TEST_UNIT` | `fluent-build` | Write or run unit tests for rule classes | RULE |
+| `TEST_E2E` | `fluent-e2e-test` | Run end-to-end test sequences against deployed workflows | WORKFLOW_DEPLOY, DEPLOY |
+| `BUILD` | `fluent-build` | Compile, package, and produce deployable ZIP artifact | RULE, WORKFLOW (all code changes must be complete) |
+| `DEPLOY` | `fluent-module-deploy` | Deploy module ZIP to target Fluent account/retailer | BUILD, VALIDATE |
+| `WORKFLOW_DEPLOY` | `fluent-workflow` | Upload workflow JSON to target retailer | WORKFLOW |
+| `CONFIG` | `fluent-retailer-config` | Configure retailer-level settings, feature flags, and sample data | DEPLOY (retailer must have module installed) |
+| `VALIDATE` | `fluent-module-validate` | Run structural validation on the module before deployment | BUILD |
+| `ANALYZE` | `fluent-connection-analysis` | Analyze workflow connection topology and cross-entity event flows | WORKFLOW_DEPLOY |
+| `DOC` | Manual / agent | Generate README, Confluence pages, or other documentation | BUILD |
+| `VERSION` | `fluent-version-manage` | Bump semver version, update CHANGELOG, sync all version files | BUILD passes |
+| `CHECKLIST` | `fluent-pre-deploy-check` | Run full pre-deployment checklist across all gates | All prior tasks |
+
+## Dependency Resolution Algorithm
+
+The skill constructs a directed acyclic graph (DAG) of task dependencies and produces a topologically sorted execution order.
+
+### Step 1: Environment-Aware Module Decision
+
+**Before generating any tasks, determine whether this is a new module or an extension of an existing one.**
+
+```
+1. Extract module name from scope document's ## Module section
+
+2. Search local workspace for existing source:
+   Glob: accounts/<PROFILE>/SOURCE/*/resources/module.json
+   Parse each module.json → build list of local modules with their rule names
+
+3. Query deployed modules in live environment:
+   MCP tool: plugin.list (compact: true)
+   Parse rule keys → extract module names (group by ACCOUNT prefix)
+
+4. Decision tree:
+   ├── Module source found in accounts/<PROFILE>/SOURCE/?
+   │   └── YES → EXTEND path
+   │       - Generate EXTEND task (not SCAFFOLD)
+   │       - RULE tasks depend on EXTEND
+   │       - inputs.existingModulePath = path to source directory
+   │
+   ├── Module deployed (rules in plugin.list) but NO source in SOURCE/?
+   │   └── SOURCE_ONBOARD path
+   │       - Generate SOURCE_ONBOARD task first (clone repo / obtain source)
+   │       - Generate EXTEND task (depends on SOURCE_ONBOARD)
+   │       - RULE tasks depend on EXTEND
+   │       - Flag ambiguity if repo URL is unknown
+   │
+   └── Module NOT found anywhere?
+       └── SCAFFOLD path (new module)
+           - Generate SCAFFOLD task
+           - RULE tasks depend on SCAFFOLD
+```
+
+### Step 2: Generate Tasks from Scope Sections
+
+```
+For each section in the scope document:
+  Module       -> generate 1 SCAFFOLD, EXTEND, or SOURCE_ONBOARD+EXTEND task (per Step 1 decision)
+  User stories -> for each story, generate RULE and/or WORKFLOW tasks based on story content
+  Acceptance criteria -> generate TEST_UNIT and TEST_E2E tasks
+  Artifacts requested -> generate task types matching the artifact keyword:
+    "Code"      -> RULE (if not already generated from stories)
+    "Workflow"   -> WORKFLOW
+    "Tests"      -> TEST_UNIT + TEST_E2E
+    "Docs"       -> DOC
+    "Settings"   -> SETTING
+    "OMX Components" -> flag as ambiguity (no skill mapping)
+  Deployment targets -> generate DEPLOY, WORKFLOW_DEPLOY, CONFIG tasks
+  Always generate: BUILD, VALIDATE, VERSION, CHECKLIST (infrastructure tasks)
+```
+
+### Step 3: Build Dependency Edges
+
+Apply these rules to construct edges in the DAG:
+
+```
+SCAFFOLD        -> no dependencies (new module path)
+SOURCE_ONBOARD  -> no dependencies (extend-without-source path)
+EXTEND          -> depends on SOURCE_ONBOARD if source was missing; else no dependencies
+RULE            -> depends on SCAFFOLD (new) or EXTEND (existing)
+WORKFLOW        -> depends on all RULE tasks that the workflow references
+SETTING         -> depends on SCAFFOLD or EXTEND
+TEST_UNIT       -> depends on the RULE task it tests
+BUILD           -> depends on all RULE + WORKFLOW + SETTING tasks
+VALIDATE        -> depends on BUILD
+DEPLOY          -> depends on BUILD + VALIDATE
+WORKFLOW_DEPLOY -> depends on all WORKFLOW tasks
+TEST_E2E        -> depends on DEPLOY + WORKFLOW_DEPLOY
+CONFIG          -> depends on DEPLOY
+DOC             -> depends on BUILD
+VERSION         -> depends on BUILD (build must pass before version bump)
+CHECKLIST       -> depends on all other tasks (always last)
+```
+
+### Step 4: Cycle Detection
+
+Run a depth-first search on the DAG. If a back edge is found, report the cycle and abort with an error:
+
+```
+ERROR: Circular dependency detected: T-003 -> T-005 -> T-008 -> T-003
+       Resolve the cycle in the scope document before decomposition can proceed.
+```
+
+### Step 5: Topological Sort
+
+Perform Kahn's algorithm (BFS-based topological sort) on the validated DAG:
+
+```
+1. Compute in-degree for each task node
+2. Enqueue all nodes with in-degree 0
+3. While queue is not empty:
+   a. Dequeue node, assign next priority number
+   b. For each outgoing edge, decrement target in-degree
+   c. If target in-degree reaches 0, enqueue it
+4. If processed count < total tasks -> cycle exists (caught in Step 3)
+```
+
+The priority field on each task reflects its position in the topological order.
+
+## Ambiguity Detection
+
+The skill flags ambiguities that require human resolution before agents can execute the task list.
+
+| Condition | Severity | Detection Rule | Example |
+|-----------|----------|---------------|---------|
+| Interface has no skill mapping | HIGH | Interface name does not match any known skill or MCP tool | "Fluent Analytics (Google Looker)" -- no skill covers Looker dashboard creation |
+| Acceptance criteria references unmeasurable metric | MEDIUM | Criteria contains percentage, statistical term, or threshold that cannot be verified by existing test tools | "within +/-1% error over sufficient volume" -- needs statistical validation |
+| User story lacks acceptance criteria | HIGH | Story ID from `## User stories` has no matching criteria in `## Acceptance criteria` | Story [US-203] exists but no Given/When/Then references it |
+| Artifact type has no skill mapping | MEDIUM | Artifact keyword does not match any known task type | "OMX Components" -- no skill covers OMX creation |
+| Constraint keyword is unknown | LOW | Keyword not in known set: `backward_compatible`, `no_pii_in_logs`, `no_breaking_changes`, `idempotent`, `audit_trail` | "gdpr_compliant" -- recognized but no automated enforcement |
+| Non-functional requirement lacks threshold | MEDIUM | NFR line has no numeric value or measurable bound | "high availability" without an SLA percentage |
+| Duplicate story identifiers | HIGH | Two or more stories share the same `[US-NNN]` identifier | `[US-201]` appears twice with different descriptions |
+| Deployment target unresolvable | MEDIUM | Target does not match known profile/retailer pattern | "fluent:account/retailer-demo" when no matching profile exists |
+
+### Ambiguity Output Format
+
+```json
+{
+  "section": "Interfaces",
+  "item": "Fluent Analytics (Google Looker)",
+  "issue": "No skill or MCP tool covers Looker dashboard creation. Requires manual implementation or external tooling.",
+  "severity": "HIGH"
+}
+```
+
+## Traceability Matrix
+
+The skill produces a mapping from every user story to the tasks generated from it, enabling end-to-end traceability from requirement to implementation:
+
+```json
+{
+  "US-201": ["T-002", "T-003", "T-007", "T-012"],
+  "US-202": ["T-004", "T-005", "T-008"],
+  "US-203": ["T-006", "T-009"]
+}
+```
+
+**Coverage validation:** After building the matrix, check that:
+1. Every story has at least one task -> if not, flag as ambiguity (story with no work)
+2. Every task with a `storyRef` maps back to a valid story -> if not, flag as orphaned task
+3. Every story has at least one TEST task -> if not, flag as untested story (severity: HIGH)
+
+## Execution Flow
+
+```
+1. READ scope document from file path
+   - Validate file exists and is readable
+   - Parse as Markdown (split by heading levels)
+
+2. VALIDATE structure:
+   a. Check required sections present (Module, Objective)
+   b. Check recommended sections present (User stories, Acceptance criteria, Artifacts)
+   c. Parse user story identifiers [US-NNN] — validate uniqueness
+   d. Parse acceptance criteria — extract Given/When/Then triples
+   e. Parse constraints — extract known keywords
+   f. If --validate-only:
+      - Report section presence/absence table
+      - Report parsed story count, criteria count, constraint count
+      - Report any structural issues found
+      - STOP (do not generate tasks)
+
+3. DECOMPOSE into tasks:
+   a. Run environment-aware module decision (see Dependency Resolution Step 1):
+      - Search accounts/<PROFILE>/SOURCE/ for existing module source
+      - Query plugin.list for deployed custom rules
+      - Decision: SCAFFOLD (new) / EXTEND (source available) / SOURCE_ONBOARD+EXTEND (deployed but no source)
+      - Extract module name, derive entity types from stories/interfaces
+   b. For each user story, generate RULE and/or WORKFLOW tasks
+      - Analyze story text for rule-like behavior ("route", "allocate", "validate")
+      - Analyze story text for workflow-like behavior ("status", "transition", "flow")
+   c. For each acceptance criterion, generate TEST tasks
+      - Unit test tasks for rule-level criteria
+      - E2E test tasks for workflow-level criteria
+   d. For each artifact requested, generate corresponding task type
+      - Map artifact keywords to task types (see Task Types table)
+   e. Generate infrastructure tasks: BUILD, VALIDATE, DEPLOY, VERSION, CHECKLIST
+   f. Generate SETTING tasks for any rule that references settings
+   g. Generate CONFIG tasks for deployment targets with feature flags
+
+4. RESOLVE dependencies:
+   a. Build adjacency list from dependency rules
+   b. Run cycle detection (DFS)
+   c. Run topological sort (Kahn's algorithm)
+   d. Assign priority numbers from sort order
+
+5. DETECT ambiguities:
+   a. Check all interfaces against known skill mappings
+   b. Check all acceptance criteria for measurability
+   c. Check all stories for criteria coverage
+   d. Check all artifact types for skill mappings
+   e. Check all constraints for known keywords
+   f. Check all NFRs for numeric thresholds
+   g. Check deployment targets for resolvability
+
+6. BUILD traceability matrix:
+   a. Map each story ID to its generated task IDs
+   b. Validate coverage (every story has tasks, every story has tests)
+
+7. WRITE output:
+   a. JSON task list to:
+      accounts/<PROFILE>/analysis/scope-decomposition/<module>.tasks.json
+   b. If --output-format markdown, also write human-readable table to:
+      accounts/<PROFILE>/analysis/scope-decomposition/<module>.tasks.md
+
+8. REPORT summary:
+   - Total tasks generated (by type)
+   - Ambiguities found (by severity)
+   - Coverage: stories with tasks, stories with tests
+   - Dependency chain depth (longest path in DAG)
+   - Output file paths
+```
+
+## Output Paths
+
+Task list artifacts are written to the analysis directory scoped by profile:
+
+```
+accounts/<PROFILE>/analysis/scope-decomposition/
+  <module>.tasks.json       <- Machine-readable task list (primary output)
+  <module>.tasks.md         <- Human-readable table (when --output-format markdown)
+```
+
+The `<module>` stem is derived from the scope document's `# Module` section with dots replaced by dashes and lowercased (e.g., `fcx.sourcing.abtesting` becomes `fcx-sourcing-abtesting`).
+
+## Integration with fluent-dev Agent
+
+The task list produced by this skill is consumed by the `/fluent-dev` orchestration agent:
+
+1. `/fluent-dev` reads `<module>.tasks.json` from the analysis directory
+2. For each task in priority order:
+   a. Check `dependsOn` — all dependencies must have `status: "completed"`
+   b. Invoke the skill named in `task.skill` with `task.inputs` as arguments
+   c. On success: update `task.status` to `"completed"`
+   d. On failure: update `task.status` to `"failed"`, log error, assess whether to continue or abort
+3. After all tasks complete, update the traceability matrix with completion status
+4. If any ambiguities have severity HIGH, pause and request human resolution before proceeding past the affected tasks
+
+The task list is a living document — `/fluent-dev` updates it in-place as work progresses.
+
+## Edge Cases
+
+### Module Already Exists
+
+If the environment-aware check (Step 1) finds the module already deployed or has local source:
+
+| State | First Task(s) | Subsequent RULE depends on |
+|-------|--------------|---------------------------|
+| Source in `SOURCE/` with `module.json` | `EXTEND` (no dependencies) | `EXTEND` |
+| Deployed but no source in `SOURCE/` | `SOURCE_ONBOARD` → `EXTEND` | `EXTEND` |
+| Not found anywhere | `SCAFFOLD` (classic new module) | `SCAFFOLD` |
+| Source exists but repo URL unknown | `SOURCE_ONBOARD` with ambiguity flag | `EXTEND` |
+
+**When extending:** The EXTEND task's `inputs.existing-module-path` tells downstream skills where to find the existing POM, `module.json`, and package structure. The `/fluent-rule-scaffold` skill uses this to wire new rules into the correct package and registration.
+
+### Missing Sections
+
+If optional sections are missing, the skill generates a minimal task list:
+
+| Missing Section | Behavior |
+|----------------|----------|
+| `User stories` | Generate only SCAFFOLD/EXTEND + BUILD + VALIDATE tasks; flag as ambiguity: "No user stories — task list is infrastructure-only" |
+| `Acceptance criteria` | Generate all tasks but no TEST tasks; flag each story as untested (HIGH severity) |
+| `Artifacts requested` | Infer artifact types from user stories (Code implies RULE, Workflow implies WORKFLOW) |
+| `Deployment targets` | Skip DEPLOY, WORKFLOW_DEPLOY, CONFIG, CHECKLIST tasks; flag as ambiguity |
+| `Constraints` | Empty constraints object; no guard rails applied |
+| `Interfaces` | No interface-related ambiguity checks |
+| `Non-functional requirements` | No NFR-related ambiguity checks |
+
+### Duplicate Story IDs
+
+If two stories share the same `[US-NNN]` identifier:
+
+1. Flag as HIGH severity ambiguity
+2. Keep the first occurrence and rename the second to `[US-NNN-DUP]`
+3. Generate tasks for both but mark the duplicate's tasks with a warning
+
+### Circular Dependencies
+
+If the dependency resolution algorithm detects a cycle:
+
+1. Report the cycle path: `T-003 -> T-005 -> T-008 -> T-003`
+2. Identify the likely cause (usually a WORKFLOW depending on a TEST that depends on the WORKFLOW)
+3. Suggest resolution: break the cycle by removing the weakest dependency edge
+4. Abort task list generation — a valid DAG is required
+
+### Unknown Artifact Types
+
+If an artifact type in `## Artifacts requested` does not match any known mapping:
+
+1. Flag as MEDIUM severity ambiguity
+2. Generate a DOC-type task as a placeholder with the description: "Manual: create <artifact-type>"
+3. The placeholder task has no skill mapping (`skill: null`)
+
+### Empty Scope Document
+
+If the file is empty or contains only headings with no content:
+
+1. Return a validation error: "Scope document is empty or contains no actionable content"
+2. List which sections were found (headings only) vs which had content
+3. Do not generate any tasks
+
+## Example
+
+### Input: Scope Document
+
+```markdown
+# Module
+fcx.sourcing.abtesting
+
+## Objective
+Extend sourcing profiles to support A/B testing so we can compare profile
+variants on conversion, latency, and cost in demo scenarios.
+
+## User stories
+- [US-201] As a merchandiser, I can define two or more sourcing profile
+  variants (A/B/...) for an experiment.
+- [US-202] As a merchandiser, I can allocate traffic splits (e.g., 50/50,
+  10/90) across variants.
+- [US-203] As an analyst, I can view experiment results with metrics per
+  variant in Fluent Analytics.
+
+## Acceptance criteria
+- Given multiple profile variants and a traffic split, when requests are
+  routed, then variants receive traffic according to the split within
+  +/-1% error over sufficient volume.
+- Given an active experiment, when a variant underperforms thresholds,
+  then the system can pause/adjust the split via config without redeploy.
+- Given experiment data, when results are requested, then metrics
+  (conversion, p95 latency, cost per order) are reported per variant.
+
+## Non-functional requirements
+- p95 latency: +<5 ms overhead from routing logic.
+- Availability: 99.9%.
+- Auditability: experiment definitions and changes are versioned.
+
+## Constraints
+- backward_compatible
+- no_pii_in_logs
+
+## Interfaces
+- Fluent AI Skills (Fluent CLI, Fluent MCP)
+- Fluent Analytics (Google Looker)
+
+## Conventions
+- Testing: unit (routing), contract (Profile APIs), smoke (experiment
+  start/stop), golden (metrics aggregation).
+- Versioning: semver
+
+## Artifacts requested
+- Code (new or updated orchestration rules)
+- Orchestration Workflow (updated orchestration workflow)
+- Tests (unit / orchestration / end to end)
+- Docs (README, Confluence)
+
+## Deployment targets
+- fluent:account/retailer-demo
+- feature flag: sourcing.abtest.enabled
+```
+
+### Output: Task List (JSON)
+
+```json
+{
+  "schema": "scope-decomposition-v1",
+  "scopeDocument": "scope/sourcing-abtesting.md",
+  "module": "fcx.sourcing.abtesting",
+  "generatedAt": "2026-02-23T10:00:00Z",
+  "profile": "HMDEV",
+  "tasks": [
+    {
+      "id": "T-001",
+      "type": "SCAFFOLD",
+      "title": "Scaffold module fcx.sourcing.abtesting",
+      "description": "Create module skeleton for sourcing A/B testing. Entity type: ORDER. Includes Maven structure, module.json, build scripts, and test harness.",
+      "skill": "fluent-module-scaffold",
+      "dependsOn": [],
+      "storyRef": null,
+      "inputs": {
+        "module-name": "sourcing-abtesting",
+        "entity-types": ["ORDER"],
+        "rules": ["ExperimentVariantRouter", "TrafficSplitAllocator", "ExperimentConfigReader"]
+      },
+      "acceptanceCriteria": [],
+      "priority": 1,
+      "status": "pending"
+    },
+    {
+      "id": "T-002",
+      "type": "RULE",
+      "title": "Implement experiment variant definition rule",
+      "description": "Rule to allow defining two or more sourcing profile variants (A/B/...) for an experiment. Reads experiment config from settings, registers variants on the entity.",
+      "skill": "fluent-rule-scaffold",
+      "dependsOn": ["T-001"],
+      "storyRef": "US-201",
+      "inputs": {
+        "rule-name": "ExperimentVariantRouter",
+        "entity-type": "ORDER"
+      },
+      "acceptanceCriteria": [],
+      "priority": 2,
+      "status": "pending"
+    },
+    {
+      "id": "T-003",
+      "type": "RULE",
+      "title": "Implement traffic split allocation rule",
+      "description": "Rule to allocate traffic across sourcing profile variants based on configured percentage splits (e.g., 50/50, 10/90).",
+      "skill": "fluent-rule-scaffold",
+      "dependsOn": ["T-001"],
+      "storyRef": "US-202",
+      "inputs": {
+        "rule-name": "TrafficSplitAllocator",
+        "entity-type": "ORDER"
+      },
+      "acceptanceCriteria": [
+        "Given multiple profile variants and a traffic split, when requests are routed, then variants receive traffic according to the split within +/-1% error over sufficient volume."
+      ],
+      "priority": 3,
+      "status": "pending"
+    },
+    {
+      "id": "T-004",
+      "type": "RULE",
+      "title": "Implement experiment config reader rule",
+      "description": "Rule to read experiment configuration (variant definitions, split ratios, pause/adjust state) from retailer settings without requiring redeploy.",
+      "skill": "fluent-rule-scaffold",
+      "dependsOn": ["T-001"],
+      "storyRef": "US-202",
+      "inputs": {
+        "rule-name": "ExperimentConfigReader",
+        "entity-type": "ORDER"
+      },
+      "acceptanceCriteria": [
+        "Given an active experiment, when a variant underperforms thresholds, then the system can pause/adjust the split via config without redeploy."
+      ],
+      "priority": 4,
+      "status": "pending"
+    },
+    {
+      "id": "T-005",
+      "type": "SETTING",
+      "title": "Create experiment configuration settings",
+      "description": "Create retailer-scoped settings for experiment definitions, variant splits, and threshold configuration. Settings must be updatable without module redeploy.",
+      "skill": "fluent-settings",
+      "dependsOn": ["T-001"],
+      "storyRef": "US-202",
+      "inputs": {
+        "settings": [
+          { "name": "sourcing.experiment.config", "context": "RETAILER" },
+          { "name": "sourcing.experiment.thresholds", "context": "RETAILER" }
+        ]
+      },
+      "acceptanceCriteria": [],
+      "priority": 5,
+      "status": "pending"
+    },
+    {
+      "id": "T-006",
+      "type": "WORKFLOW",
+      "title": "Add A/B test rulesets to ORDER sourcing workflow",
+      "description": "Extend the ORDER workflow with rulesets for experiment routing: insert ExperimentVariantRouter and TrafficSplitAllocator into the sourcing event chain. Add statuses if needed for experiment branching.",
+      "skill": "fluent-workflow-builder",
+      "dependsOn": ["T-002", "T-003", "T-004"],
+      "storyRef": "US-201",
+      "inputs": {
+        "workflow-type": "ORDER",
+        "rulesets-to-add": ["ExperimentRouting"]
+      },
+      "acceptanceCriteria": [],
+      "priority": 6,
+      "status": "pending"
+    },
+    {
+      "id": "T-007",
+      "type": "TEST_UNIT",
+      "title": "Write unit tests for routing and split rules",
+      "description": "Unit tests for ExperimentVariantRouter, TrafficSplitAllocator, and ExperimentConfigReader. Cover: correct split distribution, config read/parse, edge cases (0% split, 100% split, missing config).",
+      "skill": "fluent-build",
+      "dependsOn": ["T-002", "T-003", "T-004"],
+      "storyRef": "US-201",
+      "inputs": {},
+      "acceptanceCriteria": [
+        "Given multiple profile variants and a traffic split, when requests are routed, then variants receive traffic according to the split within +/-1% error over sufficient volume."
+      ],
+      "priority": 7,
+      "status": "pending"
+    },
+    {
+      "id": "T-008",
+      "type": "BUILD",
+      "title": "Build module fcx.sourcing.abtesting",
+      "description": "Compile all rule classes, run unit tests, and package into deployable ZIP artifact.",
+      "skill": "fluent-build",
+      "dependsOn": ["T-002", "T-003", "T-004", "T-005", "T-006", "T-007"],
+      "storyRef": null,
+      "inputs": {},
+      "acceptanceCriteria": [],
+      "priority": 8,
+      "status": "pending"
+    },
+    {
+      "id": "T-009",
+      "type": "VALIDATE",
+      "title": "Validate module structure",
+      "description": "Run /fluent-module-validate to confirm module.json, Maven structure, rule wiring, test coverage, and version consistency.",
+      "skill": "fluent-module-validate",
+      "dependsOn": ["T-008"],
+      "storyRef": null,
+      "inputs": {},
+      "acceptanceCriteria": [],
+      "priority": 9,
+      "status": "pending"
+    },
+    {
+      "id": "T-010",
+      "type": "VERSION",
+      "title": "Bump version to 1.0.0",
+      "description": "Set initial release version across module.json, all POMs, and CHANGELOG.md. Tag as v1.0.0.",
+      "skill": "fluent-version-manage",
+      "dependsOn": ["T-008"],
+      "storyRef": null,
+      "inputs": {
+        "command": "bump",
+        "level": "minor"
+      },
+      "acceptanceCriteria": [],
+      "priority": 10,
+      "status": "pending"
+    },
+    {
+      "id": "T-011",
+      "type": "DEPLOY",
+      "title": "Deploy module to retailer-demo",
+      "description": "Deploy fc-module-sourcing-abtesting ZIP to fluent:account/retailer-demo.",
+      "skill": "fluent-module-deploy",
+      "dependsOn": ["T-008", "T-009"],
+      "storyRef": null,
+      "inputs": {
+        "target": "fluent:account/retailer-demo"
+      },
+      "acceptanceCriteria": [],
+      "priority": 11,
+      "status": "pending"
+    },
+    {
+      "id": "T-012",
+      "type": "WORKFLOW_DEPLOY",
+      "title": "Deploy updated ORDER workflow",
+      "description": "Upload the modified ORDER workflow with A/B test rulesets to the target retailer.",
+      "skill": "fluent-workflow",
+      "dependsOn": ["T-006"],
+      "storyRef": null,
+      "inputs": {},
+      "acceptanceCriteria": [],
+      "priority": 12,
+      "status": "pending"
+    },
+    {
+      "id": "T-013",
+      "type": "CONFIG",
+      "title": "Configure feature flag and experiment settings",
+      "description": "Enable feature flag sourcing.abtest.enabled on target retailer. Populate initial experiment configuration settings.",
+      "skill": "fluent-retailer-config",
+      "dependsOn": ["T-011"],
+      "storyRef": null,
+      "inputs": {
+        "feature-flag": "sourcing.abtest.enabled"
+      },
+      "acceptanceCriteria": [],
+      "priority": 13,
+      "status": "pending"
+    },
+    {
+      "id": "T-014",
+      "type": "TEST_E2E",
+      "title": "Run end-to-end experiment routing test",
+      "description": "Create orders against the deployed workflow and verify traffic is split across variants. Confirm experiment config changes take effect without redeploy.",
+      "skill": "fluent-e2e-test",
+      "dependsOn": ["T-011", "T-012", "T-013"],
+      "storyRef": "US-201",
+      "inputs": {},
+      "acceptanceCriteria": [
+        "Given multiple profile variants and a traffic split, when requests are routed, then variants receive traffic according to the split within +/-1% error over sufficient volume.",
+        "Given an active experiment, when a variant underperforms thresholds, then the system can pause/adjust the split via config without redeploy."
+      ],
+      "priority": 14,
+      "status": "pending"
+    },
+    {
+      "id": "T-015",
+      "type": "DOC",
+      "title": "Generate module documentation",
+      "description": "Create README.md with module overview, rule descriptions, configuration guide, and deployment instructions.",
+      "skill": null,
+      "dependsOn": ["T-008"],
+      "storyRef": null,
+      "inputs": {},
+      "acceptanceCriteria": [],
+      "priority": 15,
+      "status": "pending"
+    },
+    {
+      "id": "T-016",
+      "type": "CHECKLIST",
+      "title": "Run pre-deployment checklist",
+      "description": "Execute full pre-deploy validation: environment readiness, module integrity, workflow validity, settings completeness, and risk assessment.",
+      "skill": "fluent-pre-deploy-check",
+      "dependsOn": ["T-008", "T-009", "T-010", "T-011", "T-012", "T-013", "T-014", "T-015"],
+      "storyRef": null,
+      "inputs": {},
+      "acceptanceCriteria": [],
+      "priority": 16,
+      "status": "pending"
+    }
+  ],
+  "ambiguities": [
+    {
+      "section": "Interfaces",
+      "item": "Fluent Analytics (Google Looker)",
+      "issue": "No skill or MCP tool covers Looker dashboard creation. Story US-203 requires metrics visualization in Fluent Analytics, which is outside agent tooling scope. Requires manual implementation or external tooling.",
+      "severity": "HIGH"
+    },
+    {
+      "section": "Acceptance criteria",
+      "item": "within +/-1% error over sufficient volume",
+      "issue": "Statistical validation of traffic distribution requires volume thresholds and statistical testing that existing E2E test tools cannot automate. Manual verification or custom test harness needed.",
+      "severity": "MEDIUM"
+    },
+    {
+      "section": "User stories",
+      "item": "[US-203] view experiment results with metrics per variant",
+      "issue": "Story requires Fluent Analytics dashboard work. No tasks generated for Looker integration — only data-side tasks can be automated.",
+      "severity": "HIGH"
+    }
+  ],
+  "constraints": {
+    "backward_compatible": true,
+    "no_pii_in_logs": true
+  },
+  "traceabilityMatrix": {
+    "US-201": ["T-002", "T-006", "T-007", "T-014"],
+    "US-202": ["T-003", "T-004", "T-005", "T-014"],
+    "US-203": []
+  },
+  "nfrs": [
+    { "requirement": "p95 latency: +<5 ms overhead from routing logic", "threshold": "5ms", "appliesTo": ["T-002", "T-003"] },
+    { "requirement": "Availability: 99.9%", "threshold": "99.9%", "appliesTo": ["T-014"] },
+    { "requirement": "Auditability: experiment definitions and changes are versioned", "threshold": null, "appliesTo": ["T-004", "T-005"] }
+  ],
+  "deploymentTargets": [
+    { "target": "fluent:account/retailer-demo", "featureFlag": "sourcing.abtest.enabled" }
+  ]
+}
+```
+
+### Variation: EXTEND Path (Existing Module)
+
+If the scope document's module matches an existing deployed module with source in `SOURCE/`, the first task changes from SCAFFOLD to EXTEND:
+
+```json
+{
+  "id": "T-001",
+  "type": "EXTEND",
+  "title": "Extend existing module hm-extensions with A/B testing rules",
+  "description": "Module hm-extensions already exists in accounts/HMDEV/SOURCE/fluentcommerce-fc-module-hm-extensions/. Add new rules for A/B testing. Source analyzed — existing rules: SendWebhook, ValidateOrder, ...",
+  "skill": "fluent-rule-scaffold",
+  "dependsOn": [],
+  "storyRef": null,
+  "inputs": {
+    "existing-module-path": "accounts/HMDEV/SOURCE/fluentcommerce-fc-module-hm-extensions/",
+    "entity-types": ["ORDER"],
+    "rules": ["ExperimentVariantRouter", "TrafficSplitAllocator", "ExperimentConfigReader"]
+  },
+  "acceptanceCriteria": [],
+  "priority": 1,
+  "status": "pending"
+}
+```
+
+If the module is deployed but source is **not** in `SOURCE/`, a SOURCE_ONBOARD task precedes EXTEND:
+
+```json
+{
+  "id": "T-001",
+  "type": "SOURCE_ONBOARD",
+  "title": "Obtain source code for module hm-extensions",
+  "description": "Module hm-extensions is deployed (rules found via plugin.list) but no source in accounts/HMDEV/SOURCE/. Clone the repository or decompile the deployed JAR to obtain source before extending.",
+  "skill": "fluent-custom-code",
+  "dependsOn": [],
+  "storyRef": null,
+  "inputs": {
+    "module-name": "hm-extensions",
+    "profile": "HMDEV"
+  },
+  "acceptanceCriteria": [],
+  "priority": 1,
+  "status": "pending"
+},
+{
+  "id": "T-002",
+  "type": "EXTEND",
+  "title": "Extend module hm-extensions with A/B testing rules",
+  "description": "Add new rules to hm-extensions after source onboarding completes.",
+  "skill": "fluent-rule-scaffold",
+  "dependsOn": ["T-001"],
+  "storyRef": null,
+  "inputs": {
+    "entity-types": ["ORDER"],
+    "rules": ["ExperimentVariantRouter", "TrafficSplitAllocator"]
+  },
+  "acceptanceCriteria": [],
+  "priority": 2,
+  "status": "pending"
+}
+```
+
+**Key difference:** When extending, all RULE tasks depend on EXTEND (not SCAFFOLD), and the EXTEND task's inputs include the existing module path so the rule scaffolder knows where to add files.
+
+### Output: Traceability Gaps
+
+From the example above, `US-203` has an empty task array in the traceability matrix. The skill reports this prominently:
+
+```
+TRACEABILITY GAPS
+  [HIGH] US-203 "view experiment results with metrics per variant"
+         -> 0 tasks generated (Fluent Analytics integration outside agent scope)
+         -> Recommend: assign to human for manual Looker dashboard creation
+```
+
+## Console Output Format
+
+After generating the task list, print a human-readable summary:
+
+```
+=== Scope Decomposition: fcx.sourcing.abtesting ===
+
+Source:  scope/sourcing-abtesting.md
+Module:  fcx.sourcing.abtesting
+Profile: HMDEV
+
+Tasks Generated: 16
+  SCAFFOLD:         1
+  RULE:             3
+  WORKFLOW:         1
+  SETTING:          1
+  TEST_UNIT:        1
+  BUILD:            1
+  VALIDATE:         1
+  VERSION:          1
+  DEPLOY:           1
+  WORKFLOW_DEPLOY:  1
+  CONFIG:           1
+  TEST_E2E:         1
+  DOC:              1
+  CHECKLIST:        1
+
+Dependency Chain Depth: 5 (SCAFFOLD -> RULE -> WORKFLOW -> BUILD -> DEPLOY -> TEST_E2E)
+
+Ambiguities: 3 (2 HIGH, 1 MEDIUM, 0 LOW)
+  [HIGH] Fluent Analytics (Google Looker) — no skill mapping
+  [HIGH] US-203 — no tasks generated (Looker integration)
+  [MEDIUM] +/-1% error — unmeasurable by existing test tools
+
+Traceability:
+  US-201: 4 tasks (covered)
+  US-202: 4 tasks (covered)
+  US-203: 0 tasks (GAP — requires human action)
+
+Constraints Applied: backward_compatible, no_pii_in_logs
+
+Output:
+  accounts/HMDEV/analysis/scope-decomposition/fcx-sourcing-abtesting.tasks.json
+```
+
+## Markdown Output Format (--output-format markdown)
+
+When markdown output is requested, produce a table-based summary alongside the JSON:
+
+```markdown
+# Task List: fcx.sourcing.abtesting
+
+| ID | Type | Title | Skill | Depends On | Story | Priority |
+|----|------|-------|-------|-----------|-------|----------|
+| T-001 | SCAFFOLD | Scaffold module fcx.sourcing.abtesting | fluent-module-scaffold | -- | -- | 1 |
+| T-002 | RULE | Implement experiment variant definition rule | fluent-rule-scaffold | T-001 | US-201 | 2 |
+| T-003 | RULE | Implement traffic split allocation rule | fluent-rule-scaffold | T-001 | US-202 | 3 |
+| ... | ... | ... | ... | ... | ... | ... |
+
+## Ambiguities
+
+| Severity | Section | Item | Issue |
+|----------|---------|------|-------|
+| HIGH | Interfaces | Fluent Analytics (Google Looker) | No skill mapping |
+| HIGH | User stories | US-203 | No tasks generated |
+| MEDIUM | Acceptance criteria | +/-1% error | Unmeasurable |
+
+## Traceability
+
+| Story | Tasks | Coverage |
+|-------|-------|----------|
+| US-201 | T-002, T-006, T-007, T-014 | Covered |
+| US-202 | T-003, T-004, T-005, T-014 | Covered |
+| US-203 | (none) | GAP |
+```
+
+## Tips
+
+- **Run `--validate-only` first** to check the scope document structure before generating a full task list. This catches missing sections and structural issues early.
+- **Scope documents should be machine-parseable** — use consistent heading levels, bullet lists with identifiers, and Given/When/Then format for criteria. The ADD template enforces this.
+- **One module per scope document** — if the scope covers multiple modules, split it into separate documents and run decomposition on each.
+- **Review ambiguities before executing tasks** — HIGH severity ambiguities often indicate scope gaps that need human resolution. Running tasks against an ambiguous scope wastes agent cycles.
+- **The task list is a living document** — `/fluent-dev` updates task statuses in-place as work progresses. Re-running decomposition overwrites the file, so back up if in-progress work exists.
+- **Custom task types** — if a scope requires work outside the standard type table (e.g., database migration, external API setup), generate a DOC-type placeholder with `skill: null` and flag as ambiguity.
+- **Story-to-criteria linking** — if criteria do not explicitly reference story IDs, the skill links them by order of appearance. For precise linking, include `[US-NNN]` references in criteria text.
+- **Large scope documents** — for scopes with 20+ stories, the task list can exceed 50 tasks. Review the dependency DAG visualization to identify parallelizable task groups.