{
  "id": "page:library-composition-smart-product-recommendations",
  "_kind": "Page",
  "_file": "wiki/library/composition-smart-product-recommendations.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "Composition: Smart Product Recommendations (DDD + Hypothesis-Driven Development + BDD + Kanban) (Library)",
    "displayName": "Composition: Smart Product Recommendations (DDD + Hypothesis-Driven Development + BDD + Kanban) (Library)",
    "slug": "library/composition-smart-product-recommendations",
    "articlePath": "wiki/library/composition-smart-product-recommendations.md",
    "article": "\n# Composition: Smart Product Recommendations (DDD + Hypothesis-Driven Development + BDD + Kanban)\n\nImplements methodology backlog **Example 1** (AI-powered product recommendations engine). See\n`../backlog.md` (~line 1744, Status **📝 Not Implemented**): \"Smart Product Recommendations\". This\ncomposition supersedes that *Not Implemented* status only — no code module is replaced.\n\n## Why this composition\n\n- **Domain-Driven Design** owns the map: it models the catalog/shopper domain into subdomains,\n  bounded contexts, a context map, and a ubiquitous language. The artifact that crosses its seam\n  is the **domain model** (bounded contexts + ubiquitous language), which the strategist turns\n  into candidate uplift levers.\n- **Hypothesis-Driven Development** owns measurable uplift: each candidate lever becomes a\n  falsifiable hypothesis with a primary metric, a quantified uplift target, guardrail metrics, and\n  a measurement plan. The artifact that crosses its seam is the **hypothesis + measurement plan**.\n- **BDD / Specification by Example** owns executable behavior: every hypothesis is specified as\n  Given/When/Then recommendation scenarios (cold-start, personalization relevance,\n  diversity/guardrails, **no-fallback ranking**), authored **in parallel per bounded context**,\n  each scenario id embedding its `contextId` and `hypothesisId`. The artifact that crosses its\n  seam is the **executable gherkin suite**.\n- **Kanban** owns delivery flow: scenarios become WIP-limited cards pulled through the board,\n  implemented so their mapped scenarios execute green, with flow metrics drawn from real card\n  history. The artifact that crosses its seam is the **implemented, tested build**.\n\nThe seam this composition exists to encode: **domain model -> hypotheses -> executable scenarios\n-> tested build -> validated experiment -> production rollout**, with an adversarial\nexecuted-evidence gate re-checking every seam.\n\n## Seam map\n\n| Phase | Methodology | Artifact in | Artifact out | Combinator used |\n|-------|-------------|-------------|--------------|-----------------|\n| P0 kip recall + interview | (memory) | topic | prior seam insights, clarified requirements | `kipRecall`, `routedBreakpoint` (`requirements-interview`, conditional) |\n| P1 domain modeling | DDD (imported) | catalog description + insights | domain model + hypothesis candidates | `adversarialGate` (`csr.seam.domain-to-hypothesis`) |\n| P2 hypothesis formulation | Hypothesis-Driven (imported) | candidates | hypotheses + measurement plans + behavior backlog | — |\n| P3 scenario authoring | BDD (csr authoring + imported execution) | behavior backlog per context | executable gherkin + card backlog (parallel per context) | `adversarialGate` (`csr.seam.hypothesis-to-scenarios`), `ctx.parallel.all` |\n| P4 implementation flow | Kanban (imported) + csr cards | cards + scenarios | tested build, flow metrics, scenario->test map | `adversarialGate` (`csr.seam.flow-to-experiment`), `ctx.parallel.all` |\n| P5 launch + validation | Hypothesis-Driven (imported analysis) + csr lanes | tested build | launch + lane metrics + analysis | `routedBreakpoint` (`experiment-launch-approval`), `adversarialGate` (`csr.experiment-validation`), `ctx.parallel.all` |\n| P6 rollout | (release; policy-gated) | validation evidence | rollout decision (guarded) | `routedBreakpoint` (`recommendations-production-rollout`) |\n| P7 close | Kanban retro (imported) + memory | cycle record | retro, seam report, kip facts | `kipAssert` |\n\n## Inputs\n\n```\n{\n  storefrontName: string (required),\n  catalogDescription: string (required),\n  recommendationGoals: string (required),\n  boundedContextHints?: string[],\n  experimentLanes?: [{ laneId, variant, description }]  (if absent, derived from validated hypotheses),\n  upliftTargets?: object   (explicit per-metric uplift targets; else formulated in P2),\n  requirementsClear?: boolean (default false — when false, P0 runs the interview + breakpoint),\n  maxParallelContexts?: number (default 3 — parallel authoring/build chunk size),\n  maxFixAttempts?: number (default 2 — adversarial-gate fix budget),\n  kipEnabled?: boolean (default true),\n  kipDir?: string (default '.a5c/kip'),\n  kipModel?: string (default 'sonnet')\n}\n```\n\n## Outputs\n\n```\n{\n  success: boolean,\n  domainModel: { subdomains, boundedContexts, contextMapPath, ubiquitousLanguage },\n  hypotheses: [{ hypothesisId, statement, contextId, primaryMetric, upliftTarget, guardrailMetrics, measurementPlanPath }],\n  scenarios: [{ contextId, gherkinPath, stepDefPath, scenarioIds }],\n  flow: { boardPath, wipLimits, flowMetrics, cardsImplemented },\n  seamGates: { domainToHypothesis, hypothesisToScenarios, flowToExperiment } each { passed, attempts, escalated, issues, evidence },\n  experiment: { launch, lanes: [{ laneId, computedMetrics, rawDataPath }], analysis, validationGate },\n  rollout: { approved, breakpointId, expert, autoApproved, rolledOut, response },\n  retro,\n  kipFactsAsserted: number,\n  artifacts: array,\n  metadata: { processId, runId, breakpointsHit }\n}\n```\n\n`success` is `true` only if all three seam gates passed, experiment validation passed, the launch\nwas approved, and (if rollout was approved) the model was rolled out. A failed seam gate, a\nrejected launch, or a failed validation returns an explicit `success: false` shape with nothing\ndownstream ever invoked — never a silent fallback that resumes the pipeline.\n\n## Policy-gated actions\n\n| Action | breakpointId | Expert | Phase | Executor guard |\n|--------|--------------|--------|-------|----------------|\n| Launch live recommendation experiment | `experiment-launch-approval` | `growth-product-lead` | P5 | `csr.launch-experiment` + `csr.experiment-lane` run ONLY if `approved === true` |\n| Roll recommendation model to production | `recommendations-production-rollout` | `product-owner` | P6 | `csr.production-rollout` runs ONLY if `approved === true` |\n\nBoth are raised via `routedBreakpoint` with `breakpointId = actionId`, tags\n`['policy-gated', 'csr', <phase-tag>]`, strategy `single`, and **no** `autoApproveAfterN` — the\nprocess never auto-approves a policy gate. Provenance\n`{ approved, autoApproved, breakpointId, expert, response }` is always recorded (`autoApproved`\nreflects `response?.autoApproved === true` set by an external rule). Ready for `adapters/policy`\nYAML gating on the `policy-gated` tag. A conditional `requirements-interview` breakpoint\n(`growth-product-lead`) is raised in P0 only when `requirementsClear !== true`.\n\n## Adversarial seam gates (executed evidence)\n\nEvery methodology handoff carries an `adversarialGate` reducing to `{ passed, issues, evidence }`\nwith mandatory evidence; three independent IRON-LAW critics fan out in parallel (none is the\ndrafting agent, none sees another's verdict), a bounded fixer loop runs `maxFixAttempts` rounds\nbetween critic rounds, and exhaustion escalates to `owner` via the combinator-owned\n`<gateId>.gate-escalation` breakpoint.\n\n| Gate | Seam | Executed evidence | Iron law (abridged) |\n|------|------|-------------------|---------------------|\n| `csr.seam.domain-to-hypothesis` | DDD -> Hypothesis | design seam (re-derive model artifacts) | re-derive boundaries + language from artifacts; a metric not measurable online is a FAIL |\n| `csr.seam.hypothesis-to-scenarios` | Hypothesis -> BDD | **yes** — execute authored gherkin (expect RED/pending) | every hypothesis traces to >= 1 scenario and every scenario to a hypothesis; a non-executable scenario is a FAIL |\n| `csr.seam.flow-to-experiment` | BDD/Kanban -> Experiment | **yes** — re-run full BDD suite green | every in-scope scenario maps to an EXECUTED passing test; any silent fallback ranking branch is a FAIL |\n| `csr.experiment-validation` | Experiment -> Rollout | **yes** — recompute metrics from raw data + re-run BDD | an uplift not reproducible from `rawDataPath` is a FAIL; a breached guardrail is a FAIL regardless of primary uplift |\n\nThe executed-evidence gates use the imported `executeTestsTask` to produce executed output threaded\ninto the critics' context.\n\n## Composed modules\n\n- [`../domain-driven-design/`](../domain-driven-design/) — `identifySubdomainsTask`,\n  `defineBoundedContextsTask`, `createContextMapTask`, `buildUbiquitousLanguageTask`\n- [`../hypothesis-driven-development/`](../hypothesis-driven-development/) —\n  `formulateHypothesisTask`, `createMeasurementPlanTask`, `analyzeResultsTask`\n- [`../bdd-specification-by-example/`](../bdd-specification-by-example/) — `executeTestsTask`\n- [`../kanban/`](../kanban/) — `boardVisualizationTask`, `wipLimitManagementTask`,\n  `pullSystemTask`, `flowMetricsTask`, `retrospectiveTask`\n\nCombinators come from\n[`../../specializations/common-utilities/routed-gate-combinators.js`](../../specializations/common-utilities/routed-gate-combinators.js)\n(`routedBreakpoint`, `adversarialGate`, `kipRecall`, `kipAssert`). Phase interiors compose **by\nimport** where ingredient exports exist; `csr.*` tasks are defined only for cross-methodology\nseams, recommendation-domain authoring/execution, and the two guarded policy executors.\n\n## Usage\n\n```js\nconst result = await orchestrate('methodologies/composition-smart-product-recommendations', {\n  storefrontName: 'NovaMart',\n  catalogDescription: 'Mid-size fashion storefront: 40k SKUs, returning + cold-start shoppers',\n  recommendationGoals: 'Lift average order value and PDP click-through with cross-sell + personalization',\n  requirementsClear: false,\n});\n```\n\n## Design rules honored\n\n- **No shell subtasks**: every `csr.*` task is `kind: 'agent'`; scenario and metric execution is\n  performed BY agents who paste executed output as evidence.\n- **No fallbacks**: invalid inputs throw; a failed seam gate, a rejected experiment launch, and a\n  failed validation each return an explicit `success: false` shape; the recommendation ranking\n  itself must specify missing-signal handling as an explicit behavior (enforced by\n  `no-fallback-ranking-critic`) — never a silent alternate path. `pickWinningLane` returns an\n  honest `null` when no lane qualifies rather than defaulting to an arbitrary lane.\n- **Sparse breakpoints**: exactly the two policy gates plus a conditional\n  `requirements-interview` and the combinator-owned gate escalations.\n- **Bounded loops**: each adversarial gate fixer runs at most `maxFixAttempts`.\n- **Honest scheduling**: `ctx.parallel.all` is used at exactly three sites in process code (P3\n  per-context authoring, P4 `parallelSafe`-card fan-out, P5 experiment lanes), each bounded by\n  `maxParallelContexts` via `chunk`; dependent cards are awaited in `dependsOn` order via\n  `orderByDependencies`, never speculatively co-scheduled.\n- **Provenance recorded** for both policy gates; executors are strictly guarded on\n  `approved === true` — ready for `adapters/policy` YAML gating on the `policy-gated` tag.\n",
    "documents": [
      "specialization:composition-smart-product-recommendations"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-composition-smart-product-recommendations",
      "to": "specialization:composition-smart-product-recommendations",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-composition-smart-product-recommendations",
      "kind": "contains_page"
    }
  ]
}