{
  "id": "page:library-composition-saas-analytics-dashboard",
  "_kind": "Page",
  "_file": "wiki/library/composition-saas-analytics-dashboard.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "Composition: SaaS Analytics Dashboard (JTBD + Impact Mapping + Spec-Kit + Kanban + XP) (Library)",
    "displayName": "Composition: SaaS Analytics Dashboard (JTBD + Impact Mapping + Spec-Kit + Kanban + XP) (Library)",
    "slug": "library/composition-saas-analytics-dashboard",
    "articlePath": "wiki/library/composition-saas-analytics-dashboard.md",
    "article": "\n# Composition: SaaS Analytics Dashboard (JTBD + Impact Mapping + Spec-Kit + Kanban + XP)\n\nImplements methodology backlog **Example 5** (B2B SaaS analytics-dashboard archetype, brownfield\nfeature added to an existing product). See `../backlog.md` (~line 2062): a customer-health\nanalytics dashboard delivered by composing five methodologies, each owning one seam.\n\n## Why this composition\n\n- **Jobs-to-be-Done** owns discovery: parallel interview synthesis (one segment per fan-out)\n  surfaces the real, solution-agnostic jobs the dashboard is hired to do; the imported\n  `forcesAnalysisTask` consolidates push/pull/anxiety/habit forces and `jobStoryGenerationTask`\n  emits situation/motivation/expected-outcome stories. The artifact that crosses its seam is the\n  **JTBD report** (jobs + job stories).\n- **Impact Mapping** owns the goal-to-deliverable ladder: from the `businessGoal` root, imported\n  `actorIdentificationTask -> impactAnalysisTask -> deliverableGenerationTask -> prioritizationTask`\n  build `goal -> actor -> impact -> deliverable` branches. The artifact that crosses its seam is\n  the **impact map** (prioritized per-actor branches).\n- **Spec-Kit** owns the buildable contract: a constitution encodes the non-functional budgets, and\n  then — **per impact branch, in parallel** — a dashboard view spec (layout, metrics, drill-downs,\n  measurable acceptance assertions) and its data contract are authored. The artifact that crosses\n  its seam is the **per-view spec + data contract + machine-checkable acceptance assertions**.\n- **Kanban** owns flow: a board (`Backlog -> Design -> Dev(WIP=3) -> Code Review -> QA -> Done`)\n  with a Dev WIP limit; each view spec becomes a card pulled under the limit. The artifact that\n  crosses its seam is the **flow-metered board** (cycle/lead time, throughput, bottlenecks).\n- **Extreme Programming** owns engineering excellence: imported `pairProgrammingTask` +\n  `tddPracticeTask` (tests first from the acceptance assertions, red-green-refactor, recording\n  `assertionId -> test`), `continuousIntegrationTask` on every increment, `refactoringTask` for\n  cleanup. The artifact that crosses its seam is the **assertion-derived test suite**.\n\nThe seam this composition exists to encode: **jobs -> impact ladder -> per-view specs -> flow-metered\nXP increments -> rendered-conformance release**, guarded by an adversarial executed-evidence gate at\nevery methodology boundary.\n\n> **Kanban re-expression:** `kanban/kanban.js` and `extreme-programming/xp-process.js` both register\n> a global task id `retrospective`, so a module importing both throws a `DuplicateTaskIdError` at\n> load. The XP task constants are imported directly; the three Kanban stages are re-expressed as own\n> `csd.wip-setup`, `csd.pull-cards`, `csd.flow-metrics` tasks (the same treatment the design gives\n> Spec-Kit, which exports only `process`). The module therefore loads with no id collision.\n\n## Seam map\n\n| Phase | Methodology | Artifact in | Artifact out | Combinator used |\n|-------|-------------|-------------|--------------|-----------------|\n| P0 kip recall | (memory) | kip store | prior seam insights | `kipRecall` |\n| P1 JTBD | Jobs-to-be-Done | dashboard brief + segments | JTBD report (jobs, forces, stories) | — (`ctx.parallel.all` over segments) |\n| G1 gate | (verification) | JTBD report | synthesis verdict | `adversarialGate` (`csd.jtbd-synthesis`) |\n| P2 Impact Mapping | Impact Mapping | business goal + jobs | impact map (goal->actor->impact->deliverable) | imported task constants |\n| G2 gate | (verification) | impact map | ladder-integrity verdict | `adversarialGate` (`csd.impact-map`) |\n| P3 Spec-Kit | Spec-Kit | branches + job stories + budget | constitution + per-view specs + data contracts | — (`ctx.parallel.all` per impact branch) |\n| G3 gate | (verification) | Spec-Kit artifacts | measurability + contract verdict | `adversarialGate` (`csd.spec-authoring`) |\n| P4 Kanban + XP | Kanban + XP | view specs | flow-metered TDD-built views | imported XP tasks + `ctx.parallel.all` (WIP-bounded) |\n| G4 release gate | (verification) | executed conformance report | rendered-conformance verdict | `adversarialGate` (`csd.spec-conformance`) |\n| P5 beta | (release) | conformance report + partners | beta rollout (guarded) | `routedBreakpoint` (`beta-customer-invite`) |\n| P6 GA | (release) | beta outcomes + conformance | GA release (guarded) | `routedBreakpoint` (`dashboard-ga-release`) |\n| P7 close | retro + memory | cycle record | retro actions + kip facts | `kipAssert` |\n\n## Per-impact-branch parallel elaboration\n\nSpec-Kit specification is not authored monolithically. After the constitution is fixed,\n`ctx.parallel.all` fans out over `impactMap.branches`: **for each impact branch concurrently**, the\nview spec (`csd.view-spec`) is authored and then its data contract (`csd.data-contract`) — so every\nprioritized actor/impact branch produces exactly one dashboard view + backing data contract in\nparallel with the others. Interview synthesis (P1) and WIP-bounded card implementation (P4) are the\nother two parallel sections; dependent stages (forces -> stories per job, view -> its data contract)\nare awaited in order, never speculatively co-scheduled.\n\n## Executed spec-conformance release gate\n\n`adversarialGate` with `gateId: 'csd.spec-conformance'` — the **dashboard-release gate** — runs over\nthe report written by `csd.spec-conformance-run`, which **renders/executes each dashboard view** and\ncaptures the rendered value / measurement / API response per acceptance assertion, then re-runs the\nXP/TDD suite. Three independent critics (`rendered-conformance-critic`, `constitution-budget-critic`,\n`tdd-evidence-critic`) are fanned out in parallel; none is the implementer or the conformance runner.\nIron law:\n\n- Do **not** trust the report — render/execute the dashboard yourself and compare rendered output to\n  each spec assertion.\n- Every in-scope `acceptanceAssertion` must map to an **EXECUTED** conformance check with rendered\n  proof; an assertion mapped only to a skipped/unexecuted check is a **FAIL**.\n- Measured dashboard load and query latency must meet the constitution budgets (numbers, not claims).\n\nA planning invariant is enforced in code before the gate: `assertConformanceComplete(specs,\nconformance)` throws if the conformance run left any in-scope assertion without an executed rendered\ncheck. A bounded fix loop (`maxFixAttempts`, built-in fixer) runs between rounds; exhaustion escalates\nvia the combinator-owned `csd.spec-conformance.gate-escalation` breakpoint. **This gate MUST pass\nbefore any beta invite is raised** — if it fails, the process returns `success: false` with\n`beta: null` and `ga: null`, and no guarded executor ever runs.\n\n## Policy-gated actions\n\n| Action | breakpointId | Expert | Phase | Executor guard |\n|--------|--------------|--------|-------|----------------|\n| Beta invite + scoped access to design partners | `beta-customer-invite` | `product-owner` | P5 | `csd.beta-rollout` runs ONLY inside `if (approved === true)` |\n| GA release to all tenants | `dashboard-ga-release` | `head-of-product` | P6 | `csd.ga-release` runs ONLY inside `if (approved === true)` |\n\nBoth are raised via `routedBreakpoint` with tags `['policy-gated', 'csd', <phase-tag>]`, strategy\n`single`, and **no** `autoApproveAfterN`. Provenance `{ approved, autoApproved, breakpointId, expert,\nresponse }` is always recorded (`autoApproved` reflects `response?.autoApproved === true`). GA is only\nraised once beta is approved+executed. Ready for `adapters/policy` YAML gating on the `policy-gated`\ntag.\n\n## Inputs\n\n```\n{\n  productName: string (required),\n  dashboardBrief: string (required),\n  businessGoal: string (required),\n  customerSegments?: array<string> (default derived: [`${productName} primary users`]),\n  designPartners?: array<{customerId, name, segment}> (default []),\n  performanceBudget?: object (default { dashboardLoadMs: 3000, queryMs: 1000, dataLatencyMin: 5 }),\n  maxFixAttempts?: number (default 2 — bounded fixer budget per adversarial gate),\n  maxInterviews?: number (default 5 — cap on parallel JTBD interview-synthesis fan-out),\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,  // true only when the spec-conformance gate passed AND beta approved+executed AND GA approved+released\n  jtbd: { reportPath, jobs: [{ jobId, jobStatement, forces:{push,pull,anxiety,habit}, jobStories }] },\n  impactMap: { mapPath, goal, branches: [{ branchId, actor, impact, deliverables:[{deliverableId,name,priority}] }] },\n  specs: { constitutionPath, viewSpecs: [{ branchId, viewId, viewSpecPath, dataContractPath, acceptanceAssertions }], checklist:{passed,items} },\n  implementation: { board:{columns,wipLimits}, storiesImplemented:[{storyId,viewId,exampleTestMap,ciRunId}], flowMetrics:{cycleTimeDays,leadTimeDays,throughputPerWeek,bottlenecks} },\n  conformance: { reportPath, passed, renderedEvidence:[{viewId,assertionId,status,renderedProof}], totals:{assertions,passed,failed,unrendered} },\n  beta: { approved, autoApproved, breakpointId, expert, response, invitedCustomers, accessGranted } | null,\n  ga: { approved, autoApproved, breakpointId, expert, response, released, releaseNotes } | null,\n  retro: { wentWell, couldImprove, actions },\n  kipFactsAsserted: number,\n  artifacts: array,\n  metadata: { processId, runId, breakpointsHit, seamGatesPassed }\n}\n```\n\nA failed seam gate (G1–G3) returns `success: false` with a `failedStage` marker and nothing\ndownstream invoked. A failed release gate (G4) returns `success: false` with `beta: null` and\n`ga: null`. A rejected beta or GA breakpoint returns a valid non-success provenance record with the\nguarded executor never called.\n\n## kip touchpoints\n\n- **Recall (P0)** — `kipRecall` under kind `methodology-composition`, topic keyed to `productName` +\n  `businessGoal`; also carries saas-product facts. Guarded by `kipEnabled`; an empty store is a fresh\n  brain, not an error.\n- **Assert (P7)** — `kipAssert` under kind `methodology-composition` writes five facts:\n  `seam-handoffs` (`{jobCount, branchCount, viewCount}`), `conformance-coverage` (assertions ->\n  executed checks, `{gateAttempts, escalated, failed}`), `flow-metrics` (`{bottlenecks}`),\n  `provenance-summary` (beta/ga approved+auto, `{released}`), and `observed-seam` (which seam leaked).\n\n## Composed modules\n\n- [`../jobs-to-be-done/`](../jobs-to-be-done/) — imports `forcesAnalysisTask`, `jobStoryGenerationTask`\n- [`../impact-mapping/`](../impact-mapping/) — imports `actorIdentificationTask`, `impactAnalysisTask`,\n  `deliverableGenerationTask`, `prioritizationTask`\n- [`../spec-kit/`](../spec-kit/) — exports only `process`; its stages are re-expressed as own\n  `csd.constitution`, `csd.view-spec`, `csd.data-contract`, `csd.spec-checklist` tasks\n- [`../extreme-programming/`](../extreme-programming/) — imports `pairProgrammingTask`,\n  `tddPracticeTask`, `continuousIntegrationTask`, `refactoringTask`\n- [`../kanban/`](../kanban/) — semantics mirrored as own `csd.wip-setup`, `csd.pull-cards`,\n  `csd.flow-metrics` (importing it alongside XP would collide on the `retrospective` task id)\n- [`../../specializations/product-management/product-lifecycle-e2e.js`](../../specializations/product-management/product-lifecycle-e2e.js)\n  — pattern reference: point tasks composed as callable stages; Spec-Kit artifacts feed implementation\n\nCombinators come from\n[`../../specializations/common-utilities/routed-gate-combinators.js`](../../specializations/common-utilities/routed-gate-combinators.js)\n(`routedBreakpoint`, `adversarialGate`, `kipRecall`, `kipAssert`).\n\n## Usage\n\n```js\nconst result = await orchestrate('methodologies/composition-saas-analytics-dashboard', {\n  productName: 'AcmeCRM',\n  dashboardBrief: 'A customer-health analytics dashboard for CSMs: usage trends, cohort retention, churn alerts, CSV export',\n  businessGoal: 'increase B2B retention by 10% through better health insights',\n  customerSegments: ['enterprise CSMs', 'mid-market CSMs'],\n  designPartners: [{ customerId: 'cust-1', name: 'Northwind', segment: 'enterprise CSMs' }],\n});\n```\n\n## Design rules honored\n\n- **No shell subtasks**: every task is `kind: 'agent'`; test/render/latency execution is performed BY\n  agents who paste executed output and measured numbers as evidence.\n- **No fallbacks**: invalid inputs throw before any orchestration; a failed gate or an unapproved\n  beta/GA returns an explicit `success: false` shape; a missing executed conformance check throws\n  (`assertConformanceComplete`) rather than being papered over.\n- **Guarded executors**: `csd.beta-rollout` and `csd.ga-release` run strictly inside\n  `if (provenance.approved === true)`; a non-approval yields a valid non-success record, never a\n  side-effecting fallback path.\n- **Executed-evidence gates**: an `adversarialGate` at every methodology seam; the release gate\n  renders the dashboard and re-runs the suite rather than trusting summaries.\n- **Honest scheduling**: `ctx.parallel.all` is used for interview synthesis, per-impact-branch\n  elaboration, and WIP-bounded card implementation; dependent stages are awaited in order.\n- **Combinators from `common-utilities` only.**\n```\n",
    "documents": [
      "specialization:composition-saas-analytics-dashboard"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-composition-saas-analytics-dashboard",
      "to": "specialization:composition-saas-analytics-dashboard",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-composition-saas-analytics-dashboard",
      "kind": "contains_page"
    }
  ]
}