From 89d8bd565a22e350c257a716ea512f9701f059c9 Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:45:30 +0300 Subject: [PATCH 01/10] =?UTF-8?q?docs(wedge-future):=20variscout-process/i?= =?UTF-8?q?ndex.md=20=E2=80=94=20overview=20+=20reading=20order?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Preserved institutional capture for VariScout Process (named-future). Multi-file synthesis of pre-wedge design heritage that doesn't fit V1 specialist scope. Activation gated on V1 reaching ~500 customers. Adds 'named-future' to STATUS enum in docs frontmatter schema for honest representation of preserved-not-shipping doc state. Index covers: two-product roadmap, activation threshold, V1-vs-Process boundary summary, file map, reading order, what-this-is-not. --- docs/01-vision/variscout-process/index.md | 112 ++++++++++++++++++++++ scripts/docs-frontmatter-schema.mjs | 1 + 2 files changed, 113 insertions(+) create mode 100644 docs/01-vision/variscout-process/index.md diff --git a/docs/01-vision/variscout-process/index.md b/docs/01-vision/variscout-process/index.md new file mode 100644 index 000000000..fe132b475 --- /dev/null +++ b/docs/01-vision/variscout-process/index.md @@ -0,0 +1,112 @@ +--- +title: 'VariScout Process — Named-Future Capture' +audience: [product, designer, engineer, business] +category: strategy +status: named-future +last-reviewed: 2026-05-17 +related: + - docs/superpowers/specs/2026-05-16-wedge-architecture-design.md + - docs/decision-log.md + - docs/superpowers/specs/2026-05-14-variscout-coherence-design.md + - docs/superpowers/specs/2026-05-03-variscout-vision-design.md + - docs/superpowers/specs/2026-04-29-multi-level-scout-design.md + - docs/superpowers/specs/2026-04-29-investigation-scope-and-drill-semantics-design.md + - docs/superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md +--- + +# VariScout Process — named-future capture + +> **Status: named-future.** This is preserved institutional knowledge, not a product commitment. VariScout Process is the second product on the two-product roadmap — gated on V1 (the wedge specialist tool) reaching ~500 customers. Nothing in this directory is in active development; nothing here ships under the V1 SKU; nothing here changes the V1 codebase. Read this when designing for V1 and a question surfaces that sounds like a process-owner / team / enterprise need — the answer is almost certainly here, and the answer is almost certainly "later, in Process." + +## §1 Why this directory exists + +The 2026-05-16 wedge pivot was a deliberate narrowing. The pre-wedge design corpus (~10 specs, ~3000 lines, March–May 2026) had converged on a four-persona, multi-Hub, auto-pipeline, monitoring-shaped product. Validating it against the actual ICP — improvement specialists running structured investigations with their teams — revealed that the breadth was the problem, not the solution. The wedge collapsed the surface area: one persona (Specialist), one container (Project wrapping an internal Hub), one ingestion path (manual paste + file upload), one SKU (€120/mo Azure tenant-wide), one positioning sentence ("structured investigation for process improvement"). + +But the design work behind the breadth was not wrong. It was early. The wedge spec §7 named eight specific capabilities as deferred — not "coming soon inside V1" but "a separate product on the roadmap when V1 validates." That product is **VariScout Process**. + +The deferrals scattered across ~10 source specs. This directory consolidates them. The goal is one canonical capture per concept, so that a year from now — when V1 has 500 customers and the team starts asking "what do we build next?" — the answer doesn't have to be re-discovered from spec archaeology. The concepts are here, named, with the boundary clearly drawn. + +## §2 The two-product roadmap + +| | **VariScout V1** (today) | **VariScout Process** (future) | +| ----------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| Audience | Improvement specialists running projects with their team | Enterprises with ongoing process ownership | +| Foundational unit | Project (self-contained, invite-scoped) | Process Hub (multi-project orchestration; first-class noun) | +| Collaboration | Project Lead invites org users _per project_ | Tenant-wide with persona-aware routing | +| Data ingestion | Manual paste + file upload | Auto pipelines feeding Hub-level storage | +| Persona model | One — Specialist (with member-roles within projects) | Four — Process Owner / Process Engineer / Specialist / Leader | +| Pricing | €120/month, single SKU, Azure-tenant-wide | TBD — separate product, separate SKU | +| Distribution | Azure Marketplace Managed Application + project ACLs | TBD | +| Knowledge memory | Per-project Findings + Hypotheses + Measurement Plans | Knowledge Catalyst at Hub scale — cross-project pattern memory federated across an org's full process portfolio | + +V1 is not a stripped-down VariScout Process. V1 is a self-contained tool whose product anatomy fits the specialist workflow. Process is not a tier upgrade of V1 — it is a different product for a different buyer and a different operating shape. The shared substrate (browser-only processing, customer-owned data, deterministic stats engine, canvas as map, three-level methodology, response paths as routing pattern) is preserved across both. Everything else is product-specific. + +## §3 The activation threshold — 500 customers, honestly framed + +VariScout Process activates when V1 reaches roughly **500 paying customers**. The number is a proxy, not a calendar date. It encodes three preconditions: + +1. **Product-market fit at the V1 ICP.** 500 specialists paying €120/mo means a working acquisition + retention loop for the specialist persona. Without that, scaling into process-owner buyer-territory is premature. +2. **Engineering capacity for a second product.** Building Process while V1 still has known gaps (V2 measurement system additions, signoff workflows, multi-project coordination at specialist scope) starves both. 500 customers funds a second product team. +3. **Customer-pull evidence that process ownership is the next layer.** If specialist customers consistently ask for process-owner monitoring as their next purchase, the deferred design becomes a validated commitment. If they ask for something else, this capture stays preserved and the roadmap turns. + +This is honest framing: VariScout Process is gated on V1 working. If V1 doesn't validate the wedge, the deferred design doesn't activate. Nothing in this directory entitles itself to a build slot. + +## §4 V1-vs-Process boundary — one-paragraph summary + +Several features are **shipped in V1 code today** but serve specialist use at V1's scope. The same features at process-owner / multi-hub / enterprise scope are deferred to Process: Hub Capability (V1: per-project capability snapshot; Process: persistent process-owner monitoring across snapshots), Layered Process View (V1: canvas substrate for one project's process; Process: Hub-scale orchestration across multiple projects sharing one canonical map), multi-level SCOUT (V1: L1/L2/L3 within one project's data; Process: portfolio-spanning multi-Hub navigation), Investigation Wall + Measurement Plans (V1: per-project Hypothesis evidence + planning; Process: cross-project pattern memory). The detailed scope-line for each feature lives in [scope-line.md](scope-line.md) — read that doc when "is this V1 or Process?" is the actual question. + +## §5 What's inside + +| File | One sentence | +| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **[scope-line.md](scope-line.md)** | The V1-vs-Process feature boundary, drawn for each shipped capability that lives in V1 today. **Start here when triaging a feature request.** | +| **[four-personas.md](four-personas.md)** | Process Owner / Process Engineer / Specialist / Leader — the four-persona model designed in Coherence Session A. Specialist is the V1 persona; the other three activate in Process. | +| **[hub-portfolios.md](hub-portfolios.md)** | Hub-of-hubs orchestration, multi-hub portfolios, the four drill semantics (Hub→Step / Step→Channels / Step→Sub-flow / Org Hub-of-Hubs). | +| **[measurement-system.md](measurement-system.md)** | The Process Measurement System (PMS) — stable measure definitions + Evidence Sources + Snapshots + cadence rules combining into Current Process State. The named-future surface that triggers response paths at cadence. | +| **[methodology.md](methodology.md)** | The three-level methodology (Outcome / Process Flow / Local Mechanism), Watson-validated. Operates per-project in V1; spans the portfolio in Process. | +| **[pipelines.md](pipelines.md)** | Auto-ingestion, multi-source profile join, sensor / SCADA / ERP feeds, scheduled refresh. The "automated data" half of process ownership. | +| **[monitoring.md](monitoring.md)** | Drift detection, alerts, process-owner monitoring views, capability snapshots over time. The "ongoing watching" half of process ownership. | + +## §6 Reading order + +For someone landing here without context: + +1. **Start with §4 of this file + [scope-line.md](scope-line.md)** to understand which V1 features are also Process features (just at smaller scope) and which are Process-only. +2. **Then [four-personas.md](four-personas.md)** because the persona model is the largest single conceptual shift V1 → Process. Most of what comes next is anchored on which persona consumes it. +3. **Then [methodology.md](methodology.md)** — the methodology is shared across both products, but the spec gets clearer at Process scope because the three levels each have a different primary persona. +4. **Then [measurement-system.md](measurement-system.md) + [monitoring.md](monitoring.md)** as a pair — PMS produces Current Process State; monitoring is the cadence-review surface that consumes it. +5. **Then [hub-portfolios.md](hub-portfolios.md) + [pipelines.md](pipelines.md)** as a pair — the structural substrate (multi-hub) and the data substrate (auto-feeds) that Process operates on. + +For someone working in V1 today and wanting to understand a single Process concept: jump to the file. Files cross-link to each other and to source specs. They do not chain. + +## §7 What this directory is not + +- **Not a product commitment.** Nothing here ships under the V1 SKU. Nothing here changes the V1 codebase. If V1 fails to validate, Process does not activate; this directory remains a preserved record of design work, not a guarantee of delivery. +- **Not agent-canonical.** Agents reading `docs/llms.txt` or the Phase A anchors (positioning, business-bible, roadmap) are explicitly not steered here. The breadcrumb is via [docs/decision-log.md](../../decision-log.md) only — future humans grepping for "VariScout Process" find this. Agents working on V1 should not be coloring V1 designs with Process concepts. +- **Not a spec.** This is institutional capture, not a buildable design. When VariScout Process activates, each file here becomes a starting point for design refinement, not the final spec. The decisions encoded here are concept-level, not implementation-level. +- **Not the wedge.** The word "wedge" is the internal engineering vocabulary for the 2026-05-16 pivot. Customer-facing language is "VariScout V1" (or simply "VariScout") for the current product and "VariScout Process" for the future one. This directory uses the customer-facing names throughout. + +## §8 How this capture relates to source specs + +The source design corpus is not deleted. Specs in `docs/superpowers/specs/` carry an Amendment block at the top (added 2026-05-16) marking which sections retire for V1 and which survive. The Process-shaped content in those specs is the original source; this directory is the consolidation. + +When you want depth, click through to the source spec. When you want one canonical answer per concept, stay here. Each file in this directory cross-links to the source specs whose content it synthesizes. + +The canonical statement of the V1-vs-Process split — the strategic decision that this directory preserves the deferred half of — lives in [wedge architecture spec §7](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) and is recorded as item #8 of the 2026-05-16 entry in [docs/decision-log.md](../../decision-log.md). + +## §9 If V1 succeeds — what activates first + +Speculation, not commitment. If V1 reaches the 500-customer threshold and customer-pull confirms process-owner buyer interest, the natural activation sequence is: + +1. **Process Owner persona + Process tab persona-aware default landing** ([four-personas.md](four-personas.md) §3). The smallest activation that introduces the new buyer without restructuring the data model. +2. **Hub-as-first-class-noun in the UI** ([hub-portfolios.md](hub-portfolios.md) §2). Today Hub is the internal data container; surfacing it as a navigable concept is the structural pivot that everything else hangs on. +3. **Process Measurement System surface** ([measurement-system.md](measurement-system.md) §2–3). The cadence-review surface that gives Process Owners their primary daily / weekly artifact. +4. **Auto-pipelines for one anchor data shape** ([pipelines.md](pipelines.md) §2–3). Not generalized ingestion — one well-documented profile (agent review log, or a comparable anchor) that proves the recurring-snapshot pattern. +5. **Drift detection + monitoring views** ([monitoring.md](monitoring.md) §2–3). The "ongoing watching" layer that earns the Process Owner's daily attention. +6. **Hub-of-hubs portfolio view** ([hub-portfolios.md](hub-portfolios.md) §3). The Leader persona's primary surface; activates when Process has enough installed base to make cross-process navigation valuable. + +This sequence is not in any spec. It is a reading of which capabilities depend on which, given the architecture in [methodology.md](methodology.md) and [hub-portfolios.md](hub-portfolios.md). When activation actually happens, the team will re-plan from first principles against the customer-pull signal of the day. + +--- + +> Process is not coming soon. Process is preserved. The wedge is the bet; this directory is the long game. diff --git a/scripts/docs-frontmatter-schema.mjs b/scripts/docs-frontmatter-schema.mjs index 1350dd6a9..0022c6393 100644 --- a/scripts/docs-frontmatter-schema.mjs +++ b/scripts/docs-frontmatter-schema.mjs @@ -19,6 +19,7 @@ export const STATUS = [ 'raw', 'review', 'living', + 'named-future', ]; export const CATEGORY = [ From 566cd56788b73fb7cce0c524b3c04dc9cc432738 Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:45:59 +0300 Subject: [PATCH 02/10] =?UTF-8?q?docs(wedge-future):=20variscout-process/s?= =?UTF-8?q?cope-line.md=20=E2=80=94=20V1-vs-Process=20feature=20boundary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per-capability line between V1 specialist scope and Process scope. Tables for shipped V1 capabilities with Process headroom, V1-only features that Process inherits or transforms, and Process-only capabilities with no V1 shape. The doc to consult when triaging whether a feature request is V1 or Process. --- .../01-vision/variscout-process/scope-line.md | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 docs/01-vision/variscout-process/scope-line.md diff --git a/docs/01-vision/variscout-process/scope-line.md b/docs/01-vision/variscout-process/scope-line.md new file mode 100644 index 000000000..18e8b03de --- /dev/null +++ b/docs/01-vision/variscout-process/scope-line.md @@ -0,0 +1,123 @@ +--- +title: 'V1-vs-Process scope line — feature boundary' +audience: [product, designer, engineer] +category: strategy +status: named-future +last-reviewed: 2026-05-17 +parent: docs/01-vision/variscout-process/index.md +related: + - docs/superpowers/specs/2026-05-16-wedge-architecture-design.md + - docs/superpowers/specs/2026-04-28-production-line-glance-design.md + - docs/superpowers/specs/2026-04-29-multi-level-scout-design.md + - docs/superpowers/specs/2026-04-29-investigation-scope-and-drill-semantics-design.md +--- + +# V1-vs-Process scope line — feature boundary + +> **Status: named-future capture.** This is the cleanest doc in the directory. It answers one question: **"is this V1 or Process?"** for every shipped capability that could plausibly belong to either product. + +## §1 How to read this doc + +V1 (the wedge specialist tool) ships today. VariScout Process is named-future. Most pre-wedge design work created **shared substrate** — code that ships in V1 but was originally designed for process-owner / multi-hub / enterprise scope. Drawing the line for each capability prevents two failure modes: + +1. **Scope creep into V1.** A specialist asks "can I monitor capability across multiple processes?" — that sounds reasonable, but answering "yes" smuggles Process-scope behavior into V1 and breaks the wedge. +2. **Throwing away shipped value.** When Process activates, the team will benefit from extending capabilities already coded rather than rebuilding from scratch. Knowing which V1 capabilities have Process-shaped headroom guides Phase 1 of Process activation. + +The table format below is the contract. For each capability: **V1 shape** (what ships today, at specialist scope) vs **Process shape** (what activates when Process activates). + +## §2 Shipped V1 capabilities with Process headroom + +These are the capabilities that exist in V1 code today and have explicit Process-scope extensions designed but deferred. + +### §2.1 Hub Capability (`ProductionLineGlanceDashboard` + `ProcessHubCapabilityTab`) + +**V1 shape.** Per-project capability snapshot rendered inside the Process tab's L2 view. The engine — per-`(node × context-tuple)` Cpk computation shipped via PRs #103/#105/#106/#107 — runs against the single project's data. The per-step Cpk boxplot honors ADR-073 (no statistical rollup across heterogeneous units) by visualizing distributions, never collapsing them. The four shipped slot variants (capability, performance, defect, yamazumi) all operate within one project's scope. + +**Process shape.** Same engine, **persistent across snapshots**, owned by the Process Owner persona, rendered on the Process Hub's primary surface (not buried inside a per-project tab). Multiple projects on the same Hub contribute investigations; each investigation's `nodeMappings` adds to the Hub's per-step distribution. The Hub Capability tab in Process is the cadence-review surface that triggers response paths — see [measurement-system.md §3](measurement-system.md). The engine doesn't change; the scope changes from "this project's data" to "this Hub's history across all contributing investigations." + +**Where the line falls.** Aggregation engine + boxplot primitive + capability badge UI: shared across V1 and Process. **Cadence prompts firing off snapshot history, Process Owner default landing on this surface, Hub-of-hubs side-by-side card composition: Process only.** V1 specialists don't see cadence prompts on the capability surface. + +### §2.2 Layered Process View / Canvas substrate + +**V1 shape.** Canvas IS the Process tab's architectural substrate. 8f viewport architecture (PRs #160–#168) wires `useCanvasViewportStore` to `ProjectId` when project-scoped. L1/L2/L3 navigation via pan/zoom within one project's process. Cards-per-step rendering with inline mini-charts and capability badges. State + Edit mode toggle (the latter being where the Frame step lives). Single Specialist persona uses both modes. + +**Process shape.** Same canvas primitive, **keyed by `ProcessHubId` for free-roaming Hub navigation**. The Hub is the persistent map across multiple projects. Process Owner enters the canvas in State mode by default — read-only, monitoring shape. Process Engineer enters in Edit mode — authoring the canonical map that multiple projects then share. Specialists working on a Process-hosted Hub see the canvas just like in V1, but their changes operate _on top of_ a Hub map that persists beyond any one project. + +**Where the line falls.** Canvas component + pan/zoom + cards-per-step + 8f viewport architecture: shared. **Hub as a first-class user-visible noun, multi-project navigation via the canvas, persona-aware default modes (Process Owner → State, Process Engineer → Edit), persistent canonical map separate from any one project: Process only.** In V1 the Hub is internal data architecture invisible to the user; in Process it surfaces as a navigable concept. + +### §2.3 Multi-level SCOUT (L1 / L2 / L3 architecture) + +**V1 shape.** Each project has L1 (outcome distribution + Cpk vs spec), L2 (process flow with step cards), and L3 (focal step / Local Mechanism detail) — navigated via canvas pan/zoom. The `AnalysisModeStrategy.dataRouter` pattern routes per-`(mode × scope × phase × window)` to existing chart slots without inventing new ones. `detectScope` reads `nodeMappings` cardinality to distinguish B0 (legacy) / B1 (multi-step) / B2 (single-step). The four-slot dashboard becomes polymorphic across levels. + +**Process shape.** Same three-level architecture, **portfolio-spanning when navigating across multiple Hubs**. Drill A (Hub → Step) operates on the Hub's aggregated investigations rather than one project's data. Drill B (Step → Channels) and Drill C (Step → Sub-flow) unchanged in shape; they apply at Hub scope. The Org Hub-of-Hubs view ([hub-portfolios.md §3](hub-portfolios.md)) becomes the new top-level entry surface, side-by-side rendering child Hub miniatures. Timeline window primitive supports rolling / open-ended / cumulative modes for cadence-aware investigation. + +**Where the line falls.** L1/L2/L3 levels + dataRouter pattern + timeline window primitive + drill A/B/C engine: shared. **Org Hub-of-Hubs view + portfolio-spanning navigation + cross-Hub context filter chip strip + cadence-anchored timeline window defaults: Process only.** V1 timeline windows operate within one project's data; Process timeline windows traverse Hub history. + +### §2.4 Investigation Wall + Measurement Plans + +**V1 shape.** The Wall (`WallCanvas` + lifecycle hooks) hosts Hypothesis-driven investigation per-project. PR-WV1-3b shipped Measurement Plans as a sub-entity per Hypothesis — Plan rows describing factor / method / sample size / owner / status. The Plan → Collection → Finding cycle integrates measurement planning, current-data analysis, and gemba / expert collection into one spatial surface. ADR-080's Sustainment auto-fire pattern preserved. + +**Process shape.** Same Wall primitive + same Measurement Plan entity, **with cross-project pattern memory**. Hypotheses from prior projects on the same Hub surface as "previously investigated" hints when a new project touches the same step / factor. Knowledge Catalyst (the named-future pattern memory feature) federates Findings across projects. Cadence-anchored Measurement Plans — Plans that fire at recurring intervals as part of the Hub's PMS — extend the V1 Plan entity with a `cadence?` field. MSA / Gage R&R workflow that V1 explicitly defers belongs here; same for the statistical sample-size calculator. + +**Where the line falls.** Wall canvas + Hypothesis card structure + Measurement Plan entity + Plan→Collection→Finding cycle: shared. **Knowledge Catalyst pattern memory, cadence-anchored Plans, MSA / Gage R&R workflow, statistical sample-size calculator: Process only.** V1 Measurement Plans are project-scoped one-shot artifacts. + +### §2.5 Three-level methodology (Outcome / Process Flow / Local Mechanism) + +**V1 shape.** The methodology is the substrate — [`docs/01-vision/methodology.md`](../methodology.md) lines 76-100. It operates per-project: the specialist works at all three levels within one project's scope, with one persona (themselves) playing all three methodological roles. No persona-routing of levels in V1. + +**Process shape.** Same three levels, but each level has a **primary persona** ([four-personas.md §2](four-personas.md)) — Process Owner reads at L1 outcome scope, Specialist works at L3 mechanism scope, Process Engineer maintains L2 flow structure, Leader reads L1 across the portfolio. The level × persona mapping is the conceptual core of the Process product. Methodology rules (ADR-073, contribution-not-causation, observed-vs-expected, sample-size honesty, target-relative Cpk grading, geometric interaction language) unchanged across both products. + +**Where the line falls.** Three-level methodology + ADR-073 + methodology rules: shared. **Persona-aware level routing, default landing per persona, persona-aware copy density, persona-adaptive Home variants: Process only.** + +## §3 V1-only capabilities (Process inherits or transforms) + +These capabilities are V1's wedge anatomy. They don't survive into Process unchanged. + +### §3.1 Project as foundational unit + +**V1 shape.** Project (Charter / Approach / Sustainment, with Improve as a top-level verb tab) is the user-facing container. Internal Hub backs each project's data. Project membership ACLs (Lead / Member / Sponsor) scope access. Promotion path from quick analysis → Project via "+ New Project" CTA. + +**Process inherits.** Projects survive in Process, but they wrap a **persistent Hub** rather than the Hub being internal-to-project. Multiple projects share one Hub. Project lifecycle (Charter ceremony, membership invites, formal artifacts) unchanged. The promotion path "quick analysis → Project" still works for analysts who want formal scoping inside Process tenancy. Project membership ACLs operate alongside (not in place of) persona-aware routing. + +### §3.2 Project membership ACLs (Lead / Member / Sponsor) + +**V1 shape.** Per-project membership ACLs. Project Lead invites org users from the buyer's Azure AD tenant. Lead / Member / Sponsor roles. Sponsor sees Report-only access. Cross-Azure-AD-tenant invites explicitly out of scope. + +**Process inherits.** Project-scoped ACLs still operate. They layer on top of persona-aware tenant-wide routing. A Process Owner persona (tenant-wide read on their assigned Hubs) may or may not be a Lead / Member on a specific project running inside their Hub. The ACL model expands to support cross-Hub Sponsorship and Hub-level membership (the Process Owner of Hub X is implicitly Sponsor on all projects in Hub X). The Azure AD-tenant boundary tightens further or loosens; that's a Process-era distribution decision. + +### §3.3 Single SKU pricing (€120/mo Azure-tenant-wide) + +**V1 shape.** One price, one SKU, Azure Marketplace Managed Application. Honors the per-deployment hypothesis (ADR-033 H6). + +**Process transforms.** Process is a separate product on a separate SKU. Pricing TBD. The V1 €120 SKU is preserved (specialists still buy V1; specialists working inside a Process-tenanted org buy through Process). No tier-gating returns to V1 surfaces — the tier philosophy as a public-facing concept retires at the V1 cutover and does not re-activate in Process. Access-gating in Process happens via project membership ACLs + persona-aware routing, not tier checks. + +### §3.4 Six / seven-tab navigation + +**V1 shape.** `[Home] [Project] [Process] [Analyze] [Investigation] [Improve] [Report]` — 7 tabs in workflow order, with Improve restored as a top-level verb tab (per the 2026-05-16 amendment). Active-IP cascade routes verb tabs to project-scoped defaults. + +**Process inherits + adapts.** The nav primitives survive. **Process Owner persona's default landing is the Process tab in State mode** — not Home. Tenant-wide navigation reads Hub-first. Persona-adaptive Home variants ([four-personas.md §2.4](four-personas.md)) replace the V1 single-persona Home. Verb tabs (Analyze / Investigation / Improve) cascade off the active project as in V1; but the project may sit inside a Hub the user navigated to before they activated a project. + +## §4 Process-only capabilities (no V1 shape) + +These do not exist in V1 code and have no V1 surface. They activate only in Process. + +| Capability | Source spec | One sentence | +| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| **4-persona model** (Process Owner / Process Engineer / Specialist / Leader) | [Coherence §3](../../superpowers/specs/2026-05-14-variscout-coherence-design.md), [four-personas.md](four-personas.md) | Persona-aware tenant routing replaces the V1 single-Specialist model. | +| **Process Measurement System (PMS)** | [Evidence Sources spec](../../superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md), [Consolidated method §4](../../superpowers/specs/2026-04-29-consolidated-method-and-surface-overview-design.md), [measurement-system.md](measurement-system.md) | Stable measure definitions + Evidence Sources + Snapshots + cadence rules combining into Current Process State. | +| **Auto-ingestion pipelines** (sensor / SCADA / ERP / hourly feeds) | [Evidence Sources spec](../../superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md), [pipelines.md](pipelines.md) | Automated recurring evidence feeding Hub-level storage. V1 is paste / file only. | +| **Multi-source profile join** at Hub scale | [Framing Layer spec](../../superpowers/specs/2026-05-03-variscout-vision-design.md), [pipelines.md](pipelines.md) | Multiple sources contributing to one canonical map via Data Profiles. V1's MatchSummary primitives operate per-project. | +| **Process Owner monitoring dashboard** | [Vision spec §5](../../superpowers/specs/2026-05-03-variscout-vision-design.md), [monitoring.md](monitoring.md) | State-mode cadence-review surface separate from the per-project Process tab — Hub-overview shape, drift signals, alert routing. | +| **Hub-of-hubs portfolio view** | [Investigation scope spec §6](../../superpowers/specs/2026-04-29-investigation-scope-and-drill-semantics-design.md), [hub-portfolios.md §3](hub-portfolios.md) | Plant > Line > Station rendered as side-by-side child Hub cards. Per-Hub local computation, never cross-Hub arithmetic. | +| **Knowledge Catalyst at Hub scale** | [Wedge spec §7](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) | Cross-project pattern memory federated across an org's full process portfolio. | +| **Gage R&R / formal MSA workflow** | [Wedge spec §3.6.5](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) | Measurement-system-assessment UI + MSA calculator. V1's `msaRequired?` flag is informational only. | +| **Statistical sample-size calculator** | [Wedge spec §3.6.5](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) | Power-analysis helper for Measurement Plans. V1 sample size is manual entry. | +| **In-app Sponsor signoff workflow** | [Wedge spec §4.1](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) | Signoff queue + audit trail. V1 handles Sponsor signoff out-of-band. | + +## §5 The line in one sentence + +V1 ships what one specialist needs to investigate one project with their invited team. Process ships what a process owner needs to monitor multiple projects on a persistent Hub, across an organization with multiple personas working at different methodological levels. + +Anything that smells like "ongoing watching," "multi-project orchestration," "persona-aware default behavior," "cross-Hub anything," or "automation that runs while no one is looking" is a Process feature. Anything that's "this specialist, this project, this evidence, this team I invited" is V1. + +When the smell-test fails: **default to V1 deferral, not Process backport.** If specialists are asking for it inside V1, the wedge spec has likely already named the deferral path. Check [wedge spec §7 + §10](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) before adding. From 585cd2f7ce0f2901375ec3d51b3c18a2cee585a0 Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:46:27 +0300 Subject: [PATCH 03/10] =?UTF-8?q?docs(wedge-future):=20variscout-process/f?= =?UTF-8?q?our-personas.md=20=E2=80=94=20Process=20Owner=20/=20Engineer=20?= =?UTF-8?q?/=20Specialist=20/=20Leader?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Coherence Session A's 4-persona model preserved as Process-scope design. Specialist is the V1 persona; the other three activate in Process. Captures persona-aware default landings, persona x evidence type mapping (Constitution P7), RACI vs persona terminology lock, and persona introduction sequencing for activation. --- .../variscout-process/four-personas.md | 183 ++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 docs/01-vision/variscout-process/four-personas.md diff --git a/docs/01-vision/variscout-process/four-personas.md b/docs/01-vision/variscout-process/four-personas.md new file mode 100644 index 000000000..b83448c9f --- /dev/null +++ b/docs/01-vision/variscout-process/four-personas.md @@ -0,0 +1,183 @@ +--- +title: 'Four personas — Process Owner / Process Engineer / Specialist / Leader' +audience: [product, designer, business] +category: strategy +status: named-future +last-reviewed: 2026-05-17 +parent: docs/01-vision/variscout-process/index.md +related: + - docs/superpowers/specs/2026-05-14-variscout-coherence-design.md + - docs/superpowers/specs/2026-05-16-wedge-architecture-design.md + - docs/01-vision/constitution.md +--- + +# Four personas — Process Owner / Process Engineer / Specialist / Leader + +> **Status: named-future capture.** The four-persona model was locked in Coherence Session A (2026-05-14) as the canonical model for VariScout. The 2026-05-16 wedge pivot retired this model for V1 — V1 collapses to a single Specialist persona with project-membership roles. The four-persona design migrates to VariScout Process unchanged. This file is the consolidated capture of the design. + +## §1 Why four personas, not three or ten + +Pre-wedge VariScout had ten persona files in `docs/02-journeys/personas/` — Analyst Alex, OpEx Olivia, MBB Mira, Engineering Eric, et al. The Coherence audit found that the ten conflated three orthogonal axes: + +- **Persona** (who you are when you log into the product) +- **Entry archetype** (how you arrived — data-first paste, process-first authoring) +- **Task type** (quick exploratory analysis vs. chartered project) + +Six of the original ten were buyer-evaluators, education-funnel students, tenant admins — not in scope for product UX design. They live in marketing / sales / education docs, not in the product persona model. + +That left four product-user personas. The Coherence brainstorm tested "could it be three?" by considering whether SME-flavored work could be absorbed into the analyst persona. The conclusion was no: three of the four personas map cleanly to Constitution P7's three evidence types (Data / Gemba / Expert), and dropping the fourth left expert-evidence creation as "whoever happens to be in the RACI C role" — structurally vague. The four are minimal. + +The Process Engineer persona was renamed from the pre-wedge "SME" label after the wedge pivot. The 2026-05-16 conversation surfaced that "SME" reads as a RACI role, not a persona — and the persona-vs-role confusion was the single most consequential terminology lock in Coherence Session A. **Process Engineer** is the canonical persona name in the named-future Process product. It captures the same role (expert input on artifacts; consulting on investigations from other Leads) while disambiguating from RACI. + +## §2 The four personas + +### §2.1 Process Owner + +**Primary verb.** Monitor + decide. + +**Real-world counterpart.** Operations manager responsible for one or more production lines, queues, or workflows. Goal-setter for the process. Receives drift signals, approves Improvement Project signoffs, owns cadence reviews. + +**Default landing in Process.** Their assigned process's Process tab in State mode (read-only). L1 outcome panel surfaced first, decisions queue (Needs your decision) immediately under that. Process map with state badges below. No paste-screen, no analyze grid — the Process Owner does not enter Process to explore; they enter to scan and decide. + +**Evidence type affinity.** Consumes evidence; doesn't primarily produce it. Reads Findings authored by Specialists and Process Engineers; approves response-path routing; signs off on Sustainment closure. + +**What they see in Process that V1 doesn't surface.** + +- **Persona-default Process-tab landing.** V1's Process tab lands the Specialist on the active project's L2; the Process Owner in Process lands on the Hub's L1 with decisions queue active. +- **Cadence prompts.** When a Hub's PMS triggers a cadence review ([measurement-system.md §3](measurement-system.md)), the prompt routes to the Process Owner's Inbox first. +- **Hub-overview drift dashboard.** A Process Owner monitoring multiple processes sees a portfolio shape ([hub-portfolios.md §3](hub-portfolios.md)) — child Hub miniatures side-by-side, drift indicators per Hub, signoff queue across all their Hubs. + +### §2.2 Process Engineer + +**Primary verb.** Provide expert input + frame process structure. + +**Real-world counterpart.** Subject-matter expert. Engineering lead who knows the physics / mechanics / regulatory constraints / vendor relationships of the process. Authors the canonical map (Process tab Edit mode). Invited to consult on investigations where deep mechanism knowledge is required. + +**Default landing in Process.** My Work surface in consult-shape — pending consult invitations at top, artifacts they've contributed to in the middle, recent Findings they authored at the bottom. Process Engineers don't lead investigations; they're invited into them. + +**Evidence type affinity.** **Expert** (Constitution P7). Their primary contribution is expert assessment — annotated charts, mechanism notes, factor specifications, design intent. Process Engineers may occasionally produce Gemba evidence when their expert work involves direct observation (a Process Engineer doing a structured FMEA walk), but their default mode is desk-side expert input. + +**What they see in Process that V1 doesn't surface.** + +- **Process tab Edit mode default.** When a Process Engineer enters the Process tab, Edit mode is the default (they author the map). V1's default is State. +- **Cross-project Hypothesis cross-reference.** Process Engineers consulting on a new investigation see prior Hypotheses + Findings on the same Hub's history — pattern memory across projects ([scope-line.md §2.4](scope-line.md)). V1 has no cross-project memory. +- **Knowledge Catalyst contribution.** Process Engineers are the primary authors of durable knowledge artifacts in the Hub (mechanism notes, factor taxonomies, design intent). The Catalyst surface in Process is shaped for their workflow. + +### §2.3 Specialist + +**Primary verb.** Analyze + improve. + +**Real-world counterpart.** Improvement specialist — Black Belt, Green Belt, continuous-improvement practitioner. Runs Investigation Projects from Charter through Sustainment. The V1 persona; the only persona present at the V1 cutover. + +**Default landing in Process.** My Work surface in project-shape — active investigations + Improvement Projects they lead at top, then prior projects, then their Hypotheses awaiting evidence. Identical to V1's Home surface, just persona-flagged so other personas have differently-shaped Homes. + +**Evidence type affinity.** **Data** (Constitution P7). Their primary contribution is data analysis — EDA, factor intelligence, capability assessment, Hypothesis evidence. Specialists work at L3 (Local Mechanism) most of the time, with frequent zoom-outs to L1 (Outcome) for context. + +**What they see in Process that V1 doesn't surface.** + +- **Hub context above the project.** A Specialist working a project inside Process sees the Hub the project belongs to as a visible parent in the breadcrumb. V1 hides the Hub. +- **Multi-project on one Hub.** A Specialist may lead two projects on the same Hub simultaneously. V1 has no Hub container above projects, so this case doesn't arise. +- **Cross-Hub investigation.** A Specialist may be invited as Member on projects across multiple Hubs (the org's quality team typically operates this way). Inbox shows pending invitations across the portfolio; My Work shows their active projects across all Hubs. + +The Specialist in Process is essentially the same persona as V1's Specialist, with the surrounding org structure now visible. + +### §2.4 Leader + +**Primary verb.** Read + sponsor. + +**Real-world counterpart.** Executive sponsor, Champion, plant manager, VP of Operations. Authorizes Improvement Projects. Reads reports across the portfolio. May personally engage with one or two projects per quarter, but primarily consumes Process outputs. + +**Default landing in Process.** Org-level overview — child Hub miniatures (the Hub-of-hubs portfolio view), portfolio drift indicators, signoff queue (projects awaiting Sponsor approval), recent Sustainment closures. The Leader's surface is the read-mostly version of the Process Owner's monitoring dashboard, summed across multiple Hubs. + +**Evidence type affinity.** Consumes evidence; doesn't produce it. Reads Reports authored by Specialists, signs off on Charters where the Leader is the named Sponsor, occasionally drills into a specific Hub or project when something catches attention. + +**What they see in Process that V1 doesn't surface.** + +- **Portfolio overview.** Hub-of-hubs side-by-side rendering at the top of their default landing. V1 has no portfolio surface; the Sponsor in V1 sees Report-only for projects they sponsor. +- **Sponsor signoff queue.** In-app Sponsor signoff workflow (named-future per [wedge spec §4.1](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) and [scope-line.md §4](scope-line.md)). V1 handles signoff out-of-band. +- **Cross-Hub drift roll-up — visual, never arithmetic.** The Leader's overview honors ADR-073: distributions per Hub, never an averaged cross-Hub Cpk. The signal is the visual comparison; no `meanCpkAcrossHubs()` exists or will exist. + +## §3 RACI roles vs personas (terminology lock) + +The single most consequential alignment from Coherence Session A: **personas and RACI roles are different concepts**, even though both have role-shaped names. + +| Concept | Scope | Examples | Stored as | +| -------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------- | +| **Persona** (Layer 1) | Tenant account holder with a primary product role | Process Owner / Process Engineer / Specialist / Leader | `teamMember.personaRole` (Process tenancy) | +| **RACI role** | Responsibility slot on a specific artifact | Responsible / Accountable / Consulted / Informed | RACI fields on the artifact (investigation, IP, action) | +| **Artifact reference** (Layer 2) | Named person on an artifact who may or may not have a tenant account | Sponsor (in V1 ACL sense), external SME, named operator | `assignee` / `responsibleRole` / `sponsor` / `verifiedBy` | + +Critical disambiguations: + +- **A Process Engineer in the C RACI role** ≠ **a Specialist in the C RACI role on the same artifact**. Same RACI role, different persona. The persona drives default UI (Edit mode for Process Engineers, My Work landing for Specialists); the RACI role drives access + workflow on that specific artifact. +- **"Process Owner" the persona** (Layer 1 tenant user) ≠ **`processHub.processOwner` the field** (single tenant user reference per Hub — typically occupied by a Process Owner persona, but the field is the slot not the persona) ≠ **"Process Owner (Operations)" in RACI taxonomies** (a Layer 2 named operator who may not be a product user). +- **`ProcessMapNode.responsibleRole`** is a per-node label (e.g., "Maintenance lead") that scopes step ownership on the canvas. It is NOT a tenant user assignment; it doesn't gate access. + +This lock prevents the "is this a persona, a role, or a label?" confusion that the pre-Coherence corpus carried. + +## §4 Persona × evidence type (Constitution P7) + +Three of the four personas map cleanly to the three evidence types: + +| Persona | Primary evidence type | +| ----------------------------------------------------- | -------------------------------------------------------------- | +| Specialist | **Data** — analysis, EDA, factor intelligence | +| Process Engineer | **Expert** — mechanism notes, design intent, expert assessment | +| Process Owner | (Consumes evidence) | +| Leader | (Consumes evidence) | +| _(Anyone — typically Specialists or operators at L3)_ | **Gemba** — direct observation, walks, incident records | + +Gemba evidence doesn't have a primary persona owner because gemba work is contextual — the Specialist on the floor for an investigation walk, the Process Engineer reviewing a specific mechanism in person, or operators (who may or may not be product users) recording observations. This is a Layer 1 / Layer 2 seam: many gemba evidence authors are Layer 2 references on artifacts, not product users. + +## §5 Persona-aware default landing per persona + +The conceptual core of the Process product is **persona-aware default landing**. When a tenant user opens VariScout Process, the surface they see is shaped by their `personaRole`. + +| Persona | Default landing surface | Default view within surface | +| ---------------- | ------------------------------------ | ------------------------------------------------------ | +| Process Owner | Their assigned process's Process tab | State mode, L1 outcome panel, decisions queue surfaced | +| Process Engineer | My Work | Consult-shape: pending consult invitations at top | +| Specialist | My Work | Project-shape: active investigations + IPs they lead | +| Leader | Org-level overview | Hub-of-hubs portfolio + signoff queue | + +V1 does not implement this — the V1 Home surface has one shape (Specialist) because V1 has one persona. The Process activation that introduces persona-aware landing is the most user-visible change between the products. + +## §6 Persona-aware copy density + +Different personas read different copy densities. Coherence Session C locked the copy strategy: + +- **Plain (Flesch-Kincaid grade ≤ 12)** for Process Owners and operators (gemba contexts). Short sentences, common vocabulary, no methodology jargon. +- **Standard (grade ≤ 14)** for Specialists. Methodology vocabulary present but explained on first use per surface. +- **Standard + technical** for Process Engineers. Statistical methodology assumed; engineering and domain vocabulary present. +- **Leader copy** scales with the artifact — Reports use Plain; in-app summaries use Standard. + +This is a Process feature, not a V1 feature. V1 ships one copy density (Standard) for the single Specialist persona. + +## §7 Team workspaces inside artifacts + +Personal queues (My Work, Today, Process tab) show the user's slice. Team coordination happens **inside the artifacts** — Improvement Projects and investigations are team workspaces with team roster (RACI per artifact), activity feed (who did what), threaded comments, @-mentions, signoff queue. + +Cross-persona handoffs become visible in the artifact's activity feed: "Pat (Process Owner) approved Section 6 outcome — Dr. Chen (Process Engineer) added expert evidence — Specialist Mira marked action done." No separate "team coordination" surface; the artifact IS the workspace. GitHub / Linear / Asana pattern. + +This pattern exists in V1's project membership model (Lead / Member / Sponsor on a project). Process expands the model with persona-aware defaults — a Process Engineer invited as Consulted on an investigation lands inside that investigation in their Process Engineer default view, not in a generic shared view. + +## §8 Why this retired from V1 + +The wedge pivot collapsed to one persona because: + +1. **Single-buyer onramp.** The V1 ICP is the Specialist buying the tool for their team. Persona-aware routing requires the buyer to set up tenant-wide persona assignments, which is enterprise IT work — incompatible with a self-service Azure Marketplace deployment for a single specialist. +2. **Engineering scope.** Persona infrastructure (tenant-admin persona assignment UI, persona-aware default routing across every surface, persona-adaptive Home variants) is multi-PR engineering work. The wedge committed to ship V1 with the smallest defensible anatomy. +3. **Methodology purity.** With one persona, every surface serves the same primary verb (analyze + improve). Multiple personas multiply the design surface (every screen has 4× the UX variants); V1 deliberately accepts the design constraint that comes with one persona. + +The four-persona model migrates to Process intact. The infrastructure to support it (persona-aware routing, persona-adaptive Homes, RACI engagement-profile model, copy-density tiers) is Process scope, not V1. + +## §9 Process activation — persona introduction order + +If V1 validates and Process activates, persona introduction is sequenced rather than simultaneous: + +1. **Specialist (already present from V1).** No change; the V1 Specialist continues in Process unchanged. +2. **Process Owner.** First new persona. Smallest activation: introduce `personaRole` on tenant-member records, route Process tab to State mode + decisions queue when the user is Process Owner. Everything else stays the same. +3. **Process Engineer.** Second activation. Adds Edit mode default + consult-shape My Work + cross-project Hypothesis cross-reference. +4. **Leader.** Last. Activates with portfolio overview ([hub-portfolios.md §3](hub-portfolios.md)) and Sponsor signoff workflow. Leader activation requires Process to already have multi-Hub installed base; introducing it before Process has enough Hubs to portfolio means an empty surface. + +This is speculation, not commitment. When Process activates, the team will re-plan persona introduction against the customer-pull signal of the day. From dee71ef14a2464b81f5eb24f10198f6e44ec1803 Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:46:57 +0300 Subject: [PATCH 04/10] =?UTF-8?q?docs(wedge-future):=20variscout-process/h?= =?UTF-8?q?ub-portfolios.md=20=E2=80=94=20multi-hub=20orchestration=20+=20?= =?UTF-8?q?drill=20semantics?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hub-as-first-class-noun + multi-hub portfolios + the four drill operations (Hub->Step, Step->Channels, Step->Sub-flow, Org Hub-of-Hubs). Versioned canonical map governance + multi-investigation lifecycle on one Hub. ADR-073 locality rule enforced by structural absence: no meanCpkAcrossHubs() exists or will exist. --- .../variscout-process/hub-portfolios.md | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/01-vision/variscout-process/hub-portfolios.md diff --git a/docs/01-vision/variscout-process/hub-portfolios.md b/docs/01-vision/variscout-process/hub-portfolios.md new file mode 100644 index 000000000..08c7ded18 --- /dev/null +++ b/docs/01-vision/variscout-process/hub-portfolios.md @@ -0,0 +1,137 @@ +--- +title: 'Hub portfolios — multi-hub orchestration + drill semantics' +audience: [product, engineer, designer] +category: strategy +status: named-future +last-reviewed: 2026-05-17 +parent: docs/01-vision/variscout-process/index.md +related: + - docs/superpowers/specs/2026-04-29-investigation-scope-and-drill-semantics-design.md + - docs/superpowers/specs/2026-04-29-multi-level-scout-design.md + - docs/superpowers/specs/2026-04-28-production-line-glance-design.md + - docs/07-decisions/adr-073-no-statistical-rollup-across-heterogeneous-units.md +--- + +# Hub portfolios — multi-hub orchestration + drill semantics + +> **Status: named-future capture.** Hub-as-first-class-noun, multi-hub portfolios, and the four drill operations are the structural shape of VariScout Process. V1 keeps the Hub internal (data architecture only) and operates per-project; Process surfaces the Hub as a navigable concept and adds portfolio-spanning operations. + +## §1 Why the Hub becomes first-class in Process + +In V1, the Hub is internal data architecture. It backs paste data + outcome + process map + factors, and it persists across projects, but no UI surfaces it as a navigable concept. Users see "Project" and "Process tab" — not "Hub." The Project is the user-facing container; the Hub is what the Project wraps. + +This works for V1 because the V1 ICP is the Specialist running one project at a time with their invited team. The Hub doesn't need to be visible because the team's mental model is the project. + +In Process, the buyer is different. The Process Owner persona owns one or more processes that produce outcomes the business cares about over time — independent of any individual Improvement Project. Their mental model is the process, not the project. The Hub IS the process — its canonical map, its outcome history, its accumulated investigation memory, its persistent identity across the projects that come and go on it. + +When the Process Owner persona activates ([four-personas.md §2.1](four-personas.md)), the Hub must become visible. This is the structural pivot that everything else in Process hangs on. + +## §2 What a Hub holds (Process scope) + +A Process Hub holds the **persistent logic map** of a process line and everything that derives from it. + +| Component | What it holds | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Canonical map** | DAG of process steps, sub-steps, branches, joins. Persistent across projects. Authored by Process Engineer; revised over time with `canonicalMapVersion` tracking. | +| **Specs per column / per step** | Target, USL, LSL, cpkTarget, characteristic type. Per the `capabilityScope` lookup indexed by `(node × context-tuple)` — supports multi-product, multi-supplier reality. | +| **Named contexts** | Context dimensions discovered through branch/join in the canonical map. Drive context-tuple stratification at L2 and L3. | +| **Cadence definition** | Manual / hourly / shiftly / daily / weekly. Drives Evidence Source semantics ([measurement-system.md §2](measurement-system.md)). | +| **Evidence Sources** | Recurring evidence streams (Line 4 fill-weight export, claims queue weekly extract, supplier intake defects, agent review log). | +| **Snapshot history** | Every dataset matched to this Hub becomes a dated Snapshot in its history. | +| **Investigation history** | Every Improvement Project that has run on this Hub is preserved. Cross-project pattern memory federates Findings + Hypotheses across them. | +| **Finding history** | Findings that have crossed the evidence threshold are anchored to canonical-map nodes. Visible across projects on the same Hub. | +| **Process Owner reference** | `processHub.processOwner` field — single tenant user reference per Hub. Drives default landing routing + persona-aware signoff gating. | + +The Hub data model already supports most of this in V1's internal storage. What changes in Process is **the UI** — Hub becomes a user-visible noun with its own surfaces (Hub list, Hub detail, Hub Capability tab, Hub cadence review, Hub portfolio overview). + +## §3 Hub-of-hubs portfolio view + +Plant > Line > Station modeled as **nested hubs**, not as nested ProcessMaps. The plant hub renders line-hub cards side-by-side. The line hub renders station-hub cards side-by-side. Each child Hub computes locally; the parent renders adjacent. + +**Aggregation rule.** Visual side-by-side only, never arithmetic. Each child Hub computes its own per-step boxplots locally against its own specs; the parent hub renders them adjacent. There is no `meanCpkAcrossHubs()` and never will be. ADR-073's no-rollup invariant holds by structural absence — the engine exposes no function that produces a single statistical metric across heterogeneous Hubs. + +**Example.** A regional plant has four lines (A, B, C, D). The plant Hub view shows four cards, each card a miniature production-line-glance dashboard for that line. Lines A and B run a `Coke 12oz` SKU; lines C and D run a `Sprite 16oz` SKU. The plant manager (Leader persona) sees that A and B's `Cap` boxes sit visibly lower than C and D's, prompting a focused investigation on A's capping torque calibration. No arithmetic was performed; the visual side-by-side carries the signal. + +**Cross-hub context filter chip strip.** When the user filters at the plant Hub level by `Shift=Night`, the chip propagates to each child Hub's local computation. The plant view re-renders with each child Hub re-computed under the shared filter. Each Hub still computes its own metrics locally; the filter is a parameter, not an aggregation. + +**Status in V1.** Not built. The same dashboard primitive multiplies across child hubs trivially (the per-(node × context) Cpk engine doesn't need to know it's running inside a portfolio). The remaining work is the plant-hub layout, side-by-side card composition, cross-hub context filter chip strip, and Leader-persona default landing. + +## §4 The four drill operations + +The Hub's analytical surface supports four navigation operations. Three are drills (each moves analytical focus to a finer scope); one is the organizational hierarchy view (Hub-of-hubs, §3 above). Each has its own aggregation rule and visual shape. **The naming-and-rules contract:** any new analytical surface must fit into one of these operations or be added explicitly to the framework. + +### §4.1 Drill A — Hub → Step (the production-line-glance dashboard) + +Click a step node in the canonical map. The step's per-step capability detail panel renders, scoped to that node's data across all contributing investigations and context-tuples. + +**Aggregation rule.** Per `(canonical-node × context-tuple)` Cpk computed locally; visualized as a distribution (per-step Cpk boxplot). Each context-tuple contributes a box (or a dot when N is small); the analyst's eye does the pattern recognition; no arithmetic spans heterogeneous specs. + +**Example.** On a coffee-roasting Hub, click the `Roast` node. The detail panel shows a boxplot of per-context Cpks for `Roast_Color`, with boxes for each lot batch the data carries. A target line at the Hub's `targetCpk` runs across; n<30 badges decorate the boxes for batches with thin samples. + +**Status.** Engine shipped in V1 via PRs #103/#105/#106/#107 (per the source spec). The Hub Capability tab is live in azure-app today. **In V1, Drill A operates per-project.** In Process, Drill A operates per-Hub — the same engine, aggregating investigations across the Hub's history. + +### §4.2 Drill B — Step → Channels (existing Performance mode) + +A step with replicated equipment — four cavities of a multi-cavity press, eight heads of a filling carousel, two parallel underwriting queues — has a within-step comparison surface. Each replica is a channel; the question is "which channel is weakest?" + +**Aggregation rule.** Same physics, same measurement column — comparison across channels is methodologically valid because the channels share specs. + +**Example.** Inside the `Fill` step's investigation, switch to Performance mode. The Cpk-per-head bar chart shows heads 5–8 running tighter than heads 1–4. The analyst opens an i-chart filtered to head 6 to see a downward drift over the last four hours. + +**Status.** Shipped in V1 Performance mode. **No change between V1 and Process.** The within-step comparison axis works identically at project scope and Hub scope. + +### §4.3 Drill C — Step → Sub-flow (recursive ProcessMap) + +A step CAN reference a sub-ProcessMap when the step is itself a complex sub-process. `Underwriting_Review` opens into `Document_Verify → Risk_Score → Compliance_Check → Approve_or_Refer`. + +**Aggregation rule.** Same as Drill A applied at the sub-flow scope. The sub-flow has its own canonical-node set, its own spec rules, its own per-step boxplot. + +**Example.** A claims-processing flow has an `Adjudicate` step that hides a five-step sub-flow. Click `Adjudicate` to drill in; the production-line-glance dashboard re-anchors on the sub-flow; per-step boxplots reveal that the `Manual_Triage` sub-step is the contribution leader, not the `Auto_Triage` sub-step the team had been instrumenting. + +**Status in V1.** Engine + data model support it (a node may reference a child ProcessMap), and the dashboard primitive can re-anchor. The remaining work is the Drill C navigation affordance, recursion guard (max 1 level in V1), and breadcrumb UX. The decision-log entry on V1 surface debt notes this as a deferred sequencing item; it remains deferred and migrates to Process unchanged. + +### §4.4 Org Hub-of-Hubs view + +Plant > Line > Station rendered as side-by-side child-Hub dashboards, plus a cross-hub context filter chip strip. Covered in §3 above as its own surface (not a drill in the strict sense — it's an organizational hierarchy view, not a navigation between analytical scopes). + +## §5 Governance — versioned canonical map + +The Hub's canonical map is **versioned**. Hub owner (Process Engineer or Process Owner depending on the org) edits canonical structure + specs. Investigations pin a `canonicalMapVersion`; can `pull-latest` explicitly when they want to inherit upstream changes. + +| Operation | Behavior | +| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Hub owner edits canonical map** | Increments `canonicalMapVersion`. Existing investigations remain pinned to their version. | +| **Investigation `pull-latest`** | Investigation re-pins to the current `canonicalMapVersion`. Run automatic node-mapping diff; flag any unresolvable mappings for the Specialist to address. | +| **Investigation `specsOverride` set** | Local fork — investigation uses its own specs instead of inheriting the Hub's. Flagged in UI as "local fork"; visible to the Process Engineer maintaining the canonical map. | + +The B0 migration banner shipped in V1 PR #106 is the first user-facing surface of this governance model. In Process, the governance UI expands — Hub Engineer surfaces show pending pulls + local forks + version diffs. + +This governance discipline is what keeps the Hub's canonical map coherent over time across many projects. Without it, every project's investigation slowly forks its own version of the process, and cross-project pattern memory (the Knowledge Catalyst feature) becomes worthless. + +## §6 Multi-investigation lifecycle on one Hub + +Multiple investigations can run on the same Hub concurrently. The Hub's investigation history accumulates them. Cross-project pattern memory (Knowledge Catalyst) federates Findings + Hypotheses across them. + +**Hub-of-investigations dashboard.** Process Engineer / Process Owner persona view: "what's currently being investigated on this Hub?" — list of active projects, their lifecycle stages, Hypotheses in flight, Measurement Plans awaiting collection. V1 has the equivalent view per-project; the Process version is per-Hub, listing projects within. + +**Investigation cross-reference.** When a new Hypothesis is created on a Hub, the Wall surface checks the Hub's historical Hypotheses + Findings for matches on the same `(step, factor)` pair. Suggestions surface as "previously investigated" hints. Specialists can choose to inherit prior Findings as evidence or start fresh. + +**Cadence-anchored Measurement Plans.** Plans on a Hub-level investigation can fire at recurring cadence intervals (not just one-shot). When the cadence fires, the Plan re-collects evidence — a new Finding is auto-suggested to link to the recurring Plan. This is the engine that makes Process Hubs durable monitoring surfaces, not just project-scoped one-shots. + +## §7 Process Hub as the cadence-review surface + +The Process tab in Process is the Process Owner's default daily / weekly artifact. It looks much like the V1 Process tab structurally — same canvas substrate, same State / Edit modes, same L1/L2/L3 navigation — but the State mode surfaces additional Process-scope content: + +- **Hub-overview drift dashboard** (Process Owner monitoring multiple Hubs sees a portfolio shape — covered in [monitoring.md §3](monitoring.md)) +- **Cadence prompts** in the decisions queue (PMS-triggered review prompts — [measurement-system.md §3](measurement-system.md)) +- **Cross-project Hypothesis cross-reference** when reading any step (pattern memory) +- **Investigation history** linked off each step (which projects have investigated this step? what did they find?) + +The Process Owner's primary daily action is scanning the Process tab State mode and routing items from the decisions queue. Investigation work happens inside the projects nested under the Hub; the Process tab is the orchestration layer, not the workspace. + +## §8 Cross-references + +- The four drill operations are originally specified in [Investigation Scope and Drill Semantics §3](../../superpowers/specs/2026-04-29-investigation-scope-and-drill-semantics-design.md). The named-future portions (Drill C, Org Hub-of-Hubs) are captured here. +- The Hub-of-hubs aggregation rule is locked by [ADR-073](../../07-decisions/adr-073-no-statistical-rollup-across-heterogeneous-units.md) (no statistical rollup across heterogeneous units). +- The multi-level architecture that drills operate on lives in [methodology.md](methodology.md) and [Multi-level SCOUT spec](../../superpowers/specs/2026-04-29-multi-level-scout-design.md). +- The per-`(node × context)` Cpk engine that Drill A renders is the production-line-glance engine — see [Production Line Glance design](../../superpowers/specs/2026-04-28-production-line-glance-design.md). From d0b0a044c817198f3eb94c8b6563875e778f8156 Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:47:25 +0300 Subject: [PATCH 05/10] =?UTF-8?q?docs(wedge-future):=20variscout-process/m?= =?UTF-8?q?easurement-system.md=20=E2=80=94=20Process=20Measurement=20Syst?= =?UTF-8?q?em?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PMS as cadence-review substrate for Process Owner persona. Stable measure definitions + Evidence Sources + Snapshots + Signal Cards + Survey readiness + cadence rules combining into Current Process State. Three timescales (daily huddle / weekly review / monthly leadership) with their own surfaces, personas, triggers. PMS makes the methodology continuous; projects are events on top of it. --- .../variscout-process/measurement-system.md | 174 ++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 docs/01-vision/variscout-process/measurement-system.md diff --git a/docs/01-vision/variscout-process/measurement-system.md b/docs/01-vision/variscout-process/measurement-system.md new file mode 100644 index 000000000..02777816e --- /dev/null +++ b/docs/01-vision/variscout-process/measurement-system.md @@ -0,0 +1,174 @@ +--- +title: 'Process Measurement System (PMS) — stable measures + cadence + Current Process State' +audience: [product, designer, engineer, quality-manager] +category: methodology +status: named-future +last-reviewed: 2026-05-17 +parent: docs/01-vision/variscout-process/index.md +related: + - docs/superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md + - docs/superpowers/specs/2026-04-29-consolidated-method-and-surface-overview-design.md + - docs/superpowers/specs/2026-04-29-multi-level-scout-design.md + - docs/superpowers/specs/2026-05-16-wedge-architecture-design.md +--- + +# Process Measurement System (PMS) — stable measures + cadence + Current Process State + +> **Status: named-future capture.** PMS is the cadence-review substrate for the Process Owner persona. Stable measure definitions + Evidence Sources + Snapshots + Signal Cards + Survey readiness + cadence rules combine into the latest structured read of a process — **Current Process State**. The V1 wedge defers this surface explicitly; the engine pieces are partly shipped today, the cadence-review surface is named-future. + +## §1 What PMS is, and what it isn't + +The Process Measurement System is **not** a separate product or a separate analytical engine. It's the **disciplined recurring use** of VariScout's existing analytical primitives, organized around a process's stable measure definitions and review cadence. + +The structure: + +| Component | Purpose | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Stable measure definitions** | What this process is measured by — outcome measures, in-process measures, defect categories, throughput metrics. Defined once per Hub; persistent across investigations. | +| **Evidence Sources** | Recurring evidence streams that feed measurements — a daily fill-weight export, a weekly claims-queue extract, a continuous sensor stream. Per [pipelines.md](pipelines.md). | +| **Snapshots** | Dated evidence packages. One Snapshot per Evidence Source per cadence cycle. The unit of "what changed since last review." | +| **Signal Cards** | Compact per-measure cards rendering Current Process State — Cpk, trend, drift, recent context. | +| **Survey readiness** | Per-measure check: do we have enough recent evidence, of the right shape, to interpret this measure today? | +| **Subgroup logic** | Per-measure: how do we group samples? (Subgroup size, time bucketing, context stratification.) | +| **Targets** | Per-measure spec rules — USL / LSL / target / cpkTarget. Indexed by `(node × context-tuple)` per the existing per-characteristic spec model. | +| **Cadence rules** | When does this process get reviewed? Daily huddle, weekly process review, monthly leadership review, ad-hoc on signal. | + +Together these produce **Current Process State** — not "stable" or "unstable" as a label, but a cadence-review surface that triggers a response path. The Process Owner persona consumes Current Process State as their primary daily / weekly artifact. + +PMS is **not** real-time monitoring. It's **not** an alarm runtime. It's **not** an ERP integration platform. It's the disciplined cadence-shaped consumption of the process's recurring evidence by the right persona at the right interval. + +## §2 The three timescales + +PMS operates on three timescales simultaneously. The cadence rules per measure route different measures to different timescales. + +### §2.1 Daily huddle scale + +**Question.** "What changed today? What needs attention now?" + +**Surface.** Hub's daily huddle view — latest Snapshot's Current Process State for each measure flagged as `cadence: daily`. Compact Signal Cards; one screen. + +**Persona.** Process Owner (primary), Specialist (when investigating actively), Process Engineer (when on-call for the process). + +**Triggers.** Drift indicator on any measure → routes to Process Owner's decisions queue. Survey-readiness check failing → routes to Specialist to gather more evidence. Sustainment cadence prompt fired → routes to the project owner (Lead). + +### §2.2 Weekly process review scale + +**Question.** "Is the process meeting requirements over the last week? Where are recurring focus areas? What should be sustained or escalated?" + +**Surface.** Hub's weekly review view — Snapshot history compare across the last N cycles. Trend chart per measure. Capability over time. Recent Findings + Hypotheses surfaced from in-flight investigations. + +**Persona.** Process Owner (primary), Process Engineer (when expert input is needed on emerging Hypotheses), occasionally Leader (when reading a specific Hub). + +**Triggers.** Sustained drift over multiple cycles → response path Charter (escalate to formal investigation). Capability improvement validated across cycles → response path Sustainment (cadence to verify it stays). Recurring focus pattern → response path Investigate (start a new Improvement Project). + +### §2.3 Monthly / quarterly leadership scale + +**Question.** "How is this portfolio doing? Which Hubs need attention? Where are we investing improvement work?" + +**Surface.** Org-level overview ([hub-portfolios.md §3](hub-portfolios.md)) — Hub-of-hubs side-by-side, portfolio drift indicators, Sponsor signoff queue, recent Sustainment closures. Per-Hub computation; no cross-Hub arithmetic. + +**Persona.** Leader. + +**Triggers.** Hub-level drift escalation → Process Owner of affected Hub flagged for response. Charter approval queue → Leader signoff. Portfolio resource allocation decisions (out-of-app, but informed by the overview). + +## §3 Current Process State — the cadence-review surface + +**Current Process State** is what the cadence-review view renders. It is the latest structured read of the process across: + +| Axis | What it surfaces | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| **Outcome** | L1 outcome distribution + Cpk vs target + drift. Per the multi-level methodology. | +| **Flow** | L2 process map with state badges per step — capability badge, drift indicator, in-flight investigation count. | +| **Known x-control** | Which factors are being actively controlled. Stratification status. | +| **Capability structure** | Per-(step × context-tuple) capability summary. The Hub Capability tab content, surfaced in cadence-review shape. | +| **Trust** | Per-measure: is the evidence current enough, large enough, the right shape? Sample-size honesty applied across the board. | + +Current Process State is not a single number. It is not a stability label. It is a **structured read** that surfaces what the Process Owner needs to decide on today. + +The decisions queue (the indigo-accent cards at the top of the Process tab State mode) is where Current Process State surfaces as **actionable signals**. Each queue item carries a response-path CTA — Investigate / Quick Action / Charter / (auto-fired) Sustainment. + +## §4 Stable measures vs investigation measures + +**Stable measures** are the measures the process is run by. They persist across investigations, snapshots, and time. The Hub's Process Owner defines them; they don't change with each Improvement Project. + +Examples: + +- Fill weight on Line 4 (outcome measure) +- Cap torque per head (in-process measure) +- Customer escapes per million (lagging outcome) +- Defect rate by category (defect measure) +- Cycle time per workflow step (throughput measure) + +**Investigation measures** are project-specific. A Specialist running an Improvement Project may introduce additional factors / measures specific to their investigation that aren't in the Hub's stable definitions. These don't promote to the Hub's PMS unless the investigation produces a Finding that justifies adding the measure. + +The promotion path: investigation produces a strong Finding → the measure that revealed the Finding gets considered for promotion to stable → Process Engineer reviews → if accepted, the measure joins the Hub's stable definitions and starts being surfaced in Current Process State. + +This is **how the Hub learns over time**. The Knowledge Catalyst feature ([scope-line.md §4](scope-line.md)) is the durable record of which investigation measures have promoted to stable status. + +## §5 Cadence rules per measure + +Each stable measure carries a cadence rule. The cadence determines which timescale surface renders it and how often Current Process State is recomputed for that measure. + +| Cadence | Refresh interval | Surface | +| ------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- | +| **Manual** | On-demand (Specialist runs analysis) | Per-project Analyze tab | +| **Shiftly** | Per shift (typically 8h) | Process tab daily huddle view | +| **Daily** | Daily | Process tab daily huddle view | +| **Weekly** | Weekly | Process tab weekly review view | +| **Hourly** (named-future) | Hourly automated | Process tab daily huddle view; requires auto-ingestion ([pipelines.md](pipelines.md)) | + +When a Snapshot lands at the cadence interval, the PMS recomputes Current Process State and updates Signal Cards. If drift / breach / out-of-control is detected, the relevant queue items surface for the Process Owner. + +V1's `EvidenceSnapshot` type exists at `packages/core/src/evidenceSources.ts:43-51`. It carries `origin`, `importedAt`, `rowTimestampRange`. The cadence rules + automated refresh layer is named-future — V1 has the Snapshot data model but no cadence-triggered refresh. + +## §6 Survey readiness check + +For each stable measure, the Survey readiness check answers: **do we have enough recent evidence, of the right shape, to interpret this measure today?** + +Six V1 rule categories (also named-future as a generalized cross-phase methodology layer): + +1. **Status.** When did this measure last receive a Snapshot? Is it stale? +2. **Data collection.** Is the recent Snapshot adequate sample size? Are required columns present? +3. **Triangulation.** Are Gemba and Expert evidence available where the Data evidence alone would be ambiguous? +4. **Power.** For comparative analyses, do we have enough samples per group? +5. **Drift.** Has the measure's distribution shifted in a way that flags the recent Snapshot as not comparable to prior cycles? +6. **Lifecycle.** Is the measure still meaningful for the current process configuration? Or has the process changed enough that this measure no longer answers the question it was defined for? + +When a readiness check fails, the measure's Signal Card carries a "needs evidence" badge. The decisions queue surfaces a routing item to whoever can address it (Specialist for sample-size, Process Engineer for triangulation, Process Owner for lifecycle review). + +This is **dual-surface** in Process: inline on the Signal Card + as Inbox prompts to the responsible persona. + +## §7 How PMS triggers response paths + +Per the three V1 canvas response paths + the auto-fire Sustainment pattern (ADR-080), Process expands the routing: + +| Trigger | Response path | Routed to | +| -------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Drift detected on outcome measure | Investigate or Charter (Specialist's choice) | Specialist persona, with cross-project Hypothesis cross-reference surfaced | +| Drift detected on multiple measures over multiple cycles | Charter (escalation) | Process Owner signs off; Leader may be Sponsor | +| Single-cycle out-of-spec breach | Quick Action | Specialist responsible for the relevant step | +| Sustainment cadence interval reached | Sustainment auto-fires | Project Lead reviews; closes or extends | +| Capability improvement validated across cycles | Sustainment closure | Project Lead + Sponsor signoff | +| Recurring focus pattern across multiple Snapshots | Investigate (new project) | Specialist accepts assignment; Charter inherits the recurring focus as initial context | +| Survey readiness failing (sample size) | Measurement Plan creation on the relevant Hypothesis | Specialist adds Plan; collection follows | +| Survey readiness failing (lifecycle / measure stale) | Measure-review decision | Process Engineer + Process Owner discuss in next weekly review | + +Each routing carries the relevant artifact link — clicking a queue item lands the user in the workspace they need (Process tab L2 for Investigate, Improvement workspace for Sustainment closure, Charter form for escalation). + +## §8 Process Measurement System vs Improvement Project lifecycle + +PMS is **continuous**. Improvement Projects are **bounded**. They coexist on a Hub. + +The Hub's PMS surfaces Current Process State at cadence. When the state surfaces a problem worth structured investigation, a project is chartered. The project runs its lifecycle (Charter → Approach → Sustainment) and closes. The Hub's PMS continues — the project's outputs (validated improvement actions, new Findings, sometimes new stable measures) feed back into PMS. The Hub's Current Process State reflects the post-project reality. + +A Hub may have multiple projects open simultaneously, each addressing a different problem the PMS surfaced. The Hub Owner (Process Owner) sees all active projects in their Hub-overview view; the projects themselves are workspaces for the Specialists who lead them. + +This is **how PMS makes the methodology continuous**. V1 ships the Improvement Project lifecycle but doesn't ship PMS — V1 projects exist without a persistent PMS layer underneath them. In Process, the PMS layer is the daily artifact; projects are events on top of it. + +## §9 Cross-references + +- The Evidence Source / Snapshot / Profile Application data model is specified in [Evidence Sources and Data Profiles spec](../../superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md). The V1 implementation slice exists; the cadence-review surface that consumes the data is named-future. +- The PMS → Current Process State framing is articulated in [Consolidated Method and Surface Overview §4](../../superpowers/specs/2026-04-29-consolidated-method-and-surface-overview-design.md). +- The auto-fire Sustainment pattern that PMS extends is [ADR-080](../../07-decisions/adr-080-sustainment-auto-fire-pattern.md). +- The three-level methodology that PMS organizes evidence around is in [methodology.md](methodology.md). +- The monitoring surfaces that render Current Process State live in [monitoring.md](monitoring.md). From dac1fe811c7815c49793e758bd6301b3756e8109 Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:47:54 +0300 Subject: [PATCH 06/10] =?UTF-8?q?docs(wedge-future):=20variscout-process/m?= =?UTF-8?q?ethodology.md=20=E2=80=94=20three-level=20outcome/flow/operatio?= =?UTF-8?q?ns?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three-level methodology (System+Outcome / Process Flow / Local Mechanism) as substrate shared across both products. Named-future piece: persona x level mapping (Process Owner reads L1, Process Engineer authors L2, Specialist works L3, Leader scans L1 portfolio). Watson invariants (ADR-073, contribution-not-causation, observed-vs- expected lens, sample-size honesty, target-relative Cpk grading, geometric interaction language) hold across V1 and Process. --- .../variscout-process/methodology.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/01-vision/variscout-process/methodology.md diff --git a/docs/01-vision/variscout-process/methodology.md b/docs/01-vision/variscout-process/methodology.md new file mode 100644 index 000000000..a5ca7d4a0 --- /dev/null +++ b/docs/01-vision/variscout-process/methodology.md @@ -0,0 +1,155 @@ +--- +title: 'Three-level methodology — Outcome / Process Flow / Local Mechanism' +audience: [product, designer, engineer, analyst, quality-manager] +category: methodology +status: named-future +last-reviewed: 2026-05-17 +parent: docs/01-vision/variscout-process/index.md +related: + - docs/01-vision/methodology.md + - docs/superpowers/specs/2026-04-29-multi-level-scout-design.md + - docs/superpowers/specs/2026-05-03-variscout-vision-design.md + - docs/07-decisions/adr-073-no-statistical-rollup-across-heterogeneous-units.md + - docs/07-decisions/adr-074-scout-level-spanning-surface-boundary-policy.md +--- + +# Three-level methodology — Outcome / Process Flow / Local Mechanism + +> **Status: named-future capture (methodology shared with V1; persona-aware layering is Process scope).** The three-level methodology is the substrate for both products. What's named-future is the persona-aware layering: in Process, each level has a primary persona that consumes it; in V1, one Specialist persona reads all three levels. + +## §1 The three levels + +Every process is read at three levels simultaneously. The levels are different shapes of question about the same process; they share one map but reveal different cognitive surfaces. + +| # | Level | What it answers | Captured as | +| --- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| 1 | **System / Outcome** | What the customer or business must experience. | Outcome distribution + Cpk vs spec + drift, at L1 on the canvas | +| 2 | **Process Flow** | The sequence and topology of steps that produce the outcome — what flows through which steps, at what rate, with which waits, handoffs, bottlenecks. | The canonical map (DAG) of process steps, at L2 on the canvas | +| 3 | **Local Mechanism** | The inputs, settings, materials, environment, operator, and per-step measurements that drive each step. The physics and the recipe. | Per-step factor analysis + Hypothesis evidence, at L3 on the canvas | + +The three levels are **orthogonal to the analysis modes** (Capability / Performance / Yamazumi / Defect / Process Flow). A user can read at any level in any mode; the level is which slice of the process you're scanning, the mode is which analytical lens you apply. + +## §2 Level × primary persona (Process-scope mapping) + +In V1, one Specialist persona reads all three levels — they monkey-bar between L1 outcome scans (for context), L2 step navigation (to choose where to investigate), and L3 mechanism work (where their primary effort lives). The single-persona V1 design intentionally collapses the persona × level grid. + +In Process, the levels acquire **primary persona affinities**: + +| Level | Primary persona | Default reading shape | +| ------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| **L1 — Outcome** | Process Owner (monitoring) + Leader (portfolio) | "Is this process meeting its outcome target? What's drifting?" Cadence-shaped, decision-oriented. | +| **L2 — Process Flow** | Process Engineer (authoring) + Process Owner (scanning) | Process Engineer maintains the canonical map; Process Owner scans state badges per step at cadence. | +| **L3 — Local Mechanism** | Specialist (analyzing) | Where the EDA work happens. Hypothesis-driven, evidence-collecting, Findings-producing. | + +A given person may operate at multiple levels — a Process Owner who personally investigates a finding zooms into L3, a Specialist who needs context for their L3 work zooms out to L1. The affinity assigns the **default** view for each persona on a given level. + +This persona × level grid is the conceptual core of the Process product. V1 doesn't implement it because V1 has one persona. + +## §3 Watson invariants — methodology rules that hold across both products + +These methodology rules are enforced in the engine and taught in the UI. They're invariants — they hold regardless of product (V1 or Process) and regardless of level (L1 / L2 / L3). + +### §3.1 No statistical rollup across heterogeneous units + +Capability, defect rates, and trend metrics are computed per `(node × context-tuple)`. The canvas's branch / join + context-propagation model makes this structural — heterogeneous siblings cannot be silently averaged. Per [ADR-073](../../07-decisions/adr-073-no-statistical-rollup-across-heterogeneous-units.md). + +**Why.** A Cpk of 1.0 against `[349, 359]` (12 oz fill) and a Cpk of 1.0 against `[468, 478]` (16 oz fill) live on unrelated physics. Averaging or min-collapsing them yields a number no Master Black Belt can interpret. The same prohibition holds across machines, lines, shifts, suppliers, paint classes, or any other dimension that resolves to a different `SpecRule`. + +**How it shows up in Process.** The Hub-of-hubs portfolio view ([hub-portfolios.md §3](hub-portfolios.md)) renders child Hub miniatures side-by-side; each child computes locally; no `meanCpkAcrossHubs()` exists. The Process Owner's monitoring dashboard ([monitoring.md](monitoring.md)) surfaces per-Hub drift indicators; no cross-Hub summary metric. + +**Structural absence enforcement.** The engine exposes no function that collapses Cp/Cpk across investigations, Hubs, or context-tuples with heterogeneous specs. The rule holds by structural absence — the unsafe operation does not exist to be misused. + +### §3.2 Contribution, not causation + +EDA reveals factors that **contribute to** variation; it does not prove causality. The product's language stays in contribution terms ("explains 23% of variation"), never in causal claims ("X causes Y"). CoScout coaching enforces this. Pre-commit ESLint enforces this. + +The Six Sigma "root cause" framing is replaced with **contribution** / **suspected cause** / **mechanism**. The "suspected cause" terminology is V1's surface vocabulary; it persists into Process unchanged. + +### §3.3 Observed vs expected — the universal lens + +Every analysis answers: _is what we see different from what we expected?_ This shared structure (observed value compared to a model of expected value) underlies chi-square, regression, ANOVA, and capability indices. + +The product commits to making this lens explicit in coaching. When a chart surfaces an anomaly, the explanation says _"observed X vs expected Y; difference is significant by Z"_ — not just "anomaly detected." This is a universal lens that operates identically across V1 and Process. + +### §3.4 Sample-size honesty + +- Cpk is **suppressed for n < 10** (deterministic refusal, not a hint). +- Cpk is **badged "trust pending" for n < 30**. +- Trust is a first-class card overlay, not a footnote. + +In Process, sample-size honesty becomes visible at additional surfaces — Hub-overview cards inherit the same trust badging; PMS Signal Cards inherit the same refusal at n<10. The Survey readiness check ([measurement-system.md §6](measurement-system.md)) institutionalizes this discipline at the cadence layer. + +### §3.5 Target-relative Cpk grading + +Cpk grades band against the **user-set target** (default 1.33), never against literature constants (1.67 / 1.33 / 1.00). `statusForCpk` is the one source of truth. + +This is per-Hub configurable in Process — different processes have different capability targets (a medical-device fill line aims higher than a sandwich-factory fill line). The Process Engineer per Hub may set the `targetCpk` once during canonical-map authoring; the UI honors it across all per-Hub renderings. + +### §3.6 Geometric interaction language + +Two-factor interactions are described in **geometric terms** (ordinal / disordinal / parallel) and their effect on Y. The product never assigns "moderator" or "primary" roles to one factor over another — that's a causal claim VariScout doesn't make. + +Pre-commit ESLint enforces this. Holds across V1 and Process. + +## §4 The five response paths (pre-wedge) → three (V1) → ? + +The pre-wedge VariScout vision named five response paths for any current state of any step: + +1. Quick action +2. Focused investigation +3. Charter (formal Improvement Project) +4. Sustainment +5. Handoff + +The V1 wedge reduced to **three canvas response paths** (Investigate, Quick Action, Charter), with Sustainment auto-firing per [ADR-080](../../07-decisions/adr-080-sustainment-auto-fire-pattern.md) and Handoff folded into Sustainment closure. + +**Process likely re-expands.** The original five-path framing serves multi-persona reality better than three. Specifically: + +- **Handoff** as an explicit response path matters when work crosses persona boundaries (Process Engineer hands off a mechanism finding to a Specialist; Specialist hands off a sustained improvement to a Process Owner). +- **Sustainment as an explicit user choice** (not auto-fire) matters when the Process Owner is doing cadence review and consciously deciding "this capability is fine; schedule the next review." + +Whether Process re-expands to five paths or stays with three + auto-firing for some paths is a Process-era design decision. The pre-wedge five-path design is preserved here as the starting point for that future conversation. + +## §5 The investigation lifecycle (project-bounded) + +Within any one Improvement Project, the investigation traces this lifecycle: + +1. **Frame.** Author / inherit the canonical map. Set CTQ specs. Identify the outcome measure(s). (V1: this is the Process tab Edit mode + Charter; Process: same, with the Hub's canonical map as starting point.) +2. **Scout.** Read Current Process State at L1, identify where to investigate. (V1: per-project state; Process: cadence-driven Current Process State from PMS.) +3. **Investigate.** L3 mechanism work — Hypotheses, Findings, factor analysis on the Investigation Wall + Evidence Map. +4. **Improve.** Action authoring + tracking. Quick Actions or improvement-project-scoped change packages. +5. **Sustain.** Did it work? Schedule cadence to verify it stays so. + +This lifecycle is **shared across V1 and Process**. The wrapping context differs (V1: project as primary; Process: project nested under a Hub on a cadence-review surface), but the methodology is identical. + +## §6 Multi-level navigation as canvas pan/zoom + +The three levels are **expressed as pan/zoom** on the canvas, not as a separate picker. ADR-074 locked this — the canvas is the viewport surface; level changes happen via pan/zoom; owner-surface components render at each level. + +- L1 outcome view (zoom out): outcome distribution + Cpk vs spec + drift + time series. +- L2 process flow view (zoom out → middle): full process map with step cards, mini-charts on steps, state badges. +- L3 focal step view (zoom in): focal step detail + Evidence Map / Wall mirror for that step's investigation. + +ADR-074 also locked the boundary policy: **owner surfaces own their level**. The Investigation Wall owns L3 mechanism work; the canvas embeds the Wall at L3 rather than reimplementing hypothesis-card rendering. SCOUT (multi-level dashboard) owns L1; the canvas embeds the L1 dashboard at L1. The architecture protects against the "every surface becomes a dashboard" failure mode. + +This is shared across V1 and Process. In Process the canvas pan/zoom traverses an additional outer level (Hub portfolio above L1) and additional inner levels (recursive sub-flows below L2 — Drill C per [hub-portfolios.md §4.3](hub-portfolios.md)). + +## §7 The locality rule and the canvas's role + +The methodology floor is the **locality rule**: capability indices computed against different specs cannot be combined arithmetically. The canvas's branch / join + context-propagation model honors the locality rule structurally: + +- **Branch.** When a parallel sub-step diverges from upstream, downstream analysis automatically groups by upstream origin. +- **Join.** When parallel sub-steps converge, the joined-into step's analysis is automatically grouped BY upstream origin. ADR-073 enforced structurally — context follows the path. + +This means **the user cannot accidentally roll up across heterogeneous specs** by navigating the canvas. The default visualization at every join is per-origin distribution; no `meanCpkAcrossPaths()` exists. + +In Process, the locality rule extends to the Hub-of-hubs view — child Hubs render side-by-side; the parent never produces a single statistical metric across them. The cross-Hub context filter chip strip is a parameter that propagates to each child Hub's local computation, not an aggregation. + +## §8 Cross-references + +- The canonical statement of the three levels is in [`docs/01-vision/methodology.md`](../methodology.md) lines 76-100 (the original methodology doc, pre-wedge). +- The multi-level surface architecture (how the levels become navigable in software) is in [Multi-level SCOUT design](../../superpowers/specs/2026-04-29-multi-level-scout-design.md). +- The level × owner-surface boundary policy is [ADR-074](../../07-decisions/adr-074-scout-level-spanning-surface-boundary-policy.md). +- The locality-rule + structural-absence enforcement is [ADR-073](../../07-decisions/adr-073-no-statistical-rollup-across-heterogeneous-units.md). +- The PMS layer that operationalizes the methodology at cadence is [measurement-system.md](measurement-system.md). +- The persona-aware default landings per level live in [four-personas.md §5](four-personas.md). From 626917dedac268287abf280f727a59b8356fcd2f Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:48:22 +0300 Subject: [PATCH 07/10] =?UTF-8?q?docs(wedge-future):=20variscout-process/p?= =?UTF-8?q?ipelines.md=20=E2=80=94=20auto-ingestion=20+=20multi-source=20p?= =?UTF-8?q?rofile?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Auto-ingestion as the 'automated data' half of process ownership. Evidence Source / Data Profile / Snapshot / Profile Application data model (partly shipped in V1). Three timescales of cadence-driven refresh. Customer-tenant ingestion + rollups architecture honoring ADR-059 browser-only processing. Multi-source profile join at Hub scale. Non-goals: no ERP integration, no live alarms, no agent-eval product, no replacement of deterministic stats engine. --- docs/01-vision/variscout-process/pipelines.md | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 docs/01-vision/variscout-process/pipelines.md diff --git a/docs/01-vision/variscout-process/pipelines.md b/docs/01-vision/variscout-process/pipelines.md new file mode 100644 index 000000000..4a087ebd7 --- /dev/null +++ b/docs/01-vision/variscout-process/pipelines.md @@ -0,0 +1,172 @@ +--- +title: 'Pipelines — auto-ingestion, multi-source profile join, scheduled refresh' +audience: [product, engineer, designer] +category: strategy +status: named-future +last-reviewed: 2026-05-17 +parent: docs/01-vision/variscout-process/index.md +related: + - docs/superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md + - docs/superpowers/specs/2026-04-26-agent-review-log-process-hub-design.md + - docs/superpowers/specs/2026-05-03-variscout-vision-design.md + - docs/superpowers/specs/2026-05-16-wedge-architecture-design.md +--- + +# Pipelines — auto-ingestion, multi-source profile join, scheduled refresh + +> **Status: named-future capture.** Auto-ingestion is the "automated data" half of process ownership — the substrate that makes recurring evidence operationally cheap. V1 ships with manual paste + file upload only; sensor / SCADA / ERP feeds, scheduled refresh, and multi-source profile join at Hub scale are deferred to Process. The Evidence Source data model exists in V1 today as a partial implementation slice. + +## §1 Why Process needs auto-ingestion + +V1's data path is **manual**: the Specialist pastes data, uploads a CSV, or starts from a sample dataset. This works for V1's wedge because the Specialist controls when data enters the product — they paste before they analyze, the rhythm matches their workflow. + +Process Owners operate differently. They don't paste data when they want to analyze; they need the data to **already be there** when they open the product at cadence. A Process Owner who has to ask the data team for an extract every Monday morning is not in a cadence loop — they're in an interruption loop. The Process tab opens, Current Process State is current, decisions surface — or it doesn't, and the product fails its persona's job. + +Auto-ingestion closes the loop. The Evidence Source data model + Data Profile adapter + Snapshot history gives Process Owners a Hub whose data refreshes on a cadence schedule without their intervention. + +This is the canonical V1-vs-Process line for ingestion: + +- **V1**: manual paste + file upload only. Cadence is "when the analyst decides to look." +- **Process**: automated Evidence Sources at the cadence the process needs (shiftly / daily / weekly / hourly). Cadence is the process's natural rhythm. + +## §2 The data model (partly shipped in V1) + +The Evidence Source data model exists in V1 core as a first implementation slice. The objects in scope: + +| Type | Purpose | V1 status | +| --------------------------- | ------------------------------------------------------------------- | --------------------------------------------------- | +| **`EvidenceSource`** | User-facing Hub-level source of recurring evidence | Type exists; UI surface partial | +| **`DataProfileDefinition`** | Reusable deterministic adapter for a recognizable source-data shape | Type exists; one profile (Agent Review Log) defined | +| **`EvidenceSnapshot`** | One dated evidence package from an Evidence Source | Type exists; produced by V1 paste flow | +| **`ProfileApplication`** | Profile version + confirmed mapping used for one Snapshot | Type exists; not yet wired across all paths | + +What's named-future is the **operational layer above the data model** — scheduled refresh, sensor / SCADA / ERP source adapters, generalized Evidence Source authoring UI, automated profile recognition. + +## §3 Evidence Source — the user-facing concept + +An Evidence Source belongs to a Process Hub and is named in the language of the Process Owner: + +- "Line 4 fill-weight export" +- "Claims queue weekly extract" +- "Supplier intake defects" +- "Agent review log" +- "Verification audit sample" + +The Source answers **what the team will review on a cadence** and how that evidence feeds the Hub. It supports: + +- Cadence-board signals (Current Process State recomputation) +- Survey readiness checks (do we have enough recent evidence?) +- New or existing investigations (a paste flow can append to an Evidence Source's Snapshot history) +- Action verification (Sustainment-stage validation) +- Sustainment / control reviews (cadence-driven monitoring) +- Handoff to live systems when control moves outside VariScout (the export-and-archive path) + +**Boundary.** Evidence Sources do **not** make VariScout an integration platform. The customer's data team or an external consultant owns the extraction + transformation from source systems (SAP, MES, QMS, CRM, agent runtime, ACD, etc.) into documented contracts. VariScout owns the import contracts, validation, deterministic profile application, evidence snapshots, and the investigation workflow that uses them. + +This is **not** an ERP / MES / QMS / CRM / agent-runtime integration. It's a recurring data contract. + +## §4 Data Profile — the deterministic adapter + +A Data Profile is reusable deterministic logic for a recognizable data shape. It can: + +- Recommend mappings (which column → which canonical-map node) +- Derive analysis-ready columns (computed fields from raw) +- Validate required + optional fields +- Preserve source columns for inspection +- Carry version metadata so the Profile Application records which profile + which mapping was used per Snapshot + +Profiles are **implementation / design concepts, not primary user language**. Users set up Evidence Sources; VariScout may say that the source uses a profile when that helps explain a mapping, validation result, or migration. The user doesn't author profiles — VariScout (or a partner / consultant) does. + +**First concrete example: Agent Review Log Profile.** Adapts agent review exports (green / yellow / red decisions, confidence scores, audited correctness) into ordinary process evidence for safe-green-throughput investigations. The target metric is _"increase the share of green pass-through decisions while keeping false-green decisions below an agreed tolerance."_ See [Agent Review Log Profile spec](../../superpowers/specs/2026-04-26-agent-review-log-process-hub-design.md). + +Other Process-era profiles likely to ship: time-series fill measurements (the canonical manufacturing case), call-center queue exports, claims queue exports, supplier defect intake feeds, sensor stream rollups (computed by customer-tenant ingestion, not raw sensor data — see §6). + +## §5 Snapshot — the recurring evidence unit + +A Snapshot is one evidence package from a Source. It may arrive by paste, upload, append, customer-owned Blob sync, or a future customer-controlled export drop. + +**Snapshot timing is an improvement cadence**, not real-time: + +- Manual (analyst-triggered append) +- Shiftly (per shift, typically 8h) +- Daily +- Weekly +- Hourly (when that fits the process review need, and customer-tenant ingestion handles the volume) + +Snapshots are what Current Process State and the Hub cadence-board reason over: + +- What changed since the last Snapshot +- Whether requirements are being met +- Where variation / defects / wait / burden / unsafe outcomes concentrate +- Whether an action has enough post-change evidence for verification +- Whether a sustainment item still needs review in VariScout +- Whether the right response path is Quick Action, Focused Investigation, Charter, Sustainment, or Handoff + +The same cadence-board supports both **daily huddles** (latest Snapshot + open investigation metadata) and **weekly process reviews** (Snapshot history compare across the last N cycles). See [measurement-system.md §2](measurement-system.md) for the three-timescale shape. + +V1 has one Snapshot path live (the Agent Review Log Profile path). Broader daily / weekly comparison generalized across Source types is named-future. + +## §6 Customer-tenant ingestion + rollups (named-future) + +When Evidence Sources become **automated or hourly**, raw Snapshot files should not be the browser's primary read model. The named-future architecture: + +1. **Hourly or automated production-line data lands as immutable raw files in the customer-tenant Blob Storage.** (Per ADR-059: customer data stays in customer's tenant.) +2. **A narrow customer-tenant ingestion processor** writes Snapshot manifests + period rollups + validation reports back to Blob. +3. **Process Hub reads rollups first**, raw only on explicit drill-down. + +This keeps the browser-only processing principle intact (ADR-059) while making hourly-cadence operations feasible. The processor lives in the customer's Azure tenant; VariScout provides the deterministic logic + manifests; the customer owns the compute. + +The logical Process Hub evidence namespace in Blob: + +``` +process-hubs/{hubId}/evidence-sources/{sourceId}/snapshots/{snapshotId}/... +``` + +This namespace holds snapshot files, profile application metadata, validation reports, and related attachments. The processor reads + writes to this namespace; the browser reads from it. + +V1 doesn't have this layer. V1 paste flow writes directly to the Hub blob (Azure) or IndexedDB (PWA). The customer-tenant ingestion architecture activates when Hub-level automation activates. + +## §7 Multi-source profile join + +A single canonical map can have **multiple Evidence Sources** contributing to it. The fill-line Hub's canonical map has steps `Fill`, `Cap`, `Label`, `Crown`. Three Evidence Sources feed it: + +- "Line 4 fill measurements" (sensor → daily Snapshot of `Fill_Weight`) +- "Cap torque audit" (manual measurement → weekly Snapshot of `Cap_Torque`) +- "Final inspection defects" (defect log → daily Snapshot of defect category counts) + +Each Source has its own Data Profile (the deterministic mapping from source-data shape to canonical-map columns). The Hub's Current Process State integrates across all three Sources — each Source contributes its own measures to the per-step Signal Cards. + +**Multi-source join logic.** The V1 framing-layer work (`MatchSummaryCard`, `EvidenceSourceSync`, per-source provenance, `archiveReplacedRows`, `RowProvenanceTag`) implements the join engine. In V1, the join operates per-project (one investigation's data may come from multiple Sources). In Process, the same engine operates **at Hub scope** — the Hub's accumulated multi-Source evidence join is Current Process State's substrate. + +The provenance shape (per ADR-077): `EvidenceSnapshot.origin`, `importedAt`, `rowTimestampRange` + sidecar `RowProvenanceTag` map. Process inherits this verbatim. + +## §8 What V1 explicitly defers + +The wedge spec §3.6.5 and §7 list the Process-only pieces of pipelines: + +- **Auto-ingestion / sensor feeds.** Re-ingestion in V1 uses the existing paste flow. Sensor / SCADA / ERP feeds defer to Process. +- **Multi-source provenance gating.** The framing-layer Slice 2/3 work stays in flight for V1 but is not a V1 blocker; basic re-paste suffices for V1's specialist scope. +- **Scheduled refresh.** No cadence-triggered Snapshot creation in V1. Process owns the scheduler. +- **Customer-tenant ingestion processor.** No automated Blob → Hub processor in V1. Process owns the customer-tenant compute architecture. +- **Generalized Evidence Source authoring UI.** V1 has the data model; the user-facing Source-setup UI generalized across Source types is Process-scope. + +What V1 keeps: the paste / file upload paths, the Snapshot data model, the per-source provenance logic, the framing-layer join engine, the Agent Review Log Profile (which V1 doesn't enable as a UI surface but which exists as a code artifact). + +## §9 Non-goals (across both V1 and Process) + +These are explicitly out of scope regardless of which product: + +- **No deep or custom ERP / MES / QMS / CRM / ACD / AI-platform / workflow integrations.** Customers' data teams own those. +- **No live alarms, runtime monitoring, shift-critical escalation, or operational uptime promise.** Process is cadence-shaped, not real-time. +- **No separate AI-evaluation product for agent logs.** Agent Review Log is one Evidence Source profile, not a product line. +- **No replacement of the deterministic stats engine as authority.** CoScout (AI) adds context; the engine remains authoritative across V1 and Process. + +These non-goals come from the Evidence Sources spec and persist into Process unchanged. + +## §10 Cross-references + +- The Evidence Source / Data Profile / Snapshot / Profile Application data model: [Evidence Sources and Data Profiles spec](../../superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md). +- The concrete first-profile example: [Agent Review Log Profile spec](../../superpowers/specs/2026-04-26-agent-review-log-process-hub-design.md). +- The customer-tenant ingestion architecture is sketched in [Customer-Tenant Ingestion And Rollups Concept](../../archive/specs/2026-04-29-customer-tenant-ingestion-rollups-concept.md) (archived; will be revived in Process activation). +- The PMS layer that consumes pipeline data: [measurement-system.md](measurement-system.md). +- The Hub-scope multi-Source join that operates on pipeline outputs: [hub-portfolios.md §6](hub-portfolios.md). From f16bdd679545dea9dfef8258dc14e183207c9728 Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:48:52 +0300 Subject: [PATCH 08/10] =?UTF-8?q?docs(wedge-future):=20variscout-process/m?= =?UTF-8?q?onitoring.md=20=E2=80=94=20drift=20detection=20+=20process-owne?= =?UTF-8?q?r=20views?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Process-owner monitoring as the 'ongoing watching' half of process ownership. Six drift types (capability / distribution shift / out-of-control / spec breach / throughput / defect rate). Process Owner monitoring views (State mode decisions queue + Current State + Process map + In-flight references). Multi-Hub portfolio shape. Alert routing per persona+surface. Sustained-improvement durability monitoring extends ADR-080 from project-bounded to Hub-persistent. Cadence-shaped, not real-time. NOT a SCADA/MES replacement. --- .../01-vision/variscout-process/monitoring.md | 182 ++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 docs/01-vision/variscout-process/monitoring.md diff --git a/docs/01-vision/variscout-process/monitoring.md b/docs/01-vision/variscout-process/monitoring.md new file mode 100644 index 000000000..70106dd34 --- /dev/null +++ b/docs/01-vision/variscout-process/monitoring.md @@ -0,0 +1,182 @@ +--- +title: 'Monitoring — drift detection, alerts, process-owner views' +audience: [product, designer, engineer, quality-manager] +category: strategy +status: named-future +last-reviewed: 2026-05-17 +parent: docs/01-vision/variscout-process/index.md +related: + - docs/superpowers/specs/2026-05-03-variscout-vision-design.md + - docs/superpowers/specs/2026-05-14-variscout-coherence-design.md + - docs/superpowers/specs/2026-05-16-wedge-architecture-design.md + - docs/07-decisions/adr-080-sustainment-auto-fire-pattern.md +--- + +# Monitoring — drift detection, alerts, process-owner views + +> **Status: named-future capture.** Process-owner monitoring is the "ongoing watching" half of process ownership — drift detection, alert routing, capability snapshots over time, decisions queue at cadence. The V1 wedge defers monitoring as a process-owner concept. V1 keeps Sustainment auto-fire (ADR-080) which is the only V1 monitoring shape; everything else is Process. + +## §1 What monitoring is, and what it isn't + +Monitoring in Process is **cadence-shaped, not real-time**. It's the disciplined recurring read of Current Process State that surfaces decisions to the Process Owner persona on a daily / weekly rhythm. It is not: + +- **A real-time alarm runtime.** SCADA, MES, and operational monitoring systems own real-time alarming. Process integrates with them as upstream Evidence Sources, not as a replacement. +- **A shift-critical escalation tool.** When something breaks the line, the operations team uses their existing escalation tooling. Process surfaces the post-event analysis at cadence; it doesn't replace the incident-response stack. +- **An uptime / SLA monitoring product.** APM and reliability tooling own that. Process is process-improvement-shaped, not infrastructure-shaped. + +What monitoring IS in Process: + +- **Drift detection** at cadence — has any measure's distribution shifted in a way that warrants attention? +- **Alert routing** — when drift fires, who gets the prompt and at what surface? +- **Capability snapshots over time** — how has the process's capability evolved across snapshot cycles? +- **Decisions queue** — the surface where drift signals + cadence prompts + signoffs surface as actionable items for the Process Owner. +- **Sustainment cadence** — verifying that completed improvements stay sustained at the cadence the project closed at. + +## §2 Drift detection + +Drift detection compares the **latest Snapshot's distribution** to the **prior reference window** for each measure. The detection answers: _"is what we see different from what we expected?"_ (the universal lens, per [methodology.md §3.3](methodology.md)). + +| Drift type | What it detects | Surface | +| --------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------- | +| **Capability drift** | Cpk has declined materially vs prior reference window | Process tab decisions queue; routed to Process Owner | +| **Distribution shift** | Mean or σ has shifted (with sample-size honesty) | Signal Card on relevant measure; visible during cadence review | +| **Out-of-control signal** | Recent points violate Western Electric / Nelson rules on the i-chart for the measure | Process tab decisions queue; severity-flagged | +| **Spec breach** | Recent points breach USL or LSL | Process tab decisions queue; immediate-attention severity | +| **Throughput / cycle-time drift** | Step output rate, FPY, or cycle time has declined | Process tab decisions queue; routed to Process Owner | +| **Defect rate increase** | Defect rate per category has increased materially | Process tab decisions queue; routed to Process Owner | + +Each drift type carries: + +- A reference window (the "expected" baseline) +- A latest window (the "observed" reality) +- A statistical test or rule that triggered the detection +- A response-path suggestion (Investigate / Quick Action / Charter / Sustainment) + +**Sample-size honesty applied.** Drift detection respects the Watson invariants ([methodology.md §3.4](methodology.md)). A drift signal on a measure with n<10 is **suppressed**; the Signal Card shows "needs evidence" instead. A drift signal on n<30 is **badged "trust pending"**. Both prevent the false-positive flood that would otherwise undermine the Process Owner's trust in the queue. + +## §3 Process Owner monitoring views + +The Process Owner's daily / weekly artifact is the **Process tab in State mode** ([four-personas.md §2.1](four-personas.md)). The State mode surfaces three sections in attention order: + +### §3.1 Needs your decision (decisions queue) + +Primary attention; indigo-accent cards. Items requiring the Process Owner's input across their assigned Hubs: + +- Drift escalations (capability degradation, out-of-control signals, spec breaches) +- Sustainment cadence prompts (project ready for "did it work?" verification per ADR-080 auto-fire) +- Charter signoff requests (Specialists requesting new project authorization) +- Cross-persona handoffs (Process Engineer flagging a mechanism finding for Process Owner review) +- Pending measurement plans on Hypotheses where the Process Owner is the consultative role + +Each queue item carries a response-path CTA. Clicking the CTA lands the Process Owner in the workspace they need (Charter form, Sustainment closure view, Investigation Wall, etc.). + +### §3.2 Current state + +Outcome panel + Cpk + drift indicators per assigned Hub. The L1 outcome view rendered at portfolio shape — small per-Hub miniatures if the Process Owner owns multiple Hubs, full L1 if they own one. + +This is the "scan" surface — the Process Owner reads it for context, not for action. The decisions queue is the action surface. + +### §3.3 Process map + +The L2 process flow view (canonical map with state badges per step). State badges encode: + +- Capability status (target met / trust pending / below target / breach) +- Drift indicator (none / drifting / out-of-control) +- In-flight investigation count (which steps have active Hypotheses?) + +Clicking a step badge drills to L3 focal step detail. The Process Owner uses this to read which steps are healthy and which warrant attention — without entering an investigation. + +### §3.4 In-flight references + +Read-only links to current Improvement Projects, recent actions, open investigations, recent Findings. Compact badge format; not full cards. The full workspaces live in the relevant tabs (Project tab, Improve tab, Investigation tab). + +## §4 Hub-overview monitoring (multi-Hub Process Owner) + +When a Process Owner is assigned multiple Hubs, their Process tab landing is a **portfolio shape** rather than a single-Hub State mode. The portfolio shape renders: + +- Per-Hub miniature L1 outcome panel +- Per-Hub drift indicator +- Cross-Hub decisions queue (queue items aggregated across all assigned Hubs) +- Hub-level Sustainment cadence prompts + +The cross-Hub aggregation honors ADR-073: each Hub's metrics compute locally; the portfolio renders them adjacent; no `meanCpkAcrossHubs()` exists. The portfolio is **visual aggregation only**. + +A Process Owner with five Hubs sees five miniatures + a consolidated decisions queue. They route from the queue to the relevant Hub's full State mode when they need to act. The portfolio is the orchestration layer; the State mode is the workspace. + +## §5 Alert routing + +Alerts route to **personas + surfaces**, not to email lists. The default routing matrix: + +| Signal type | Primary persona | Surface | +| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| Capability drift on outcome measure | Process Owner | Decisions queue | +| Capability drift on in-process measure | Process Owner | Decisions queue, plus cross-reference to Process Engineer for mechanism review | +| Out-of-control signal | Process Owner | Decisions queue (severity-flagged) | +| Spec breach | Process Owner | Decisions queue (immediate-attention severity) | +| Sustainment cadence prompt | Project Lead (Specialist) | Inbox + decisions queue | +| Charter signoff request | Sponsor (Leader) | Decisions queue (Leader's portfolio overview) | +| Cross-persona handoff | Target persona | Decisions queue + Inbox | +| Survey-readiness failure | Specialist (where Specialist is on the affected project) or Process Engineer (where measure lifecycle is the concern) | Inbox | + +**Off-product notification** is optional and per-tenant configurable: an EngagementEvent webhook fires to Microsoft Teams / Power Automate / Slack when a signal arrives. The in-app surface is the source of truth; the off-product notification is a redirect. + +## §6 Capability snapshots over time + +The Hub's capability is tracked **across Snapshots**. The capability trend is a first-class read: + +- Per-step Cpk per Snapshot cycle (timeline) +- Distribution of per-(step × context) Cpks per Snapshot (timeline of distributions, not means) +- Capability delta vs prior cycle (rolling) +- Capability delta vs a marked baseline (the snapshot when an Improvement Project closed Sustainment — "are we still where we ended up?") + +V1 ships per-snapshot capability computation. **What's named-future**: the timeline view that renders capability evolution across the Hub's full Snapshot history, the per-baseline delta view, and the auto-fire Sustainment trigger that fires when capability drifts below a closed project's baseline. + +The ADR-080 Sustainment auto-fire pattern is the V1 piece that survives — when a project closes Sustainment with a capability commitment, the cadence-triggered re-check at the project's scheduled interval fires automatically. Process generalizes this from project-bounded to Hub-persistent. + +## §7 Sustainment monitoring + +Sustainment in Process is **continuous**, not bounded by project lifecycle. When a project closes Sustainment, the improvement's expected capability becomes part of the Hub's PMS — a stable measure with a target and a cadence-driven verification schedule. + +The Sustainment monitoring view per Hub: + +- List of completed improvements with their committed capability baselines +- Current capability per improvement (latest Snapshot) +- Drift status vs baseline (sustained / drifting / regressed) +- Last verification timestamp + next scheduled verification + +When a sustained improvement starts drifting, the Process Owner gets a decisions-queue item: "Improvement X is regressing — investigate?" Response paths from there: Investigate (new project), Quick Action (small fix), or Re-Charter (re-open the original project for follow-up). + +This is what makes Process improvements **durable** rather than one-shot. V1 ships the Sustainment stage; the cross-project durability monitoring is Process. + +## §8 What V1 explicitly defers + +Per the wedge spec §7 and §10 deferrals: + +- **Process Owner-shaped cadence monitoring dashboard** — the State-mode-only Hub overview surface (separate from per-project Process tab) is Process scope. +- **Persona-aware Home variants** — V1 ships one Home shape (Specialist); Process Owner's portfolio-shape default landing is Process. +- **Hub-of-hubs portfolio overview** — [hub-portfolios.md §3](hub-portfolios.md). Leader's primary landing. +- **Cross-Hub decisions queue aggregation** — Process Owner with multiple Hubs. +- **Off-product notification webhook (EngagementEvent → Teams / Power Automate / Slack)** — designed; not implemented. +- **Sustained-improvement durability monitoring** — V1 ships Sustainment as project-bounded; Process makes it Hub-persistent. + +What V1 keeps: the ADR-080 Sustainment auto-fire pattern (project-bounded), the existing drift detection at the per-project scope (computed when the Specialist runs analysis), and the basic capability + i-chart rules that drift detection would consume. + +## §9 Why this retired from V1 + +The wedge pivot collapsed monitoring because: + +1. **Monitoring is a process-owner concept.** V1's single Specialist persona doesn't have a monitoring job — they have an investigation job. Specialists don't open VariScout to scan; they open it to analyze. +2. **The cadence layer requires PMS.** Without the Process Measurement System ([measurement-system.md](measurement-system.md)), there's no cadence to monitor on; drift detection has nothing to compare against beyond the Specialist's most recent manual paste. +3. **Alert routing requires the persona model.** Without 4 personas, there's no routing problem — everything goes to the Specialist. The routing decisions (who sees what) only matter when more than one persona is in the product. +4. **Scope discipline.** V1 needs to ship as the smallest defensible anatomy. Monitoring is a large surface area (multiple views, multiple persona routes, drift-detection engine integration); shipping it before V1 validates would dilute the wedge. + +Monitoring activates in Process when the four-persona model + PMS layer + auto-ingestion are all in place — they're a prerequisite set, not independent capabilities. Activation order matters: introduce Process Owner persona first ([four-personas.md §9](four-personas.md)), then PMS, then the Hub-overview surface, then drift detection on top. + +## §10 Cross-references + +- The ADR-080 Sustainment auto-fire pattern (the V1 surviving piece): [`docs/07-decisions/adr-080-sustainment-auto-fire-pattern.md`](../../07-decisions/adr-080-sustainment-auto-fire-pattern.md). +- The decisions-queue and State-mode design that monitoring populates: [Wedge spec §3.3.2](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) (the V1 State-mode shape that Process expands). +- The persona × surface routing that determines who sees which alert: [four-personas.md](four-personas.md). +- The PMS layer that produces Current Process State for drift detection to read: [measurement-system.md](measurement-system.md). +- The Hub-of-hubs portfolio overview that the Leader persona's monitoring view renders: [hub-portfolios.md §3](hub-portfolios.md). +- The Coherence persona-aware State-mode design that originally specified Process Owner monitoring: [Coherence spec §4](../../superpowers/specs/2026-05-14-variscout-coherence-design.md). From 089b5a66901c1b348fb8c5924b90846f6a0d75c6 Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:49:20 +0300 Subject: [PATCH 09/10] docs(wedge): decision-log inbound link to variscout-process/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Single inbound link from item #8 of the 2026-05-16 wedge entry to the new VariScout Process named-future directory. This is the only discovery breadcrumb — Phase A canonical anchors (positioning, business-bible, roadmap, llms.txt, OVERVIEW, USER-JOURNEYS) stay clean of Process references per the design. Satisfies the docs workflow inbound-link requirement (new docs need >=1 inbound link) for the entire variscout-process/ directory; internal cross-links between the 8 files satisfy the rest. --- docs/decision-log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decision-log.md b/docs/decision-log.md index dc0609e94..746f96937 100644 --- a/docs/decision-log.md +++ b/docs/decision-log.md @@ -26,7 +26,7 @@ When in doubt: capture, don't invent. Record the decision; link to its source ar Decisions we keep relitigating. Each entry: short statement, rationale, closing artifact, date pinned. -- **2026-05-16 — Wedge pivot: single-product VariScout for improvement specialists (€99/mo, 6-tab nav, project-membership ACLs).** After an 8-round strategic brainstorm questioning whether VariScout was trying to be too many things at once (Hub + Project containers, 4 personas, tier-gating across 28 files, multi-source pipeline plans, process-owner monitoring concepts), the conversation converged on splitting VariScout into **two products on a roadmap**: ship the wedge first (project tool for improvement specialists), defer the platform (process ownership, auto pipelines, Hub portfolios, 4 personas) to a future separate product called **VariScout Process**. V1 (this pivot) anatomy: (1) **6 tabs in workflow order** — `[Home] [Projects] [Process] [Analyze] [Investigation] [Report]` — Improve tab removed as top-level; becomes a stage inside Projects detail; supersedes the Coherence §4 / Projects-tab-design D1 7-tab nav and Coherence's verb/noun grouping rationale (workflow-order grouping is stronger for the wedge's single persona). (2) **Projects detail = 4 stages** — `Charter / Approach / Improve / Sustainment` (Handoff folds into Sustainment closure as "did it work? + close"); supersedes Projects-tab-design D-series stage list (Sustainment+Handoff → Improve+Sustainment). (3) **Improve stage UI = simple action tracker by default**; PDCA workbench + What-If accessible via an "Advanced" toggle (progressive disclosure, not parallel modes). What-If may re-emerge in Analyze later; idea board / action conversion retire. (4) **3 canvas response paths** at V1 (Investigate, Quick Action, Charter); Sustainment auto-fires per ADR-080; Handoff path deleted everywhere. (5) **Persona model collapses to one — Specialist** — `personaRole` routing deleted from V1; Coherence Session A's 4-persona model migrates to VariScout Process. Member-roles inside projects (Lead / Member / Reviewer) replace persona routing. (6) **Per-project membership ACLs** — Project Lead invites org users _per project_ (not tenant-wide); cross-Azure-AD-tenant invites explicitly out of V1 scope (privacy boundary as feature, not bug); ACL data model: `ProjectMember`, `Invitation`, role enum. (7) **Pricing: single €99/month SKU, Azure tenant-wide, unlimited org users + projects**; supersedes ADR-033's €79/€199 tier split; preserves ADR-033 H6 hypothesis ("per-deployment beats per-seat") — €99 is still per-deployment. Tier-gating logic (~28 files using `isPaidTier()` / `hasTeamFeatures()`) mostly retires; project-membership ACL checks replace where access-gating remains useful. (8) **VariScout Process** named-future for process-ownership platform features (Hub portfolios, 4 personas, auto pipelines, multi-source ingestion). Not announced in V1 marketing; mentioned only when customers ask about enterprise use cases. (9) **Positioning unchanged**: "Structured investigation for process improvement" — V1 delivers the whole sentence for one project lead and their invited team. (10) **Three preconditions before engineering commits**: migration math (30-min financial sensitivity on €79→€99 + €199→€99), Azure AD invitation constraint accepted as feature (confirms cross-org collab is out of V1 ICP), one customer validation conversation (30-min pitch confirms "yes that's the product I want"). (11) **Holistic doc cleanup (~500 docs)** sequenced as Audit → Triage → Apply (Phase C), with canonical anchor docs (OVERVIEW, USER-JOURNEYS, DATA-FLOW, positioning, business-bible, tier-philosophy, roadmap, decision-log, root CLAUDE.md, llms.txt) updated as Phase A before engineering; per-surface amendments as Phase B during engineering; archive over delete to preserve institutional knowledge per `feedback_consolidation_replace_not_umbrella` + `feedback_close_threads_to_done`. (12) **Recent week's shipped work (PRs #172–#181) is mostly wedge-aligned** — already project-centric. Persona-routing hooks need de-personalization (small refactor, not rewrite); stage list rename (Sustainment+Handoff → Improve+Sustainment) is a medium refactor; Improve top-level tab deletion is the largest engineering item. Canonical artifacts: spec [`docs/superpowers/specs/2026-05-16-wedge-architecture-design.md`](superpowers/specs/2026-05-16-wedge-architecture-design.md) (canonical V1 design); ADR [`docs/07-decisions/adr-082-wedge-architecture.md`](07-decisions/adr-082-wedge-architecture.md); Phase A doc completion + Phase C execution spec [`docs/superpowers/specs/2026-05-17-wedge-phase-a-doc-completion-design.md`](superpowers/specs/2026-05-17-wedge-phase-a-doc-completion-design.md) (4-PR sequenced execution: Phase A → C-AMEND → C-ARCHIVE → C-DELETE; price amended €99 → €120; vocabulary "wedge" retired from customer-facing docs in favor of "VariScout" + "VariScout Process"). Supersession markers added to ADR-007, ADR-033, Coherence design spec, Projects-tab design spec. Brainstorm captured in plan file `~/.claude/plans/i-am-wondering-that-smooth-narwhal.md`. _Pinned 2026-05-16; amended 2026-05-17 with Phase A/C execution spec link._ +- **2026-05-16 — Wedge pivot: single-product VariScout for improvement specialists (€99/mo, 6-tab nav, project-membership ACLs).** After an 8-round strategic brainstorm questioning whether VariScout was trying to be too many things at once (Hub + Project containers, 4 personas, tier-gating across 28 files, multi-source pipeline plans, process-owner monitoring concepts), the conversation converged on splitting VariScout into **two products on a roadmap**: ship the wedge first (project tool for improvement specialists), defer the platform (process ownership, auto pipelines, Hub portfolios, 4 personas) to a future separate product called **VariScout Process**. V1 (this pivot) anatomy: (1) **6 tabs in workflow order** — `[Home] [Projects] [Process] [Analyze] [Investigation] [Report]` — Improve tab removed as top-level; becomes a stage inside Projects detail; supersedes the Coherence §4 / Projects-tab-design D1 7-tab nav and Coherence's verb/noun grouping rationale (workflow-order grouping is stronger for the wedge's single persona). (2) **Projects detail = 4 stages** — `Charter / Approach / Improve / Sustainment` (Handoff folds into Sustainment closure as "did it work? + close"); supersedes Projects-tab-design D-series stage list (Sustainment+Handoff → Improve+Sustainment). (3) **Improve stage UI = simple action tracker by default**; PDCA workbench + What-If accessible via an "Advanced" toggle (progressive disclosure, not parallel modes). What-If may re-emerge in Analyze later; idea board / action conversion retire. (4) **3 canvas response paths** at V1 (Investigate, Quick Action, Charter); Sustainment auto-fires per ADR-080; Handoff path deleted everywhere. (5) **Persona model collapses to one — Specialist** — `personaRole` routing deleted from V1; Coherence Session A's 4-persona model migrates to VariScout Process. Member-roles inside projects (Lead / Member / Reviewer) replace persona routing. (6) **Per-project membership ACLs** — Project Lead invites org users _per project_ (not tenant-wide); cross-Azure-AD-tenant invites explicitly out of V1 scope (privacy boundary as feature, not bug); ACL data model: `ProjectMember`, `Invitation`, role enum. (7) **Pricing: single €99/month SKU, Azure tenant-wide, unlimited org users + projects**; supersedes ADR-033's €79/€199 tier split; preserves ADR-033 H6 hypothesis ("per-deployment beats per-seat") — €99 is still per-deployment. Tier-gating logic (~28 files using `isPaidTier()` / `hasTeamFeatures()`) mostly retires; project-membership ACL checks replace where access-gating remains useful. (8) **VariScout Process** named-future for process-ownership platform features (Hub portfolios, 4 personas, auto pipelines, multi-source ingestion). Not announced in V1 marketing; mentioned only when customers ask about enterprise use cases. Design heritage preserved at [`docs/01-vision/variscout-process/`](01-vision/variscout-process/index.md) — multi-file capture of Process scope (V1-vs-Process scope-line, 4-persona model, Hub portfolios, Process Measurement System, three-level methodology, auto-pipelines, monitoring). Not agent-canonical; reachable only via this decision-log entry. (9) **Positioning unchanged**: "Structured investigation for process improvement" — V1 delivers the whole sentence for one project lead and their invited team. (10) **Three preconditions before engineering commits**: migration math (30-min financial sensitivity on €79→€99 + €199→€99), Azure AD invitation constraint accepted as feature (confirms cross-org collab is out of V1 ICP), one customer validation conversation (30-min pitch confirms "yes that's the product I want"). (11) **Holistic doc cleanup (~500 docs)** sequenced as Audit → Triage → Apply (Phase C), with canonical anchor docs (OVERVIEW, USER-JOURNEYS, DATA-FLOW, positioning, business-bible, tier-philosophy, roadmap, decision-log, root CLAUDE.md, llms.txt) updated as Phase A before engineering; per-surface amendments as Phase B during engineering; archive over delete to preserve institutional knowledge per `feedback_consolidation_replace_not_umbrella` + `feedback_close_threads_to_done`. (12) **Recent week's shipped work (PRs #172–#181) is mostly wedge-aligned** — already project-centric. Persona-routing hooks need de-personalization (small refactor, not rewrite); stage list rename (Sustainment+Handoff → Improve+Sustainment) is a medium refactor; Improve top-level tab deletion is the largest engineering item. Canonical artifacts: spec [`docs/superpowers/specs/2026-05-16-wedge-architecture-design.md`](superpowers/specs/2026-05-16-wedge-architecture-design.md) (canonical V1 design); ADR [`docs/07-decisions/adr-082-wedge-architecture.md`](07-decisions/adr-082-wedge-architecture.md); Phase A doc completion + Phase C execution spec [`docs/superpowers/specs/2026-05-17-wedge-phase-a-doc-completion-design.md`](superpowers/specs/2026-05-17-wedge-phase-a-doc-completion-design.md) (4-PR sequenced execution: Phase A → C-AMEND → C-ARCHIVE → C-DELETE; price amended €99 → €120; vocabulary "wedge" retired from customer-facing docs in favor of "VariScout" + "VariScout Process"). Supersession markers added to ADR-007, ADR-033, Coherence design spec, Projects-tab design spec. Brainstorm captured in plan file `~/.claude/plans/i-am-wondering-that-smooth-narwhal.md`. _Pinned 2026-05-16; amended 2026-05-17 with Phase A/C execution spec link._ **Amendment 2026-05-16 — PR-WV1-1 shipped (project membership foundation).** 17 commits on `feat/wedge-pr-wv1-1-project-membership` deliver the wedge §4 membership data model + ACL pattern: `ProjectRole` (`lead | member | sponsor`), `ProjectMember` + `Invitation` types extending `EntityBase`, `MembershipAction` reducer (ADD/UPDATE/REMOVE — patches use `Omit` per `feedback_action_patch_omit_lifecycle`), pure `canAccess(userId, members, action)` ACL function, Annotation-per-user `useProjectMembershipStore`, `InviteModal` + `MemberList` UI primitives with role-gated remove + per-row `aria-label`, Charter stage integration via additive `members[]` on `ImprovementProjectMetadata`, IPDetailPage ACL guard (non-member → `NoAccessRedirect`, Sponsor → `sponsor-report-panel` placeholder pointing to top-level Report nav), legacy `team[]` → wedge `members[]` `migrateTeamToMembers` function, Azure `useInvitationSync` Graph API stub, and PWA/Azure `ProjectsTabView` wired with `currentUserId` (PWA: `'analyst@local'` constant for single-user mode; Azure: `currentUser?.email` from EasyAuth) + `onMembersChange` callback mirroring the legacy `onTeamChange` `applyProjectPatch` pattern. Architecture review (system-architect, Opus) confirmed patterns generalize to PR-WV1-3's `MeasurementPlan` (reducer-over-domain-slice + pure ACL lookup table + sibling field on parent + migration helper). Three architectural decisions deferred to PR-WV1-2 with explicit ownership: (a) **`INVITATION_ACCEPT` / `INVITATION_REVOKE` action kinds** — `Invitation.status` + `acceptedAt` + `revokedAt` fields ship but no code mutates them yet; lifecycle action kinds land in PR-WV1-2 alongside Inbox simplification (Inbox surfaces pending invites; acceptance is the user action that transitions status → emits a `PROJECT_MEMBER_ADD` via composite reducer). (b) **`team[]` deprecation cutover** — `migrateTeamToMembers` exists in `packages/core/src/improvementProject/migration.ts` but is invoked nowhere; legacy `team[]` and wedge `members[]` coexist on the same `ImprovementProjectMetadata` for the migration window. PR-WV1-2 (stage rename + Improve fold-in) owns eager one-shot migration during `.vrs`/Dexie round-trip so legacy Sponsors (`team[].role === 'sponsor'`) don't get caught by the wedge ACL guard's `isExplicitlyExcluded` branch. (c) **Per-user persistence key on `useProjectMembershipStore`** — currently uses static `'variscout:projectMembership'` localStorage key (Zustand `persist` middleware). Shared-workstation users (rare in Azure ICP but possible) would bleed pending invites across sessions. Refactor to `useActiveIPStore`-style dynamic-key pattern (no `persist` middleware, manual `localStorage` with `variscout:projectMembership:{userId}` key + scope-keyed `Record` state) lands in PR-WV1-2 alongside auth-wiring refinement. (d) **Wire `canAccess` at consumer call sites** — final Opus code review noted that `IPDetailPage.tsx:126-134` inlines role lookup (`members.find(m => m.userId === currentUserId)?.role`) instead of calling `canAccess`, and `CharterOverview.tsx:129` gates the Invite button on `onInvite` prop presence rather than `canAccess(currentUserId, members, 'manage-membership')`. Today's behavior is correct because the only consumer is `IPDetailPage` itself, but PR-WV1-2's stage editors will need `canAccess('edit-charter')` / `canAccess('edit-improve')` per surface; converging the ACL truth table on one entry point at that point prevents drift. First commit of PR-WV1-2 should add §"Wire `canAccess` at consumer call sites" before stage editors land. Verification: 8/9 packages green via Turbo; `@variscout/ui` full suite stalls on the known unchanged-Canvas hang (per existing memory entries) — touched suites (`IPDetail`, `projects`, `InviteModal`, `MemberList`, `CharterOverview`) run green in isolation. `bash scripts/pr-ready-check.sh` deferred until pre-PR. _Amendment pinned 2026-05-16._ From f338cdcbcccee4b0181d8a7f0817fa1bd823fb6a Mon Sep 17 00:00:00 2001 From: Jukka-Matti Turtiainen Date: Sun, 17 May 2026 17:59:41 +0300 Subject: [PATCH 10/10] =?UTF-8?q?docs(wedge-future):=20vocabulary=20cleanu?= =?UTF-8?q?p=20=E2=80=94=20drop=20habitual=20'wedge'=20usage=20in=20Proces?= =?UTF-8?q?s=20capture=20body=20prose=20(preserve=20filename=20+=20histori?= =?UTF-8?q?cal=20refs)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- docs/01-vision/variscout-process/four-personas.md | 6 +++--- docs/01-vision/variscout-process/index.md | 8 ++++---- docs/01-vision/variscout-process/measurement-system.md | 2 +- docs/01-vision/variscout-process/methodology.md | 2 +- docs/01-vision/variscout-process/monitoring.md | 6 +++--- docs/01-vision/variscout-process/pipelines.md | 2 +- docs/01-vision/variscout-process/scope-line.md | 8 ++++---- 7 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/01-vision/variscout-process/four-personas.md b/docs/01-vision/variscout-process/four-personas.md index b83448c9f..d5a150ef5 100644 --- a/docs/01-vision/variscout-process/four-personas.md +++ b/docs/01-vision/variscout-process/four-personas.md @@ -27,7 +27,7 @@ Six of the original ten were buyer-evaluators, education-funnel students, tenant That left four product-user personas. The Coherence brainstorm tested "could it be three?" by considering whether SME-flavored work could be absorbed into the analyst persona. The conclusion was no: three of the four personas map cleanly to Constitution P7's three evidence types (Data / Gemba / Expert), and dropping the fourth left expert-evidence creation as "whoever happens to be in the RACI C role" — structurally vague. The four are minimal. -The Process Engineer persona was renamed from the pre-wedge "SME" label after the wedge pivot. The 2026-05-16 conversation surfaced that "SME" reads as a RACI role, not a persona — and the persona-vs-role confusion was the single most consequential terminology lock in Coherence Session A. **Process Engineer** is the canonical persona name in the named-future Process product. It captures the same role (expert input on artifacts; consulting on investigations from other Leads) while disambiguating from RACI. +The Process Engineer persona was renamed from the pre-wedge "SME" label after the V1 pivot. The 2026-05-16 conversation surfaced that "SME" reads as a RACI role, not a persona — and the persona-vs-role confusion was the single most consequential terminology lock in Coherence Session A. **Process Engineer** is the canonical persona name in the named-future Process product. It captures the same role (expert input on artifacts; consulting on investigations from other Leads) while disambiguating from RACI. ## §2 The four personas @@ -163,10 +163,10 @@ This pattern exists in V1's project membership model (Lead / Member / Sponsor on ## §8 Why this retired from V1 -The wedge pivot collapsed to one persona because: +The V1 pivot collapsed to one persona because: 1. **Single-buyer onramp.** The V1 ICP is the Specialist buying the tool for their team. Persona-aware routing requires the buyer to set up tenant-wide persona assignments, which is enterprise IT work — incompatible with a self-service Azure Marketplace deployment for a single specialist. -2. **Engineering scope.** Persona infrastructure (tenant-admin persona assignment UI, persona-aware default routing across every surface, persona-adaptive Home variants) is multi-PR engineering work. The wedge committed to ship V1 with the smallest defensible anatomy. +2. **Engineering scope.** Persona infrastructure (tenant-admin persona assignment UI, persona-aware default routing across every surface, persona-adaptive Home variants) is multi-PR engineering work. V1 committed to ship with the smallest defensible anatomy. 3. **Methodology purity.** With one persona, every surface serves the same primary verb (analyze + improve). Multiple personas multiply the design surface (every screen has 4× the UX variants); V1 deliberately accepts the design constraint that comes with one persona. The four-persona model migrates to Process intact. The infrastructure to support it (persona-aware routing, persona-adaptive Homes, RACI engagement-profile model, copy-density tiers) is Process scope, not V1. diff --git a/docs/01-vision/variscout-process/index.md b/docs/01-vision/variscout-process/index.md index fe132b475..7980e2e1c 100644 --- a/docs/01-vision/variscout-process/index.md +++ b/docs/01-vision/variscout-process/index.md @@ -16,11 +16,11 @@ related: # VariScout Process — named-future capture -> **Status: named-future.** This is preserved institutional knowledge, not a product commitment. VariScout Process is the second product on the two-product roadmap — gated on V1 (the wedge specialist tool) reaching ~500 customers. Nothing in this directory is in active development; nothing here ships under the V1 SKU; nothing here changes the V1 codebase. Read this when designing for V1 and a question surfaces that sounds like a process-owner / team / enterprise need — the answer is almost certainly here, and the answer is almost certainly "later, in Process." +> **Status: named-future.** This is preserved institutional knowledge, not a product commitment. VariScout Process is the second product on the two-product roadmap — gated on V1 (the specialist tool) reaching ~500 customers. Nothing in this directory is in active development; nothing here ships under the V1 SKU; nothing here changes the V1 codebase. Read this when designing for V1 and a question surfaces that sounds like a process-owner / team / enterprise need — the answer is almost certainly here, and the answer is almost certainly "later, in Process." ## §1 Why this directory exists -The 2026-05-16 wedge pivot was a deliberate narrowing. The pre-wedge design corpus (~10 specs, ~3000 lines, March–May 2026) had converged on a four-persona, multi-Hub, auto-pipeline, monitoring-shaped product. Validating it against the actual ICP — improvement specialists running structured investigations with their teams — revealed that the breadth was the problem, not the solution. The wedge collapsed the surface area: one persona (Specialist), one container (Project wrapping an internal Hub), one ingestion path (manual paste + file upload), one SKU (€120/mo Azure tenant-wide), one positioning sentence ("structured investigation for process improvement"). +The 2026-05-16 wedge pivot was a deliberate narrowing. The pre-wedge design corpus (~10 specs, ~3000 lines, March–May 2026) had converged on a four-persona, multi-Hub, auto-pipeline, monitoring-shaped product. Validating it against the actual ICP — improvement specialists running structured investigations with their teams — revealed that the breadth was the problem, not the solution. V1 collapsed the surface area: one persona (Specialist), one container (Project wrapping an internal Hub), one ingestion path (manual paste + file upload), one SKU (€120/mo Azure tenant-wide), one positioning sentence ("structured investigation for process improvement"). But the design work behind the breadth was not wrong. It was early. The wedge spec §7 named eight specific capabilities as deferred — not "coming soon inside V1" but "a separate product on the roadmap when V1 validates." That product is **VariScout Process**. @@ -49,7 +49,7 @@ VariScout Process activates when V1 reaches roughly **500 paying customers**. Th 2. **Engineering capacity for a second product.** Building Process while V1 still has known gaps (V2 measurement system additions, signoff workflows, multi-project coordination at specialist scope) starves both. 500 customers funds a second product team. 3. **Customer-pull evidence that process ownership is the next layer.** If specialist customers consistently ask for process-owner monitoring as their next purchase, the deferred design becomes a validated commitment. If they ask for something else, this capture stays preserved and the roadmap turns. -This is honest framing: VariScout Process is gated on V1 working. If V1 doesn't validate the wedge, the deferred design doesn't activate. Nothing in this directory entitles itself to a build slot. +This is honest framing: VariScout Process is gated on V1 working. If V1 doesn't validate, the deferred design doesn't activate. Nothing in this directory entitles itself to a build slot. ## §4 V1-vs-Process boundary — one-paragraph summary @@ -109,4 +109,4 @@ This sequence is not in any spec. It is a reading of which capabilities depend o --- -> Process is not coming soon. Process is preserved. The wedge is the bet; this directory is the long game. +> Process is not coming soon. Process is preserved. V1 is the bet; this directory is the long game. diff --git a/docs/01-vision/variscout-process/measurement-system.md b/docs/01-vision/variscout-process/measurement-system.md index 02777816e..d14832448 100644 --- a/docs/01-vision/variscout-process/measurement-system.md +++ b/docs/01-vision/variscout-process/measurement-system.md @@ -14,7 +14,7 @@ related: # Process Measurement System (PMS) — stable measures + cadence + Current Process State -> **Status: named-future capture.** PMS is the cadence-review substrate for the Process Owner persona. Stable measure definitions + Evidence Sources + Snapshots + Signal Cards + Survey readiness + cadence rules combine into the latest structured read of a process — **Current Process State**. The V1 wedge defers this surface explicitly; the engine pieces are partly shipped today, the cadence-review surface is named-future. +> **Status: named-future capture.** PMS is the cadence-review substrate for the Process Owner persona. Stable measure definitions + Evidence Sources + Snapshots + Signal Cards + Survey readiness + cadence rules combine into the latest structured read of a process — **Current Process State**. V1 defers this surface explicitly; the engine pieces are partly shipped today, the cadence-review surface is named-future. ## §1 What PMS is, and what it isn't diff --git a/docs/01-vision/variscout-process/methodology.md b/docs/01-vision/variscout-process/methodology.md index a5ca7d4a0..51f7f6687 100644 --- a/docs/01-vision/variscout-process/methodology.md +++ b/docs/01-vision/variscout-process/methodology.md @@ -101,7 +101,7 @@ The pre-wedge VariScout vision named five response paths for any current state o 4. Sustainment 5. Handoff -The V1 wedge reduced to **three canvas response paths** (Investigate, Quick Action, Charter), with Sustainment auto-firing per [ADR-080](../../07-decisions/adr-080-sustainment-auto-fire-pattern.md) and Handoff folded into Sustainment closure. +V1 reduced to **three canvas response paths** (Investigate, Quick Action, Charter), with Sustainment auto-firing per [ADR-080](../../07-decisions/adr-080-sustainment-auto-fire-pattern.md) and Handoff folded into Sustainment closure. **Process likely re-expands.** The original five-path framing serves multi-persona reality better than three. Specifically: diff --git a/docs/01-vision/variscout-process/monitoring.md b/docs/01-vision/variscout-process/monitoring.md index 70106dd34..8dc3f5d24 100644 --- a/docs/01-vision/variscout-process/monitoring.md +++ b/docs/01-vision/variscout-process/monitoring.md @@ -14,7 +14,7 @@ related: # Monitoring — drift detection, alerts, process-owner views -> **Status: named-future capture.** Process-owner monitoring is the "ongoing watching" half of process ownership — drift detection, alert routing, capability snapshots over time, decisions queue at cadence. The V1 wedge defers monitoring as a process-owner concept. V1 keeps Sustainment auto-fire (ADR-080) which is the only V1 monitoring shape; everything else is Process. +> **Status: named-future capture.** Process-owner monitoring is the "ongoing watching" half of process ownership — drift detection, alert routing, capability snapshots over time, decisions queue at cadence. V1 defers monitoring as a process-owner concept. V1 keeps Sustainment auto-fire (ADR-080) which is the only V1 monitoring shape; everything else is Process. ## §1 What monitoring is, and what it isn't @@ -163,12 +163,12 @@ What V1 keeps: the ADR-080 Sustainment auto-fire pattern (project-bounded), the ## §9 Why this retired from V1 -The wedge pivot collapsed monitoring because: +The V1 pivot collapsed monitoring because: 1. **Monitoring is a process-owner concept.** V1's single Specialist persona doesn't have a monitoring job — they have an investigation job. Specialists don't open VariScout to scan; they open it to analyze. 2. **The cadence layer requires PMS.** Without the Process Measurement System ([measurement-system.md](measurement-system.md)), there's no cadence to monitor on; drift detection has nothing to compare against beyond the Specialist's most recent manual paste. 3. **Alert routing requires the persona model.** Without 4 personas, there's no routing problem — everything goes to the Specialist. The routing decisions (who sees what) only matter when more than one persona is in the product. -4. **Scope discipline.** V1 needs to ship as the smallest defensible anatomy. Monitoring is a large surface area (multiple views, multiple persona routes, drift-detection engine integration); shipping it before V1 validates would dilute the wedge. +4. **Scope discipline.** V1 needs to ship as the smallest defensible anatomy. Monitoring is a large surface area (multiple views, multiple persona routes, drift-detection engine integration); shipping it before V1 validates would dilute V1's scope. Monitoring activates in Process when the four-persona model + PMS layer + auto-ingestion are all in place — they're a prerequisite set, not independent capabilities. Activation order matters: introduce Process Owner persona first ([four-personas.md §9](four-personas.md)), then PMS, then the Hub-overview surface, then drift detection on top. diff --git a/docs/01-vision/variscout-process/pipelines.md b/docs/01-vision/variscout-process/pipelines.md index 4a087ebd7..a28d2f5ef 100644 --- a/docs/01-vision/variscout-process/pipelines.md +++ b/docs/01-vision/variscout-process/pipelines.md @@ -18,7 +18,7 @@ related: ## §1 Why Process needs auto-ingestion -V1's data path is **manual**: the Specialist pastes data, uploads a CSV, or starts from a sample dataset. This works for V1's wedge because the Specialist controls when data enters the product — they paste before they analyze, the rhythm matches their workflow. +V1's data path is **manual**: the Specialist pastes data, uploads a CSV, or starts from a sample dataset. This works for V1 because the Specialist controls when data enters the product — they paste before they analyze, the rhythm matches their workflow. Process Owners operate differently. They don't paste data when they want to analyze; they need the data to **already be there** when they open the product at cadence. A Process Owner who has to ask the data team for an extract every Monday morning is not in a cadence loop — they're in an interruption loop. The Process tab opens, Current Process State is current, decisions surface — or it doesn't, and the product fails its persona's job. diff --git a/docs/01-vision/variscout-process/scope-line.md b/docs/01-vision/variscout-process/scope-line.md index 18e8b03de..395286dd5 100644 --- a/docs/01-vision/variscout-process/scope-line.md +++ b/docs/01-vision/variscout-process/scope-line.md @@ -18,9 +18,9 @@ related: ## §1 How to read this doc -V1 (the wedge specialist tool) ships today. VariScout Process is named-future. Most pre-wedge design work created **shared substrate** — code that ships in V1 but was originally designed for process-owner / multi-hub / enterprise scope. Drawing the line for each capability prevents two failure modes: +V1 (the specialist tool) ships today. VariScout Process is named-future. Most pre-wedge design work created **shared substrate** — code that ships in V1 but was originally designed for process-owner / multi-hub / enterprise scope. Drawing the line for each capability prevents two failure modes: -1. **Scope creep into V1.** A specialist asks "can I monitor capability across multiple processes?" — that sounds reasonable, but answering "yes" smuggles Process-scope behavior into V1 and breaks the wedge. +1. **Scope creep into V1.** A specialist asks "can I monitor capability across multiple processes?" — that sounds reasonable, but answering "yes" smuggles Process-scope behavior into V1 and breaks the V1 scope. 2. **Throwing away shipped value.** When Process activates, the team will benefit from extending capabilities already coded rather than rebuilding from scratch. Knowing which V1 capabilities have Process-shaped headroom guides Phase 1 of Process activation. The table format below is the contract. For each capability: **V1 shape** (what ships today, at specialist scope) vs **Process shape** (what activates when Process activates). @@ -71,7 +71,7 @@ These are the capabilities that exist in V1 code today and have explicit Process ## §3 V1-only capabilities (Process inherits or transforms) -These capabilities are V1's wedge anatomy. They don't survive into Process unchanged. +These capabilities are V1's anatomy. They don't survive into Process unchanged. ### §3.1 Project as foundational unit @@ -120,4 +120,4 @@ V1 ships what one specialist needs to investigate one project with their invited Anything that smells like "ongoing watching," "multi-project orchestration," "persona-aware default behavior," "cross-Hub anything," or "automation that runs while no one is looking" is a Process feature. Anything that's "this specialist, this project, this evidence, this team I invited" is V1. -When the smell-test fails: **default to V1 deferral, not Process backport.** If specialists are asking for it inside V1, the wedge spec has likely already named the deferral path. Check [wedge spec §7 + §10](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) before adding. +When the smell-test fails: **default to V1 deferral, not Process backport.** If specialists are asking for it inside V1, the V1 architecture spec has likely already named the deferral path. Check [wedge spec §7 + §10](../../superpowers/specs/2026-05-16-wedge-architecture-design.md) before adding.