diff --git a/apps/azure/src/components/ProcessHubCadenceQuestions.tsx b/apps/azure/src/components/ProcessHubCadenceQuestions.tsx index 3f6b7577c..5132d1a2d 100644 --- a/apps/azure/src/components/ProcessHubCadenceQuestions.tsx +++ b/apps/azure/src/components/ProcessHubCadenceQuestions.tsx @@ -24,7 +24,7 @@ const ProcessHubCadenceQuestions: React.FC = ({
-

Cadence Questions

+

Process State Questions

diff --git a/apps/azure/src/components/ProcessHubCurrentStatePanel.tsx b/apps/azure/src/components/ProcessHubCurrentStatePanel.tsx new file mode 100644 index 000000000..f46ccc958 --- /dev/null +++ b/apps/azure/src/components/ProcessHubCurrentStatePanel.tsx @@ -0,0 +1,161 @@ +import React from 'react'; +import { Activity, Gauge, GitBranch, Layers3, ShieldCheck } from 'lucide-react'; +import type { + CurrentProcessState, + ProcessStateItem, + ProcessStateLens, + ProcessStateResponsePath, + ProcessStateSeverity, +} from '@variscout/core'; +import { formatChangeSignals, formatMetric } from './ProcessHubFormat'; + +interface ProcessHubCurrentStatePanelProps { + state: CurrentProcessState; +} + +const LENS_LABELS: Record = { + outcome: 'Outcome', + flow: 'Flow', + conversion: 'Conversion', + measurement: 'Measurement', + sustainment: 'Sustainment', +}; + +const RESPONSE_LABELS: Record = { + monitor: 'Monitor', + 'quick-action': 'Quick action', + 'focused-investigation': 'Focused investigation', + 'chartered-project': 'Chartered project', + 'measurement-system-work': 'Measurement system work', + 'sustainment-review': 'Sustainment review', + 'control-handoff': 'Control handoff', +}; + +const SEVERITY_LABELS: Record = { + red: 'Red', + amber: 'Amber', + neutral: 'Neutral', + green: 'Green', +}; + +const SEVERITY_CLASS: Record = { + red: 'border-rose-500/40 text-rose-400', + amber: 'border-amber-500/40 text-amber-400', + neutral: 'border-edge text-content-secondary', + green: 'border-emerald-500/40 text-emerald-400', +}; + +const LENS_ICONS: Record = { + outcome: , + flow: , + conversion: , + measurement: , + sustainment: , +}; + +const LENSES: ProcessStateLens[] = ['outcome', 'flow', 'conversion', 'measurement', 'sustainment']; + +const StateCountCard: React.FC<{ lens: ProcessStateLens; count: number }> = ({ lens, count }) => ( +
+
+ {LENS_ICONS[lens]} + {LENS_LABELS[lens]} +
+

+ {count} +

+
+); + +const formatStateDetail = (item: ProcessStateItem): string | null => { + const metric = item.metric; + if (metric?.cpk !== undefined && metric.cpkTarget !== undefined) { + return `Cpk ${formatMetric(metric.cpk)} vs target ${formatMetric(metric.cpkTarget)}`; + } + if (metric?.changeSignalCount !== undefined) { + return formatChangeSignals(metric.changeSignalCount); + } + if (metric?.variationPct !== undefined) { + return `${formatMetric(metric.variationPct)}% variation`; + } + if (item.count !== undefined) { + return formatMetric(item.count); + } + return item.detail ?? null; +}; + +const StateItemCard: React.FC<{ item: ProcessStateItem }> = ({ item }) => { + const detail = formatStateDetail(item); + + return ( +
+
+
+

+ {LENS_LABELS[item.lens]} +

+

{item.label}

+ {detail &&

{detail}

} +
+ + {SEVERITY_LABELS[item.severity]} + +
+

+ {RESPONSE_LABELS[item.responsePath]} +

+
+ ); +}; + +const ProcessHubCurrentStatePanel: React.FC = ({ state }) => { + const visibleItems = state.items.slice(0, 6); + const hiddenCount = Math.max(0, state.items.length - visibleItems.length); + + return ( +
+
+
+ +

Current Process State

+
+ + {SEVERITY_LABELS[state.overallSeverity]} + +
+ +
+ {LENSES.map(lens => ( + + ))} +
+ + {visibleItems.length > 0 ? ( +
+ {visibleItems.map(item => ( + + ))} + {hiddenCount > 0 && ( +

+ +{hiddenCount} more current-state items +

+ )} +
+ ) : ( +

+ No current process state signals yet +

+ )} +
+ ); +}; + +export default ProcessHubCurrentStatePanel; diff --git a/apps/azure/src/components/ProcessHubReviewPanel.tsx b/apps/azure/src/components/ProcessHubReviewPanel.tsx index 9d7b3ec00..b4224c267 100644 --- a/apps/azure/src/components/ProcessHubReviewPanel.tsx +++ b/apps/azure/src/components/ProcessHubReviewPanel.tsx @@ -1,9 +1,10 @@ import React from 'react'; import { Plus } from 'lucide-react'; -import { buildProcessHubCadence } from '@variscout/core'; +import { buildCurrentProcessState, buildProcessHubCadence } from '@variscout/core'; import type { ProcessHubInvestigation, ProcessHubRollup } from '@variscout/core'; import ProcessHubCadenceQuestions from './ProcessHubCadenceQuestions'; import ProcessHubCadenceQueues from './ProcessHubCadenceQueues'; +import ProcessHubCurrentStatePanel from './ProcessHubCurrentStatePanel'; import { formatLatestActivity } from './ProcessHubFormat'; interface ProcessHubReviewPanelProps { @@ -43,7 +44,8 @@ const ProcessHubReviewPanel: React.FC = ({ onRecordHandoff, }) => { const cadence = buildProcessHubCadence(rollup); - const headingId = `process-hub-review-${rollup.hub.id}`; + const currentState = buildCurrentProcessState(rollup, cadence); + const headingId = `process-hub-current-state-${rollup.hub.id}`; return (
= ({

- {rollup.hub.name} Cadence Review + {rollup.hub.name} Current Process State

-

Cadence Review Board

+

Process state review

{rollup.hub.processOwner?.displayName ? `Owner: ${rollup.hub.processOwner.displayName} · ` @@ -73,6 +75,8 @@ const ProcessHubReviewPanel: React.FC = ({

+ +
{ least one rational-subgroup axis.

- { + const setProcessContext = vi.fn(); + const setSpecs = vi.fn(); + return { + useProjectStore: vi.fn((selector: (s: unknown) => unknown) => + selector({ + rawData: [], + outcome: null, + specs: null, + setSpecs, + processContext: null, + setProcessContext, + }) + ), + }; +}); + +import FrameView from '../FrameView'; + +describe('FrameView (Azure)', () => { + it('renders LayeredProcessView with three bands', () => { + render(); + + expect(screen.getByTestId('layered-process-view')).toBeInTheDocument(); + expect(screen.getByTestId('band-outcome')).toBeInTheDocument(); + expect(screen.getByTestId('band-process-flow')).toBeInTheDocument(); + expect(screen.getByTestId('band-operations')).toBeInTheDocument(); + }); +}); diff --git a/apps/azure/src/pages/__tests__/Dashboard.processHub.test.tsx b/apps/azure/src/pages/__tests__/Dashboard.processHub.test.tsx index 8a7061c53..e4397774b 100644 --- a/apps/azure/src/pages/__tests__/Dashboard.processHub.test.tsx +++ b/apps/azure/src/pages/__tests__/Dashboard.processHub.test.tsx @@ -198,7 +198,7 @@ describe('Dashboard Process Hub home', () => { expect(screen.getByText('2 change signals')).toBeInTheDocument(); }); - it('renders an inline Hub Cadence Review panel for the selected hub and opens review items', async () => { + it('renders an inline Current Process State panel for the selected hub and opens review items', async () => { const onOpenProject = vi.fn(); mockListProjects.mockResolvedValue([ makeProject(), @@ -214,8 +214,13 @@ describe('Dashboard Process Hub home', () => { await screen.findByText('Line 4'); fireEvent.click(screen.getByLabelText('Open Line 4')); - const panel = await screen.findByRole('region', { name: 'Line 4 Cadence Review' }); - expect(within(panel).getByText('Cadence Questions')).toBeInTheDocument(); + const panel = await screen.findByRole('region', { name: 'Line 4 Current Process State' }); + expect(within(panel).getByText('Current Process State')).toBeInTheDocument(); + expect(within(panel).getByText('Capability below target')).toBeInTheDocument(); + expect(within(panel).getAllByText('Focused investigation').length).toBeGreaterThan(0); + expect(within(panel).getAllByText('Outcome').length).toBeGreaterThan(0); + expect(within(panel).getAllByText('Measurement').length).toBeGreaterThan(0); + expect(within(panel).getByText('Process State Questions')).toBeInTheDocument(); expect(within(panel).getByText('Are we meeting the requirement?')).toBeInTheDocument(); expect( within(panel).getByText('Fill weight must stay inside customer specs.') @@ -263,7 +268,7 @@ describe('Dashboard Process Hub home', () => { await screen.findByText('Line 4'); fireEvent.click(screen.getByLabelText('Open Line 4')); - const panel = await screen.findByRole('region', { name: 'Line 4 Cadence Review' }); + const panel = await screen.findByRole('region', { name: 'Line 4 Current Process State' }); expect(within(panel).getAllByText('Readiness').length).toBeGreaterThan(0); expect(within(panel).getAllByText('Frame missing process context 1').length).toBeGreaterThan(0); expect(within(panel).getByText('Complete process context')).toBeInTheDocument(); @@ -272,7 +277,7 @@ describe('Dashboard Process Hub home', () => { expect(within(panel).getByText('Map one customer-felt outcome.')).toBeInTheDocument(); }); - it('renders a cadence review board with snapshot metrics and truncated queues', async () => { + it('renders a current process state board with snapshot metrics and truncated queues', async () => { mockListProjects.mockResolvedValue([ makeProject(), makeVerificationProject(), @@ -303,8 +308,8 @@ describe('Dashboard Process Hub home', () => { await screen.findByText('Line 4'); fireEvent.click(screen.getByLabelText('Open Line 4')); - const panel = await screen.findByRole('region', { name: 'Line 4 Cadence Review' }); - expect(within(panel).getByText('Cadence Review Board')).toBeInTheDocument(); + const panel = await screen.findByRole('region', { name: 'Line 4 Current Process State' }); + expect(within(panel).getByText('Current Process State')).toBeInTheDocument(); expect(within(panel).getByText('Decision Queues')).toBeInTheDocument(); expect(within(panel).getByTestId('cadence-snapshot-active')).toHaveTextContent('7'); expect(within(panel).getByTestId('cadence-snapshot-readiness')).toHaveTextContent('7'); @@ -324,14 +329,14 @@ describe('Dashboard Process Hub home', () => { await screen.findByText('Line 4'); fireEvent.click(screen.getByLabelText('Open Line 4')); - await screen.findByRole('region', { name: 'Line 4 Cadence Review' }); + await screen.findByRole('region', { name: 'Line 4 Current Process State' }); fireEvent.change(screen.getByPlaceholderText('Search investigations...'), { target: { value: 'zzzz no matching project' }, }); expect(screen.getByLabelText('Open Line 4')).toBeInTheDocument(); - const panel = screen.getByRole('region', { name: 'Line 4 Cadence Review' }); + const panel = screen.getByRole('region', { name: 'Line 4 Current Process State' }); expect(within(panel).getByTestId('cadence-snapshot-active')).toHaveTextContent('1'); expect(screen.queryByTestId('project-card')).not.toBeInTheDocument(); }); @@ -347,7 +352,7 @@ describe('Dashboard Process Hub home', () => { await screen.findByText('Line 4'); fireEvent.click(screen.getByLabelText('Open Line 4')); - const panel = await screen.findByRole('region', { name: 'Line 4 Cadence Review' }); + const panel = await screen.findByRole('region', { name: 'Line 4 Current Process State' }); expect(within(panel).getByText('Daily huddle')).toBeInTheDocument(); expect(within(panel).getByText('Weekly process review')).toBeInTheDocument(); expect(within(panel).getByText('No latest signals yet')).toBeInTheDocument(); @@ -390,7 +395,7 @@ describe('Dashboard Process Hub home', () => { await screen.findByText('Line 4'); fireEvent.click(screen.getByLabelText('Open Line 4')); - const panel = await screen.findByRole('region', { name: 'Line 4 Cadence Review' }); + const panel = await screen.findByRole('region', { name: 'Line 4 Current Process State' }); const headings = within(panel) .getAllByRole('heading') .map(h => h.textContent?.trim()); diff --git a/apps/pwa/src/components/views/FrameView.tsx b/apps/pwa/src/components/views/FrameView.tsx index c0c0ba3eb..1c06966c9 100644 --- a/apps/pwa/src/components/views/FrameView.tsx +++ b/apps/pwa/src/components/views/FrameView.tsx @@ -1,13 +1,13 @@ /** * FrameView — PWA FRAME workspace (ADR-070). * - * Renders the `ProcessMapBase` component wired to `projectStore.processContext.processMap`, + * Renders the `LayeredProcessView` component wired to `projectStore.processContext.processMap`, * with live gap detection from `@variscout/core/frame`. The user builds the process map * (SIPOC spine + tributaries + ocean/CTS + hunches). V2+ will add CoScout drafting, * template libraries, and data-seeded skeletons — V1 is deterministic-only. */ import React from 'react'; -import { ProcessMapBase } from '@variscout/ui'; +import { LayeredProcessView } from '@variscout/ui'; import { useProjectStore } from '@variscout/stores'; import type { ProcessContext } from '@variscout/core'; import { detectGaps, type ProcessMap } from '@variscout/core/frame'; @@ -69,7 +69,7 @@ const FrameView: React.FC = () => { least one rational-subgroup axis.

- { + const setProcessContext = vi.fn(); + const setSpecs = vi.fn(); + return { + useProjectStore: vi.fn((selector: (s: unknown) => unknown) => + selector({ + rawData: [], + outcome: null, + specs: null, + setSpecs, + processContext: null, + setProcessContext, + }) + ), + }; +}); + +import FrameView from '../FrameView'; + +describe('FrameView (PWA)', () => { + it('renders LayeredProcessView with three bands', () => { + render(); + + expect(screen.getByTestId('layered-process-view')).toBeInTheDocument(); + expect(screen.getByTestId('band-outcome')).toBeInTheDocument(); + expect(screen.getByTestId('band-process-flow')).toBeInTheDocument(); + expect(screen.getByTestId('band-operations')).toBeInTheDocument(); + }); +}); diff --git a/docs/01-vision/methodology.md b/docs/01-vision/methodology.md index 0bac9482e..ddae02fd2 100644 --- a/docs/01-vision/methodology.md +++ b/docs/01-vision/methodology.md @@ -37,8 +37,12 @@ VariScout now uses a nested methodology model: | Layer | Job | | ------------------------------------ | ------------------------------------------------------------------- | | **Process Hub** | Operating spine for process-owner cadence and team improvement | +| **Process Measurement System** | Designed measure, evidence, snapshot, trust, and cadence layer | +| **Current Process State** | Latest review of outcome, flow, known x-control, and trust measures | | **Evidence Sources / Data Profiles** | Recurring hub evidence workflow and deterministic source adapters | -| **Investigation journey** | FRAME -> SCOUT -> INVESTIGATE -> IMPROVE for one issue | +| **Process learning levels** | Outcome, flow, and local-mechanism levels of process understanding | +| **Investigation journey** | Reasoning loop from Current Process State to response | +| **Response paths** | Quick action, focused investigation, charter, sustainment, handoff | | **Question-driven EDA** | Reasoning spine that sharpens concern into Current Understanding | | **Survey** | Horizontal readiness check across phases and hub reviews | | **Signal Cards** | Signal-level trust records quoted by Survey, branches, and reports | @@ -46,10 +50,75 @@ VariScout now uses a nested methodology model: | **Sustainment handoff** | Decision on what stays in VariScout or moves to operational systems | This is not a replacement for the original journey. Process Hub organizes the -work; Evidence Sources provide recurring Snapshots for hub cadence; Data -Profiles adapt recognizable source-data shapes deterministically; the -investigation journey explains how the work is done; Survey asks whether the -current evidence is ready for the next move. +work; the Process Measurement System defines what the process reviews and +trusts; Evidence Sources provide recurring Snapshots; Current Process State +shows what the process looks like now; investigations explain that state well +enough to choose a response path. Survey asks whether the current evidence is +ready for the next move. + +The settled vocabulary is: + +```text +VariScout = Process Learning System +Process Hub = operating home for one process +Process Measurement System = designed evidence/measure layer +Current Process State = process-owner review surface +Investigation = structured reasoning loop from state to response +Response Path = quick action / focused investigation / charter / sustain / handoff +CoScout = product assistant grounded in shared process context +``` + +Publicly, VariScout should promise a shared, evidence-backed process context +for teams. CoScout uses that context to explain, draft, and guide investigation +work. VariScout should not promise an open AI-agent platform or autonomous +process control. + +### Process Learning Levels + +VariScout should not treat analysis modes as the primary mental model. The +stronger frame is a Makigami-style set of process understanding levels: + +| Level | Question | Typical evidence | +| ------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------ | +| **System / outcome** | What result must the customer or business experience? | CTS, Y, spec, target, Process Hub cadence, sustainment gaps | +| **Flow / process model** | What flows through which steps, at what rate, and where is loss? | CTQ per step, rate, cycle time, wait, throughput, bottleneck | +| **Local mechanism / evidence** | What physics, recipe, condition, or measurement issue explains? | settings, material, equipment, subgroup, gemba, Signal Card | + +The FRAME process map is one important flow-level lens. It is not the whole +method. The full model links one-off datasets, investigations, recurring +Evidence Sources, Process Hub cadence, and sustainment/control handoff. See +[Process Learning Operating Model](../superpowers/specs/2026-04-27-process-learning-operating-model-design.md). + +These levels generalize the older three-level EDA language: + +| Investigation language | Process-learning language | +| ---------------------- | -------------------------- | +| Y / problem condition | System / outcome | +| X / concentration | Flow / process model | +| x / local mechanism | Local mechanism / evidence | + +The FRAME workspace renders these levels as three visible bands — **Outcome**, +**Process Flow**, and **Operations** — stacked vertically with the river-styled +SIPOC inside the Process Flow band. The visual structure makes the methodology +visible by default. See the [Layered Process View design spec](../superpowers/specs/2026-04-27-layered-process-view-design.md) for band semantics, surface variations, and phasing. + +### Current Process State + +Current Process State is not a simple "stable or not stable" label. It is the +latest structured read of the process across outcome, flow, known x-control, +capability structure, and trust: + +- **Cpk vs target Cpk** shows whether current performance is good enough. +- **Cp-Cpk gap** shows centering loss. +- **Cp/Cpk over subgroups or snapshots** shows how capability itself is moving. +- **flow and wait measures** show whether the process is moving as expected. +- **known x-control measures** show whether confirmed drivers are still inside + expected windows. +- **sample size, power, subgroup, and MSA signals** protect the team from + overclaiming. + +Current Process State can trigger quick team action, focused investigation, +chartered improvement, sustainment review, or control handoff. --- @@ -206,15 +275,20 @@ The lens metaphor is useful for marketing and teaching, but the methodology work --- -### Analysis Modes +### Analysis Modes As Instrument Sets -Beyond the standard four-tool view, VariScout supports alternative analysis modes that reconfigure the dashboard for specific analytical questions: +Beyond the standard four-tool view, VariScout supports alternative instrument +sets that reconfigure the dashboard for specific process questions: - **Performance Mode** — Multi-channel Cpk comparison for wide-format data (fill heads, cavities, nozzles) - **Yamazumi Mode** — Lean time study with stacked activity bars and cycle time decomposition - **Capability Mode** — Per-subgroup Cp/Cpk stability analysis on the I-Chart, answering "Are we meeting our Cpk target?" Analysts switch freely between standard and capability views at any drill level. Time-based subgrouping uses extracted time columns from FRAME. See [Analysis Flow](../03-features/workflows/analysis-flow.md) for how these modes interleave through the full journey. -Each mode reuses the same chart infrastructure with different data pipelines and interpretation context. See [Subgroup Capability Analysis](../03-features/analysis/subgroup-capability.md) for the capability mode details. +The user-facing question should be "what level of process understanding are we +working on?" before it becomes "which mode?" Each mode reuses the same chart +infrastructure with different data pipelines and interpretation context. See +[Subgroup Capability Analysis](../03-features/analysis/subgroup-capability.md) +for the capability mode details. --- diff --git a/docs/05-technical/architecture/mental-model-hierarchy.md b/docs/05-technical/architecture/mental-model-hierarchy.md index a99e950f2..14c363a5d 100644 --- a/docs/05-technical/architecture/mental-model-hierarchy.md +++ b/docs/05-technical/architecture/mental-model-hierarchy.md @@ -100,6 +100,8 @@ The thread is not always linear — Routine Check entries may never reach INVEST FRAME contains significant deterministic engines: data parsing and validation, column type detection, factor role keyword inference (equipment/temporal/operator/material/location), investigation category auto-grouping, and characteristic type selection. Process context and analysis brief (Azure) become the AI's grounding context in subsequent phases. +**Layered band structure:** FRAME renders as three vertically stacked bands — Outcome / Process Flow / Operations — wrapping the existing river-styled SIPOC inside the Process Flow band. The bands are a render-time projection; no data-model change. See `LayeredProcessView` in `@variscout/ui` and the [Layered Process View design spec](../../superpowers/specs/2026-04-27-layered-process-view-design.md). + ### SCOUT | Aspect | Detail | diff --git a/docs/07-decisions/adr-070-frame-workspace.md b/docs/07-decisions/adr-070-frame-workspace.md index 402ef3131..074fdfdc2 100644 --- a/docs/07-decisions/adr-070-frame-workspace.md +++ b/docs/07-decisions/adr-070-frame-workspace.md @@ -96,6 +96,16 @@ FRAME must work end-to-end without any AI call (Constitution P8 _Deterministic f - Existing investigation workflow is unchanged: pre-data hunches created in FRAME flow into `investigationStore` as draft `SuspectedCause` hubs, reusing the hub model ([ADR-064](./adr-064-suspected-cause-hub-model.md)). Analysis, Investigation, Improvement, and Report workspaces are untouched. +## Update — 2026-04-27 (Layered Process View V1) + +The river-styled SIPOC `ProcessMapBase` is now wrapped by `LayeredProcessView` (`@variscout/ui`), which adds an Outcome band above and an Operations band below. ADR-070 stays canonical for the river/SIPOC design itself; the layered extension adds visual structure around it without changing the data model. + +See the [Layered Process View design spec](../superpowers/specs/2026-04-27-layered-process-view-design.md) for band semantics, surface variations, and phasing. + +V1 is structural only: the bands wrap the existing component. V2+ phases add Operations band content (snapshot-backed actuals, capability sparklines), Process Hub current-state rendering, and multi-hub aggregation. + +V1 places the process specs (target / USL / LSL) in the Outcome band as a pragmatic simplification — the design spec ultimately positions per-step specs alongside rate data in the Operations band (see V3 in the design spec). Reconciling this is a follow-up; treat the V1 placement as a transient. + ## Implementation Staged across multiple PRs. See the design spec for full detail: [FRAME Workspace & Visual Process Map](../superpowers/specs/2026-04-18-frame-process-map-design.md). diff --git a/docs/08-products/presentations/variscout-product-evaluation-deck.pptx b/docs/08-products/presentations/variscout-product-evaluation-deck.pptx new file mode 100644 index 000000000..e8cec8e85 Binary files /dev/null and b/docs/08-products/presentations/variscout-product-evaluation-deck.pptx differ diff --git a/docs/08-products/presentations/variscout-product-evaluation-narrative-plan.md b/docs/08-products/presentations/variscout-product-evaluation-narrative-plan.md new file mode 100644 index 000000000..ef1a4c926 --- /dev/null +++ b/docs/08-products/presentations/variscout-product-evaluation-narrative-plan.md @@ -0,0 +1,46 @@ +--- +title: VariScout Product Evaluation Deck Narrative Plan +audience: [product, manager, analyst] +category: strategy +status: draft +date: 2026-04-27 +--- + +# VariScout Product Evaluation Deck + +Audience: MBB, product leadership, process-improvement experts, and implementation stakeholders. + +Objective: explain how VariScout is used, who uses and contributes to it, what problems it solves, how the system reasons, and which capabilities are implemented, partial, designed, next, or deferred. + +Readability target: large-room readable for weaker eyesight and projector viewing. Body text is kept at 22px or larger; dense slides are split instead of shrinking text. + +Narrative arc: why this product exists, who it serves, how teams frame and investigate work, how deterministic statistics and readiness checks protect decision quality, and what proof should come next. + +Slide list: + +1. VariScout controls the improvement learning loop +2. The missing layer is retained reasoning +3. It is deliberately not a generic platform +4. Primary users need different depths +5. Many voices feed one evidence graph +6. The architecture mirrors the method +7. FRAME maps the process before analysis +8. Use process inputs & conditions +9. Subgroups come from process logic +10. Subgroup capability shows stability of capability +11. The core loop is current understanding +12. First half: define and find the signal +13. Second half: test, improve, and retain learning +14. Expose instruments, not disconnected apps +15. Instrument maturity should be visible +16. What the stats engine calculates +17. How calculations become investigation signals +18. MSA starts as measurement trust logic +19. Full Gage R&R is a next-stage capability +20. Power protects teams from false confidence +21. Survey and surfaces keep decisions bounded +22. Evaluate the habit, then prove it narrowly + +Terminology: use process inputs & conditions. Inputs are SIPOC-style incoming material or information; conditions are internal operating factors such as force, speed, pressure, temperature, setup, tool state, shift, method, and environment. + +Editability plan: all slide text, diagrams, badges, cards, and process structures are editable PowerPoint objects. diff --git a/docs/DATA-FLOW.md b/docs/DATA-FLOW.md index a45cf3355..b20c6eed6 100644 --- a/docs/DATA-FLOW.md +++ b/docs/DATA-FLOW.md @@ -21,12 +21,16 @@ Users paste text, upload CSV, or drag a file. `packages/core/src/parser/` detect **No value flagged as unparseable is silently zeroed.** Downstream code sees `undefined` or a valid number. -Process Hub Evidence Sources are a future workflow layer above this parse -boundary. An Evidence Source represents recurring hub evidence; a Snapshot is -one dated evidence package from that source. When the source shape is known, a -Data Profile can recommend mappings, derive deterministic columns, and record a -Profile Application for that Snapshot. Current code still enters through the -existing paste/upload/manual paths. +Process Hub Evidence Sources are the workflow layer above this parse boundary. +An Evidence Source represents recurring hub evidence; a Snapshot is one dated +evidence package from that source. When the source shape is known, a Data +Profile can recommend mappings, derive deterministic columns, and record a +Profile Application for that Snapshot. Together, Evidence Sources, Snapshots, +Signal Cards, Survey readiness, targets, subgroup logic, and cadence rules form +the Process Measurement System that produces Current Process State for Process +Hub review. Current ordinary analysis still enters through the existing +paste/upload/manual paths, while Azure has the first profile-specific Evidence +Source slice for Agent Review Log snapshots. ## 2. Mode transforms (pre-stats aggregation) @@ -53,10 +57,12 @@ Two-pass best subsets with interaction screening (ADR-067) drives Evidence Map. IndexedDB schema in `apps/azure/src/db/schema.ts` (Dexie). `services/localDb.ts` is the facade. sessionStore from `@variscout/stores` persists UI session state via middleware; document-level persistence goes through `useProjectActions` (domain stores). -Future Evidence Source objects are design concepts only in the current docs -update: `EvidenceSource`, `DataProfileDefinition`, `EvidenceSnapshot`, and -`ProfileApplication`. They are not implemented in the current persistence -schema. +Evidence Source objects now exist in core as the first implementation slice: +`EvidenceSource`, `DataProfileDefinition`, `EvidenceSnapshot`, and +`ProfileApplication`. The current persisted Azure UI support is still narrow +and profile-specific; ordinary process datasets do not yet have a general +promotion path from one-off project to recurring Evidence Source or Current +Process State review. ## 5. Sync (Azure Team only) @@ -69,8 +75,9 @@ schema. SAS lifetime, container structure, and RBAC rules: `docs/08-products/azure/blob-storage-sync.md`. -Current Blob behavior remains project-based. Phase 5 reserves a future Process -Hub evidence namespace without claiming current support: +Current Blob behavior remains primarily project-based, with Process Hub +evidence storage emerging through the first Evidence Source implementation +slice. The logical namespace remains: `process-hubs/{hubId}/evidence-sources/{sourceId}/snapshots/{snapshotId}/...`. ## 6. Display boundary (B3 — the third numeric gate) diff --git a/docs/USER-JOURNEYS.md b/docs/USER-JOURNEYS.md index f4346aed2..9104ebf4d 100644 --- a/docs/USER-JOURNEYS.md +++ b/docs/USER-JOURNEYS.md @@ -9,7 +9,7 @@ related: [personas, flows, journey, modes] # VariScout User Journeys — Personas & Flows -Ten personas drive VariScout's design decisions. Each follows the same journey spine (FRAME → SCOUT → INVESTIGATE → IMPROVE); the tools they use inside each phase vary by analysis mode. +Ten personas drive VariScout's design decisions. Each follows the same journey spine (FRAME → SCOUT → INVESTIGATE → IMPROVE); the tools they use inside each phase vary by process question and evidence shape. ## The ten personas @@ -35,9 +35,11 @@ work across multiple hubs to compare leverage, blocked work, verification gaps, and charter candidates. The PWA remains investigation-first for training. Evidence Sources are the recurring hub inputs that let those users ask whether -the process is meeting the requirement, what changed, and where to focus. Data -Profiles sit behind recognized Evidence Sources as deterministic adapters, not -as a separate user-facing journey. +the process is meeting the requirement, what changed, and where to focus. The +Process Measurement System combines those sources, stable measure definitions, +targets, subgroup logic, trust checks, known x-control measures, and cadence +rules into Current Process State. Data Profiles sit behind recognized Evidence +Sources as deterministic adapters, not as a separate user-facing journey. ## Usage levels @@ -47,7 +49,7 @@ VariScout serves one nested methodology at several levels of use: | --------------------------- | --------------------------------- | ------------------------------------------------------------------------ | | PWA / training | Tina, Sara, Carlos | Learn the investigation method without organizational persistence | | Quick analyst dataset | Alex, Eeva, Gary | Analyze one dataset and attach the learning to process context | -| Process-owner cadence | Olivia, process owner, team lead | Review signals, actions, verification, and sustainment in one hub | +| Process-owner cadence | Olivia, process owner, team lead | Review Current Process State and choose the right response path | | GB/BB multi-hub scan | Gary, Olivia, sponsor | Compare hubs for leverage, charter candidates, and blocked work | | Evidence-source enablement | Admin Aino, data team, consultant | Fit recurring exports to VariScout contracts without custom integrations | | Sustainment/control handoff | Owner, quality, operations | Decide what stays in VariScout and what moves to live monitoring | @@ -56,19 +58,77 @@ The same investigation journey sits inside each level. Survey acts as the readiness evaluator: it asks what the current data, signals, branches, and verification evidence can support next. -## The unified journey spine +## Current Process State and response paths + +Process-owner cadence centers on Current Process State: the latest read of +outcome, flow, known x-control, capability structure, and trust measures. This +state is produced by the Process Measurement System, not by a generic dashboard. + +Current Process State can trigger five response paths: + +| Response path | Typical use | +| ----------------------------- | ------------------------------------------------------------------ | +| Quick team action | Cause is obvious enough, low-risk, reversible, and locally owned. | +| Focused investigation | Pattern is real, but mechanism, subgroup, trust, or scope is open. | +| Chartered improvement project | High impact, cross-functional, expensive, regulatory, or unclear. | +| Sustainment review | Improvement is verified and should stay checked in VariScout. | +| Control handoff | Live control belongs in another operational system. | -Every investigation — Standard, Yamazumi, Performance, Defect, Capability, or Process Flow — follows this spine: +CoScout is grounded in the same shared process context. It can explain, draft, +and guide investigation work, but deterministic statistics, Survey, Signal +Cards, and user-confirmed evidence remain the authority. -1. **FRAME.** User names the problem. Three entry points per P5 (amended constitution): upfront hypothesis, evidence-ranked from data (Factor Intelligence), or observation-triggered (from a Four Lenses finding). Problem Statement captures Watson's 3 Qs. +## Process learning levels -2. **SCOUT.** Data is parsed (wide-form, stack columns, defect events all supported). Characteristic types inferred. The Four Lenses surface variation patterns. First hypotheses emerge. +The journey should be evaluated through three levels of process understanding, +not only through analysis modes: -3. **INVESTIGATE.** User picks one or more suspected causes — the SuspectedCause hub model (ADR-064) is the organizing entity. Each hub accumulates evidence: data (Evidence Map edges with R²adj from best-subsets regression), gemba (photos, notes), expert knowledge. The investigation spine has three threads (ADR-066): regression discovery, hub UX, EDA heartbeat. +| Level | Main user question | Common users | +| -------------------------- | ------------------------------------------------------------------- | ------------------------------------ | +| System / outcome | Are we meeting the customer or business requirement? | process owner, sponsor, OpEx, GB/BB | +| Flow / process model | Where does time, rate, throughput, wait, or bottleneck loss live? | engineer, lean practitioner, analyst | +| Local mechanism / evidence | Which physics, recipe, condition, or measurement issue explains it? | local owner, expert, gemba observer | -4. **IMPROVE.** Hubs with strong evidence become HMW ("How Might We") brainstorming starters. Ideas prioritized by timeframe × cost × risk × impact (ADR-035). Selected ideas become action items; implementation captured, outcome compared to prediction via What-If Explorer. +The same dataset can start at any level. A customer complaint or Cpk gap starts +at outcome level. Timestamped station data starts at flow level. A scoped +Yamazumi study, maintenance record, or gemba check starts at local-mechanism +level. VariScout's job is to connect those levels into durable process +understanding. + +These levels generalize the existing investigation language: `Y` maps to +system/outcome, `X` maps to flow/concentration, and local `x` maps to mechanism +or evidence. Process Flow uses the same idea as line, station, and activity +levels. + +## The unified journey spine -## Per-mode distinctive experience +Every investigation - Standard, Yamazumi, Performance, Defect, Capability, or Process Flow - follows this spine: + +1. **FRAME.** User names the concern and maps the evidence to the right + process-understanding level: outcome, flow, or local mechanism. Three entry + points per P5 (amended constitution): upfront hypothesis, evidence-ranked + from data (Factor Intelligence), or observation-triggered (from a Four Lenses + finding). Problem Statement captures Watson's 3 Qs. + +2. **SCOUT.** Data is parsed (wide-form, stack columns, defect events all + supported). Characteristic types are inferred. Instrument sets surface + variation, capability, flow, defect, or work-content patterns. First clues + and questions emerge. + +3. **INVESTIGATE.** User builds one or more Mechanism Branches or + SuspectedCause hubs. Each hub accumulates evidence: data (Evidence Map edges + with R2adj from best-subsets regression), gemba (photos, notes), and expert + knowledge. The investigation may discover a new x, check which known x + changed, validate a suspected mechanism, scope the problem, resolve a trust + gap, or verify an action. The investigation spine has three threads + (ADR-066): regression discovery, hub UX, and EDA heartbeat. + +4. **IMPROVE.** Hubs with strong evidence become HMW ("How Might We") + brainstorming starters. Ideas are prioritized by timeframe, cost, risk, and + impact (ADR-035). Selected ideas become action items; implementation is + captured; outcome is compared to prediction via What-If Explorer. + +## Instrument-set experience ### Standard mode diff --git a/docs/llms.txt b/docs/llms.txt index 4eb2f5667..c82b60358 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -7,9 +7,12 @@ Entry points for AI agents working in this repo. Humans should start at `docs/in ## Core orientation - [OVERVIEW.md](OVERVIEW.md): what VariScout does, the FRAME → SCOUT → INVESTIGATE → IMPROVE journey, six analysis modes, three distribution tiers. -- [USER-JOURNEYS.md](USER-JOURNEYS.md): ten personas, unified journey spine, per-mode distinctive experience. +- [USER-JOURNEYS.md](USER-JOURNEYS.md): ten personas, unified journey spine, process learning levels, and instrument-set experiences. - [DATA-FLOW.md](DATA-FLOW.md): parse → transform → stats → persist → sync → display → AI pipeline. Three numeric-safety boundaries. +- [superpowers/specs/2026-04-27-product-method-roadmap-design.md](superpowers/specs/2026-04-27-product-method-roadmap-design.md): product-method maturity roadmap across Process Hub, Current Process State, Process Measurement System, process learning memory, and CoScout context. +- [superpowers/specs/2026-04-27-process-learning-operating-model-design.md](superpowers/specs/2026-04-27-process-learning-operating-model-design.md): process learning operating model; Process Measurement System, Current Process State, response paths, and Makigami-style outcome/flow/local-mechanism levels. - [superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md](superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md): canonical Evidence Sources, Data Profiles, Snapshots, and Profile Applications design. +- [superpowers/specs/2026-04-27-layered-process-view-design.md](superpowers/specs/2026-04-27-layered-process-view-design.md): three-band visual language (Outcome / Process Flow / Operations) for FRAME, Process Hub, and multi-hub. - [01-vision/trainer-network.md](01-vision/trainer-network.md): lightweight trainer ecosystem model for VariScout growth, certification, and directory routing. ## Architecture diff --git a/docs/superpowers/plans/2026-04-27-layered-process-view-v1.md b/docs/superpowers/plans/2026-04-27-layered-process-view-v1.md new file mode 100644 index 000000000..41008ace2 --- /dev/null +++ b/docs/superpowers/plans/2026-04-27-layered-process-view-v1.md @@ -0,0 +1,980 @@ +# Layered Process View V1 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Wrap the existing river-styled SIPOC FRAME workspace in a three-band layered visual (Outcome / Process Flow / Operations), shipping in both PWA and Azure apps without changing the underlying ProcessMap data model. + +**Architecture:** New shared component `` in `@variscout/ui` composes (a) an Outcome summary band on top, (b) the existing `` river-SIPOC inside a Process Flow band, and (c) an Operations band below that mirrors `map.tributaries` as factor chips labelled with their parent step. Both `FrameView` wrappers (PWA + Azure) swap their `ProcessMapBase` usage for `LayeredProcessView`. No data-model changes; props-based composition only. + +**Tech Stack:** TypeScript, React (functional components), Tailwind v4 with semantic tokens, Vitest + React Testing Library. No new dependencies. + +**Spec:** [`docs/superpowers/specs/2026-04-27-layered-process-view-design.md`](../specs/2026-04-27-layered-process-view-design.md). V1 corresponds to the spec's "V1 — Layer existing FRAME map into three visual bands" phase. + +**Out of scope for V1 (deferred to later phases per the spec):** + +- New data model (factor specs, designed step rates, snapshot-backed actuals) — V3 / V4 +- Cross-band SVG connector lines (require pixel-position coordination with `ProcessMapBase`) — V2+ +- Process Hub current-state rendering — V2 +- Multi-hub aggregate rendering — V5 +- `tributary` → `factor` code rename — separate PR before V3 +- Capability-mode-specific emphasis on bands — V1 ships with default content for all modes + +--- + +## File Structure + +**Created:** + +- `packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx` — the composed view +- `packages/ui/src/components/LayeredProcessView/index.ts` — barrel export +- `packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx` — component tests + +**Modified:** + +- `packages/ui/src/index.ts` — add `LayeredProcessView` to public exports +- `apps/pwa/src/components/views/FrameView.tsx` — swap `ProcessMapBase` for `LayeredProcessView` +- `apps/azure/src/components/editor/FrameView.tsx` — same swap +- `docs/07-decisions/adr-070-frame-workspace.md` — amend to note layered extension +- `docs/01-vision/methodology.md` — add band labels to the methodology hierarchy table +- `docs/05-technical/architecture/mental-model-hierarchy.md` — note the layered visual structure for FRAME +- `docs/llms.txt` — add reference to the new spec + +**Not modified (rely on existing patterns):** + +- `packages/charts/src/ProcessMap/` — primitives unchanged +- `packages/ui/src/components/ProcessMap/ProcessMapBase.tsx` — used as-is by `LayeredProcessView` +- `packages/core/src/frame/` — types unchanged +- `packages/core/src/processState.ts` — `ProcessStateLens` reconciliation is render-time projection only; no enum changes + +--- + +## Conventions + +These apply across all tasks; the engineer should follow them without being reminded each time. + +- **Functional components only.** Props interface named `LayeredProcessViewProps` (per `@variscout/ui` rule). +- **Semantic Tailwind classes** (`bg-surface-secondary`, `text-content`, `border-edge`) so the component adapts to `data-theme`. Never hard-code colors. +- **Test imports**: `vi.mock()` calls **must come before** the component import to prevent infinite test loops (per `writing-tests` skill / memory rule). +- **No `Math.random`** in code or tests. The existing `ProcessMapBase` already uses `Math.random` for IDs; do not propagate that pattern into the new component. +- **`data-testid` for tests**: top-level wrapper carries `data-testid="layered-process-view"`; bands carry `data-testid="band-outcome"`, `band-process-flow`, `band-operations`. +- **No new i18n keys for V1**: hard-coded English labels match the existing `FrameView` header pattern. i18n keys are a follow-up if and when methodology.md upgrades. +- **Commits**: small, focused. Each task ends with a commit. Commit messages follow the existing convention (`feat:`, `test:`, `docs:`, `refactor:`). + +--- + +## Task 1: Scaffold `LayeredProcessView` skeleton + +**Files:** + +- Create: `packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx` +- Create: `packages/ui/src/components/LayeredProcessView/index.ts` +- Create: `packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx` +- Modify: `packages/ui/src/index.ts` — add export + +- [ ] **Step 1.1: Write the failing test for the three-band skeleton** + +Create `packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx`: + +```tsx +import { render, screen } from '@testing-library/react'; +import { describe, it, expect } from 'vitest'; +import { LayeredProcessView } from '../LayeredProcessView'; +import type { ProcessMap } from '@variscout/core/frame'; + +const emptyMap: ProcessMap = { + version: 1, + nodes: [], + tributaries: [], + createdAt: '2026-04-27T00:00:00.000Z', + updatedAt: '2026-04-27T00:00:00.000Z', +}; + +describe('LayeredProcessView', () => { + it('renders three bands labelled Outcome, Process Flow, Operations', () => { + render( {}} />); + + expect(screen.getByTestId('layered-process-view')).toBeInTheDocument(); + expect(screen.getByTestId('band-outcome')).toBeInTheDocument(); + expect(screen.getByTestId('band-process-flow')).toBeInTheDocument(); + expect(screen.getByTestId('band-operations')).toBeInTheDocument(); + + expect(screen.getByText('Outcome')).toBeInTheDocument(); + expect(screen.getByText('Process Flow')).toBeInTheDocument(); + expect(screen.getByText('Operations')).toBeInTheDocument(); + }); +}); +``` + +- [ ] **Step 1.2: Run test to verify it fails** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: FAIL — `Cannot find module '../LayeredProcessView'` (component doesn't exist yet). + +- [ ] **Step 1.3: Implement minimal three-band skeleton** + +Create `packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx`: + +```tsx +/** + * LayeredProcessView — three-band Makigami-style process visual. + * + * Stacks Outcome / Process Flow / Operations bands vertically. The Process + * Flow band wraps the existing `ProcessMapBase` river-SIPOC; the Outcome and + * Operations bands surround it. See spec at + * `docs/superpowers/specs/2026-04-27-layered-process-view-design.md` (V1). + */ + +import React from 'react'; +import type { ProcessMap, Gap } from '@variscout/core/frame'; + +export interface LayeredProcessViewProps { + map: ProcessMap; + availableColumns: string[]; + onChange: (next: ProcessMap) => void; + gaps?: Gap[]; + disabled?: boolean; + target?: number; + usl?: number; + lsl?: number; + onSpecsChange?: (next: { target?: number; usl?: number; lsl?: number }) => void; +} + +export const LayeredProcessView: React.FC = () => { + return ( +
+
+

Outcome

+
+
+

Process Flow

+
+
+

Operations

+
+
+ ); +}; +``` + +- [ ] **Step 1.4: Create barrel export** + +Create `packages/ui/src/components/LayeredProcessView/index.ts`: + +```ts +export { LayeredProcessView } from './LayeredProcessView'; +export type { LayeredProcessViewProps } from './LayeredProcessView'; +``` + +- [ ] **Step 1.5: Add to package public exports** + +Open `packages/ui/src/index.ts` and add (matching existing export style — likely near other component exports): + +```ts +export { LayeredProcessView } from './components/LayeredProcessView'; +export type { LayeredProcessViewProps } from './components/LayeredProcessView'; +``` + +- [ ] **Step 1.6: Run test to verify it passes** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: PASS — all three bands rendered with correct testids and labels. + +- [ ] **Step 1.7: Commit** + +```bash +git add packages/ui/src/components/LayeredProcessView/ packages/ui/src/index.ts +git commit -m "feat(ui): scaffold LayeredProcessView three-band skeleton" +``` + +--- + +## Task 2: Wire Outcome band to specs + +The Outcome band shows the strategic / business outcome we want. For V1, populate it with `target` (Cpk target value), USL, and LSL when provided. Show a placeholder when no specs are set. + +**Files:** + +- Modify: `packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx` +- Modify: `packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx` + +- [ ] **Step 2.1: Add failing tests for Outcome band content** + +Add to the existing test file: + +```tsx +it('shows target Cpk in Outcome band when target is set', () => { + render( + {}} target={1.33} /> + ); + + const outcomeBand = screen.getByTestId('band-outcome'); + expect(outcomeBand).toHaveTextContent('Target: 1.33'); +}); + +it('shows USL and LSL in Outcome band when set', () => { + render( + {}} + usl={12.5} + lsl={8.5} + /> + ); + + const outcomeBand = screen.getByTestId('band-outcome'); + expect(outcomeBand).toHaveTextContent('USL: 12.5'); + expect(outcomeBand).toHaveTextContent('LSL: 8.5'); +}); + +it('shows placeholder when no outcome data', () => { + render( {}} />); + + const outcomeBand = screen.getByTestId('band-outcome'); + expect(outcomeBand).toHaveTextContent('No outcome target set'); +}); +``` + +- [ ] **Step 2.2: Run tests to verify they fail** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: 3 new tests fail (placeholder + target + USL/LSL); existing skeleton test still passes. + +- [ ] **Step 2.3: Implement Outcome band content** + +Update the Outcome `
` in `LayeredProcessView.tsx`: + +```tsx +const hasOutcomeData = target !== undefined || usl !== undefined || lsl !== undefined; + +// inside the return: +
+

Outcome

+ {hasOutcomeData ? ( +
+ {target !== undefined && ( +
+
Target:
+
{target}
+
+ )} + {usl !== undefined && ( +
+
USL:
+
{usl}
+
+ )} + {lsl !== undefined && ( +
+
LSL:
+
{lsl}
+
+ )} +
+ ) : ( +

No outcome target set

+ )} +
; +``` + +Update the destructured props in the component signature to actually consume them: + +```tsx +export const LayeredProcessView: React.FC = ({ + target, + usl, + lsl, +}) => { +``` + +(Other props get destructured in subsequent tasks.) + +- [ ] **Step 2.4: Run tests to verify they pass** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: All 4 tests pass. + +- [ ] **Step 2.5: Commit** + +```bash +git add packages/ui/src/components/LayeredProcessView/ +git commit -m "feat(ui): wire Outcome band to specs (target/USL/LSL)" +``` + +--- + +## Task 3: Embed `ProcessMapBase` in Process Flow band + +Process Flow band wraps the existing `ProcessMapBase` component. All current FRAME interactions (step add, tributary add, hunches, gap rendering, specs popover) keep working unchanged. + +**Files:** + +- Modify: `packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx` +- Modify: `packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx` + +- [ ] **Step 3.1: Add failing test for Process Flow band containing ProcessMapBase** + +Add to the test file: + +```tsx +it('renders ProcessMapBase inside Process Flow band', () => { + const mapWithStep: ProcessMap = { + ...emptyMap, + nodes: [{ id: 'step-1', name: 'Mix' }], + }; + + render( + {}} + /> + ); + + const processFlowBand = screen.getByTestId('band-process-flow'); + // ProcessMapBase renders the step name + expect(processFlowBand).toHaveTextContent('Mix'); +}); +``` + +- [ ] **Step 3.2: Run test to verify it fails** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: New test fails — "Mix" text not found in the Process Flow band (ProcessMapBase isn't there yet). + +- [ ] **Step 3.3: Embed ProcessMapBase in the Process Flow band** + +Update the imports and component body in `LayeredProcessView.tsx`: + +```tsx +import React from 'react'; +import type { ProcessMap, Gap } from '@variscout/core/frame'; +import { ProcessMapBase } from '../ProcessMap/ProcessMapBase'; + +// ... (props interface unchanged) + +export const LayeredProcessView: React.FC = ({ + map, + availableColumns, + onChange, + gaps, + disabled, + target, + usl, + lsl, + onSpecsChange, +}) => { + const hasOutcomeData = target !== undefined || usl !== undefined || lsl !== undefined; + + return ( +
+ {/* Outcome band — unchanged from Task 2 */} +
+ {/* ... existing Outcome band markup ... */} +
+ + {/* Process Flow band — wraps ProcessMapBase */} +
+

Process Flow

+
+ +
+
+ + {/* Operations band — placeholder for now, populated in Task 4 */} +
+

Operations

+
+
+ ); +}; +``` + +- [ ] **Step 3.4: Run tests to verify they pass** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: All tests pass (including existing ones — ProcessMapBase still works as-is). + +- [ ] **Step 3.5: Commit** + +```bash +git add packages/ui/src/components/LayeredProcessView/ +git commit -m "feat(ui): embed ProcessMapBase in Process Flow band" +``` + +--- + +## Task 4: Render factor chips in Operations band + +Operations band shows `map.tributaries` as a row of factor chips. Each chip displays the column name and the parent step's name. Read-only mirror — V1 does not let users edit factors from the Operations band (those edits still happen via the river inside the Process Flow band). + +**Files:** + +- Modify: `packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx` +- Modify: `packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx` + +- [ ] **Step 4.1: Add failing tests for factor chips** + +Add to the test file: + +```tsx +it('renders one factor chip per tributary in Operations band', () => { + const mapWithFactors: ProcessMap = { + ...emptyMap, + nodes: [ + { id: 'step-1', name: 'Mix' }, + { id: 'step-2', name: 'Coat' }, + ], + tributaries: [ + { id: 't-1', toNodeId: 'step-1', column: 'Temperature' }, + { id: 't-2', toNodeId: 'step-2', column: 'Speed' }, + ], + }; + + render( + {}} + /> + ); + + const operationsBand = screen.getByTestId('band-operations'); + const chips = operationsBand.querySelectorAll('[data-testid^="factor-chip-"]'); + expect(chips).toHaveLength(2); + expect(operationsBand).toHaveTextContent('Temperature'); + expect(operationsBand).toHaveTextContent('Speed'); +}); + +it('labels each factor chip with its parent step name', () => { + const mapWithFactors: ProcessMap = { + ...emptyMap, + nodes: [{ id: 'step-1', name: 'Mix' }], + tributaries: [{ id: 't-1', toNodeId: 'step-1', column: 'Temperature' }], + }; + + render( {}} />); + + const chip = screen.getByTestId('factor-chip-t-1'); + expect(chip).toHaveTextContent('Temperature'); + expect(chip).toHaveTextContent('at Mix'); +}); + +it('shows placeholder when no factors are mapped', () => { + render( {}} />); + + const operationsBand = screen.getByTestId('band-operations'); + expect(operationsBand).toHaveTextContent('No factors mapped yet'); +}); +``` + +- [ ] **Step 4.2: Run tests to verify they fail** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: 3 new tests fail; previous tests still pass. + +- [ ] **Step 4.3: Implement Operations band factor chips** + +Update the Operations band in `LayeredProcessView.tsx`: + +```tsx +{ + /* Operations band — factor chips per tributary */ +} +
+

Operations

+ {map.tributaries.length > 0 ? ( +
    + {map.tributaries.map(trib => { + const parentStep = map.nodes.find(n => n.id === trib.toNodeId); + const stepLabel = parentStep?.name ?? 'Unmapped'; + return ( +
  • + {trib.column} + at {stepLabel} +
    • + ); + })} +
+ ) : ( +

No factors mapped yet

+ )} +
; +``` + +- [ ] **Step 4.4: Run tests to verify they pass** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: All tests pass. + +- [ ] **Step 4.5: Commit** + +```bash +git add packages/ui/src/components/LayeredProcessView/ +git commit -m "feat(ui): render factor chips in Operations band" +``` + +--- + +## Task 5: Empty-state polish — placeholder when Process Flow is empty + +When the map has no steps, the Process Flow band's `ProcessMapBase` already renders its own empty state. Ensure the LayeredProcessView itself doesn't break visually with a fully empty map. This is a small polish task with one test. + +**Files:** + +- Modify: `packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx` + +- [ ] **Step 5.1: Add test for fully empty state** + +Add to the test file: + +```tsx +it('renders all three band frames even when the map is fully empty', () => { + render( {}} />); + + // All three bands render with their headers regardless of content + expect(screen.getByText('Outcome')).toBeInTheDocument(); + expect(screen.getByText('Process Flow')).toBeInTheDocument(); + expect(screen.getByText('Operations')).toBeInTheDocument(); + + // Outcome and Operations show their placeholders + expect(screen.getByTestId('band-outcome')).toHaveTextContent('No outcome target set'); + expect(screen.getByTestId('band-operations')).toHaveTextContent('No factors mapped yet'); +}); +``` + +- [ ] **Step 5.2: Run test to verify it passes** + +Run: `pnpm --filter @variscout/ui test LayeredProcessView -- --run` +Expected: PASS — the previous tasks already implemented the empty-state placeholders. This task is a regression check. + +- [ ] **Step 5.3: Commit** + +```bash +git add packages/ui/src/components/LayeredProcessView/ +git commit -m "test(ui): regression test for fully empty LayeredProcessView" +``` + +--- + +## Task 6: Replace `ProcessMapBase` with `LayeredProcessView` in PWA `FrameView` + +**Files:** + +- Modify: `apps/pwa/src/components/views/FrameView.tsx` +- Create or Modify: `apps/pwa/src/components/views/__tests__/FrameView.test.tsx` (create if doesn't exist) + +- [ ] **Step 6.1: Check if a FrameView test exists** + +Run: `ls apps/pwa/src/components/views/__tests__/FrameView.test.tsx 2>/dev/null && echo EXISTS || echo MISSING` + +If `EXISTS`, skip to step 6.2 (modify the existing test). If `MISSING`, create the file in step 6.2. + +- [ ] **Step 6.2: Write or update the failing test** + +Either create or modify `apps/pwa/src/components/views/__tests__/FrameView.test.tsx`: + +```tsx +import { render, screen } from '@testing-library/react'; +import { describe, it, expect, vi, beforeEach } from 'vitest'; + +// vi.mock MUST come before component imports (per writing-tests skill) +vi.mock('@variscout/stores', () => { + const setProcessContext = vi.fn(); + const setSpecs = vi.fn(); + return { + useProjectStore: vi.fn((selector: any) => + selector({ + rawData: [], + outcome: null, + specs: null, + setSpecs, + processContext: null, + setProcessContext, + }) + ), + }; +}); + +import FrameView from '../FrameView'; + +describe('FrameView (PWA)', () => { + it('renders LayeredProcessView with three bands', () => { + render(); + + expect(screen.getByTestId('layered-process-view')).toBeInTheDocument(); + expect(screen.getByTestId('band-outcome')).toBeInTheDocument(); + expect(screen.getByTestId('band-process-flow')).toBeInTheDocument(); + expect(screen.getByTestId('band-operations')).toBeInTheDocument(); + }); +}); +``` + +- [ ] **Step 6.3: Run test to verify it fails** + +Run: `pnpm --filter @variscout/pwa test FrameView -- --run` +Expected: FAIL — `band-outcome` testid not found (current FrameView uses ProcessMapBase, not LayeredProcessView). + +- [ ] **Step 6.4: Swap `ProcessMapBase` for `LayeredProcessView`** + +Modify `apps/pwa/src/components/views/FrameView.tsx`: + +Change the import line from: + +```tsx +import { ProcessMapBase } from '@variscout/ui'; +``` + +to: + +```tsx +import { LayeredProcessView } from '@variscout/ui'; +``` + +In the JSX return, replace the `` usage with `` — the props are identical (same prop names). + +The full updated component body: + +```tsx +return ( +
+
+
+

Frame the investigation

+

+ Build your process map so the analysis has context. The map drives mode selection and a + measurement-gap report; the methodology wants CTS at the ocean, a CTQ per step, and at + least one rational-subgroup axis. +

+
+ +
+
+); +``` + +(If the existing FrameView has any closing JSX after `onSpecsChange` that I haven't shown — preserve it.) + +- [ ] **Step 6.5: Run tests to verify they pass** + +Run: `pnpm --filter @variscout/pwa test FrameView -- --run` +Expected: PASS. + +- [ ] **Step 6.6: Run the broader PWA test suite to ensure no regressions** + +Run: `pnpm --filter @variscout/pwa test -- --run` +Expected: All tests pass (the swap is non-breaking; LayeredProcessView passes ProcessMapBase props through unchanged). + +- [ ] **Step 6.7: Commit** + +```bash +git add apps/pwa/src/components/views/FrameView.tsx apps/pwa/src/components/views/__tests__/FrameView.test.tsx +git commit -m "feat(pwa): use LayeredProcessView in FrameView" +``` + +--- + +## Task 7: Replace `ProcessMapBase` with `LayeredProcessView` in Azure `FrameView` + +Same swap as Task 6, in the Azure app. + +**Files:** + +- Modify: `apps/azure/src/components/editor/FrameView.tsx` +- Create or Modify: `apps/azure/src/components/editor/__tests__/FrameView.test.tsx` (create if doesn't exist) + +- [ ] **Step 7.1: Check if an Azure FrameView test exists** + +Run: `ls apps/azure/src/components/editor/__tests__/FrameView.test.tsx 2>/dev/null && echo EXISTS || echo MISSING` + +- [ ] **Step 7.2: Write or update the failing test** + +Either create or modify `apps/azure/src/components/editor/__tests__/FrameView.test.tsx`: + +```tsx +import { render, screen } from '@testing-library/react'; +import { describe, it, expect, vi } from 'vitest'; + +vi.mock('@variscout/stores', () => { + const setProcessContext = vi.fn(); + const setSpecs = vi.fn(); + return { + useProjectStore: vi.fn((selector: any) => + selector({ + rawData: [], + outcome: null, + specs: null, + setSpecs, + processContext: null, + setProcessContext, + }) + ), + }; +}); + +import FrameView from '../FrameView'; + +describe('FrameView (Azure)', () => { + it('renders LayeredProcessView with three bands', () => { + render(); + + expect(screen.getByTestId('layered-process-view')).toBeInTheDocument(); + expect(screen.getByTestId('band-outcome')).toBeInTheDocument(); + expect(screen.getByTestId('band-process-flow')).toBeInTheDocument(); + expect(screen.getByTestId('band-operations')).toBeInTheDocument(); + }); +}); +``` + +- [ ] **Step 7.3: Run test to verify it fails** + +Run: `pnpm --filter @variscout/azure-app test FrameView -- --run` +Expected: FAIL — `band-outcome` testid not found. + +- [ ] **Step 7.4: Swap `ProcessMapBase` for `LayeredProcessView` in Azure FrameView** + +Modify `apps/azure/src/components/editor/FrameView.tsx` exactly as in Task 6.4 — the file is structurally near-identical to the PWA version. + +- [ ] **Step 7.5: Run tests to verify they pass** + +Run: `pnpm --filter @variscout/azure-app test FrameView -- --run` +Expected: PASS. + +- [ ] **Step 7.6: Run the broader Azure test suite** + +Run: `pnpm --filter @variscout/azure-app test -- --run` +Expected: All tests pass. + +- [ ] **Step 7.7: Commit** + +```bash +git add apps/azure/src/components/editor/FrameView.tsx apps/azure/src/components/editor/__tests__/FrameView.test.tsx +git commit -m "feat(azure): use LayeredProcessView in FrameView" +``` + +--- + +## Task 8: Verify cross-package build + test green across the monorepo + +**Files:** none modified — verification only. + +- [ ] **Step 8.1: Run the @variscout/ui type check + build** + +Run: `pnpm --filter @variscout/ui build` +Expected: Build completes with no type errors. (Per memory rule: ui's tsc catches cross-package type-export gaps that per-package vitest misses.) + +- [ ] **Step 8.2: Run the full monorepo test suite** + +Run: `pnpm test` +Expected: All packages pass. (Note from memory: `packages/hooks` may show flaky timeout under concurrent load — re-run that package alone if it fails: `pnpm --filter @variscout/hooks test`.) + +- [ ] **Step 8.3: Run the full build** + +Run: `pnpm build` +Expected: All packages and apps build cleanly. Tailwind v4 `@source` directives in both apps' `index.css` should already cover `packages/ui/src/**/*.tsx` (per app CLAUDE.md memory rule), so the new component's classes will be picked up without changes. + +- [ ] **Step 8.4: No commit (verification task)** + +If issues surface, fix them in their respective tasks and re-run. + +--- + +## Task 9: Visual verification with `claude --chrome` + +The PR-ready check expects this for UI changes per memory rule "Verify before push". + +**Files:** none modified — manual verification. + +- [ ] **Step 9.1: Start the PWA dev server** + +Run: `pnpm dev` +Expected: PWA available at `http://localhost:5173`. + +- [ ] **Step 9.2: Walk the FRAME workspace with `claude --chrome`** + +Open the running app in chrome (via `claude --chrome` or browser). Navigate to FRAME workspace. Verify: + +- Three bands render with labels Outcome / Process Flow / Operations +- Outcome band shows "No outcome target set" placeholder when no specs are entered +- Setting USL/LSL/target via the existing SpecsPopover updates the Outcome band immediately +- Process Flow band shows the existing river-SIPOC, fully interactive (add step, add tributary, set ocean, etc.) +- Operations band shows factor chips matching tributaries (e.g., "Temperature at Mix") +- Operations band shows "No factors mapped yet" when no tributaries exist +- Theme toggle (light/dark) works; semantic Tailwind classes adapt correctly +- Resize the browser to tablet width — bands still render legibly (full mobile responsive behavior is V2+) + +- [ ] **Step 9.3: Walk the Azure FrameView with `claude --chrome`** + +If running the Azure app locally, do the same walk in `apps/azure`. Run: `pnpm --filter @variscout/azure-app dev`. + +- [ ] **Step 9.4: Document any visual issues** + +If anything reads poorly, file a follow-up task — _do not_ try to redesign in V1. V1 is structural; visual polish is allowed but not in scope for layout changes. + +--- + +## Task 10: Documentation updates + +Update related docs to reflect the layered visual structure. Per the user note: this should be holistic — touch every doc that's affected. + +**Files:** + +- Modify: `docs/07-decisions/adr-070-frame-workspace.md` +- Modify: `docs/01-vision/methodology.md` +- Modify: `docs/05-technical/architecture/mental-model-hierarchy.md` +- Modify: `docs/llms.txt` +- (Already done in earlier session) `docs/superpowers/specs/index.md` + +- [ ] **Step 10.1: Amend ADR-070 to note the layered extension** + +Open `docs/07-decisions/adr-070-frame-workspace.md`. Add a new "Update — 2026-04-27 (Layered Process View V1)" section after the existing Consequences section: + +```markdown +## Update — 2026-04-27 (Layered Process View V1) + +The river-styled SIPOC `ProcessMapBase` is now wrapped by `LayeredProcessView` (`@variscout/ui`), which adds an Outcome band above and an Operations band below. ADR-070 stays canonical for the river/SIPOC design itself; the layered extension adds visual structure around it without changing the data model. + +See the Layered Process View design spec at `docs/superpowers/specs/2026-04-27-layered-process-view-design.md` for band semantics, surface variations, and phasing. (When pasting this snippet into ADR-070, write a real markdown link from `docs/07-decisions/` to that path.) + +V1 (this update) is structural only: the bands wrap the existing component. V2+ phases add Operations band content (snapshot-backed actuals, capability sparklines), Process Hub current-state rendering, and multi-hub aggregation. +``` + +- [ ] **Step 10.2: Update methodology.md to reference the band names** + +Open `docs/01-vision/methodology.md`. In the "Process Learning Levels" section (currently introduces System / Flow / Local mechanism levels), add a small note that the FRAME workspace now exposes these levels as visible bands labelled Outcome / Process Flow / Operations: + +```markdown +The FRAME workspace renders these levels as three visible bands — **Outcome**, +**Process Flow**, and **Operations** — stacked vertically with the river-styled +SIPOC inside the Process Flow band. The visual structure makes the methodology +visible by default. See the Layered Process View design spec at `docs/superpowers/specs/2026-04-27-layered-process-view-design.md`. (When pasting this snippet into methodology.md, write a real markdown link from `docs/01-vision/` to that path.) +``` + +(Add this as a paragraph after the Process Learning Levels table; do not restructure the section.) + +- [ ] **Step 10.3: Update mental-model-hierarchy.md** + +Open `docs/05-technical/architecture/mental-model-hierarchy.md`. In the "What's In Code" or "Per-Phase Detail → FRAME" section, add a row or paragraph noting the layered visual structure: + +```markdown +**Layered band structure:** FRAME renders as three coplanar bands — Outcome / Process Flow / Operations — wrapping the existing river-styled SIPOC inside the Process Flow band. The bands are a render-time projection; no data-model change. See `LayeredProcessView` in `@variscout/ui` and the design spec at `docs/superpowers/specs/2026-04-27-layered-process-view-design.md`. (When pasting this snippet into mental-model-hierarchy.md, write a real markdown link from `docs/05-technical/architecture/` to that path.) +``` + +- [ ] **Step 10.4: Add the design spec reference to docs/llms.txt** + +Open `docs/llms.txt`. In the "Core orientation" or design-spec section, add an entry: + +```text +- docs/superpowers/specs/2026-04-27-layered-process-view-design.md — three-band visual language (Outcome / Process Flow / Operations) for FRAME, Process Hub, and multi-hub +``` + +- [ ] **Step 10.5: Verify docs build cleanly** + +Run: `bash scripts/check-diagram-health.sh` (per memory: docs:check before merge). +Run: `pnpm docs:check` (or whatever the project's docs-check command is — see `package.json`). + +If frontmatter validator complains, fix before committing. + +- [ ] **Step 10.6: Commit documentation updates** + +```bash +git add docs/07-decisions/adr-070-frame-workspace.md docs/01-vision/methodology.md docs/05-technical/architecture/mental-model-hierarchy.md docs/llms.txt +git commit -m "docs: reflect Layered Process View V1 in ADR-070, methodology, mental-model" +``` + +--- + +## Task 11: PR readiness check + final validation + +**Files:** none modified — verification. + +- [ ] **Step 11.1: Run the project's PR-ready check** + +Run: `bash scripts/pr-ready-check.sh` +Expected: All checks pass (tests + lint + docs:check). + +- [ ] **Step 11.2: Confirm git log is clean** + +Run: `git log --oneline main..HEAD` +Expected: One commit per logical task, all with clear messages. If multiple WIP commits exist for one task, that's fine — just confirm the message hygiene is reasonable. + +- [ ] **Step 11.3: Decide on merge path** + +Two paths per the user's tooling/docs commit rule: + +1. **Direct to main** (allowed for docs/tooling per CLAUDE.md): if the bulk of changes are docs + new component without modifying product behavior critically, this works. The new component is additive; the FrameView swap changes behavior visually but the underlying ProcessMapBase is unchanged. +2. **PR + review** (safer, recommended): the FrameView swap touches both apps and changes user-facing chrome, so a PR with subagent code review feels right. Per the project workflow rule for product code: branch → PR → `bash scripts/pr-ready-check.sh` green → subagent code review → squash-merge. + +Recommended: PR path, since this touches `apps/*/src/`. Do not use `gh pr merge --admin`. + +--- + +## Self-Review Checklist (the engineer should run this after Task 11) + +1. **Spec coverage:** every V1 deliverable in the spec maps to a task above: + - V1: "Wrap the existing ProcessMapBase river-SIPOC in a Process Flow band" — Task 3 + - V1: "Add an Outcome band above (initially showing Cpk target if set)" — Task 2 + - V1: "Add an Operations band below (initially showing existing tributaries as factor chips)" — Task 4 + - V1: "Renames 'tributary' → 'factor' in UI strings only; code stays `tributary`" — Tasks 4, 6, 7 (UI strings use "factor", code keeps `tributary`) + - V1: Band labels Outcome / Process Flow / Operations — Task 1 + - Cross-band connector lines: explicitly deferred to V2+ (correctly not in this plan) +2. **Placeholder scan:** no "TBD", "implement appropriate", or vague language. Every step has a concrete code block or command. +3. **Type consistency:** `LayeredProcessViewProps` defined in Task 1 is used in Tasks 2-4. The prop names match `ProcessMapBaseProps`. ✓ +4. **Test patterns:** all tests use `vi.mock` BEFORE component imports (per memory rule). ✓ +5. **Tailwind tokens:** all class strings use semantic tokens (`bg-surface-secondary`, `text-content`, `border-edge`). No hard-coded colors. ✓ +6. **Memory rules covered:** terminology consistency (UI says "factor", code says "tributary" — consciously deferred to follow-up PR per spec), no `Math.random` in new code, vi.mock ordering, no destructive git operations. + +--- + +## Open follow-ups (NOT in V1 — recorded for future plans) + +- V2: Read-only Process Hub current-state overlay using `` +- V2: Cross-band SVG connector lines (requires position coordination with ProcessMapBase — non-trivial) +- V2: Side-sheet preview for cross-investigation evidence flow +- V3: `tributary` → `factor` code rename (separate cleanup PR) +- V3: Per-factor spec data model (`tributary.targetRange?` and `node.designedRate?`) +- V4: Snapshot-backed actuals + Cp/Cpk-over-batches mini-i-charts +- V5: Multi-hub aggregate rendering +- Future: CoScout coaching prompt updates for level-aware guidance (touches ADR-068) +- Future: Way 3 / band × lens grid exploration (requires its own design session) + +--- + +## References + +- Spec: [`docs/superpowers/specs/2026-04-27-layered-process-view-design.md`](../specs/2026-04-27-layered-process-view-design.md) +- Predecessor: [`docs/07-decisions/adr-070-frame-workspace.md`](../../07-decisions/adr-070-frame-workspace.md) +- Predecessor design: [`docs/superpowers/specs/2026-04-18-frame-process-map-design.md`](../specs/2026-04-18-frame-process-map-design.md) +- Brainstorm critique input: `~/.claude/plans/i-would-need-to-drifting-hummingbird.md` +- @variscout/ui CLAUDE.md (functional components, Tailwind tokens, \*Base naming) +- @variscout/core CLAUDE.md (no Math.random, no React imports) +- writing-tests skill (vi.mock ordering) diff --git a/docs/superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md b/docs/superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md index 058e52592..d412b31cd 100644 --- a/docs/superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md +++ b/docs/superpowers/specs/2026-04-26-evidence-sources-data-profiles-design.md @@ -21,7 +21,10 @@ Are we meeting the requirement, what changed, and where should we focus? An **Evidence Source** is the user-facing hub-level source of recurring evidence. A **Data Profile** is the deterministic adapter behind that source -when VariScout recognizes a repeatable source-data shape. +when VariScout recognizes a repeatable source-data shape. Together with stable +measure definitions, targets, subgroup logic, Signal Cards, Survey readiness, +and cadence rules, these snapshots feed the Process Measurement System that +produces Current Process State. This keeps Process Hub evidence workflow first: @@ -42,14 +45,16 @@ This keeps Process Hub evidence workflow first: | **Snapshot** | One dated or imported evidence package from an Evidence Source | | **Profile Application** | Profile version plus confirmed mapping used for one Snapshot | -The future conceptual object names are: +The conceptual object names are: - `EvidenceSource` - `DataProfileDefinition` - `EvidenceSnapshot` - `ProfileApplication` -This design does not introduce code, APIs, or persisted types yet. +These types now exist in core as the first implementation slice. The broader +product workflow is still incomplete: ordinary process datasets do not yet have +a general path to become recurring Process Hub Evidence Sources. ## Evidence Source @@ -101,13 +106,16 @@ upload, append, customer-owned Blob sync, or a future customer-controlled export drop. Snapshot timing is an improvement cadence: manual, shiftly, daily, weekly, or hourly when that fits the process review need. -Snapshots are what the hub cadence board should reason over: +Snapshots are what Current Process State and the hub cadence board should +reason over: - what changed since the last Snapshot - whether requirements are being met - where variation, defects, wait, burden, or 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, + chartered project, sustainment review, or control handoff The same cadence board should support both daily huddles and weekly process reviews. Daily huddles use the latest Snapshot and open investigation metadata @@ -115,9 +123,8 @@ to ask what changed, what needs attention today, and what verification is waiting. Weekly process reviews compare Snapshot history to ask whether the process is meeting requirements, whether recurring focus areas are emerging, and which improvements should be sustained or escalated into focused/chartered -work. Until Phase 5 is implemented, the Azure board may label these meeting -uses but must derive them from existing project metadata rather than claiming -true Snapshot history. +work. The first Snapshot path exists for the Agent Review Log profile; broader +daily/weekly comparison still needs generalized Evidence Source support. ## Profile Application @@ -135,22 +142,21 @@ even when the Evidence Source represents the same process evidence. ## Storage Direction -Current Blob behavior remains project-based until Phase 5 is implemented. This -document reserves the future Process Hub evidence namespace without claiming -current support: +Current Blob behavior remains primarily project-based while Evidence Source +support emerges through narrow profile-specific slices. The logical Process Hub +evidence namespace is: ```text process-hubs/{hubId}/evidence-sources/{sourceId}/snapshots/{snapshotId}/... ``` -The future namespace should hold snapshot files, profile application metadata, -validation reports, and related attachments when the implementation slice needs -them. +The namespace should hold snapshot files, profile application metadata, +validation reports, and related attachments as generalized support expands. ## Non-Goals -- No code, API, schema, or type changes in this documentation update. -- No custom ERP, MES, QMS, CRM, ACD, AI-platform, or workflow integrations. +- No deep or custom ERP, MES, QMS, CRM, ACD, AI-platform, or workflow + integrations. - No live alarms, runtime monitoring, shift-critical escalation, or operational uptime promise. - No separate AI-evaluation product for agent logs. diff --git a/docs/superpowers/specs/2026-04-26-unified-process-hub-methodology-roadmap.md b/docs/superpowers/specs/2026-04-26-unified-process-hub-methodology-roadmap.md index 5c084284f..0dea252cb 100644 --- a/docs/superpowers/specs/2026-04-26-unified-process-hub-methodology-roadmap.md +++ b/docs/superpowers/specs/2026-04-26-unified-process-hub-methodology-roadmap.md @@ -27,6 +27,11 @@ Process Hub is the operating spine for VariScout. It is where recurring process-improvement work lives over time for one line, queue, flow, cell, lab process, service workflow, or development value stream. +For the horizon-level product-method roadmap that places Process Hub inside +the broader progression from one dataset to Process Measurement System, +process learning memory, and CoScout context layer, see +[Product-Method Roadmap](2026-04-27-product-method-roadmap-design.md). + Process Hub does not replace the investigation method. Each investigation still uses the VariScout journey: @@ -39,8 +44,12 @@ The roadmap should treat the product as a nested methodology: | Layer | Role | | -------------------------------- | ------------------------------------------------------------------ | | Process Hub | Operating spine for process-owner cadence and team improvement | +| Process Measurement System | Designed measure, evidence, snapshot, trust, and cadence layer | +| Current Process State | Latest review of outcome, flow, known x-control, and trust signals | | Evidence Sources / Data Profiles | Recurring hub evidence workflow and deterministic source adapters | -| Investigation journey | Method spine for one investigation from concern to verified action | +| Process learning levels | Outcome, flow, and local-mechanism levels of process understanding | +| Investigation journey | Reasoning loop from Current Process State to response | +| Response paths | Quick action, focused investigation, charter, sustainment, handoff | | Question-driven EDA | Reasoning spine that sharpens issue into problem condition | | Survey | Horizontal readiness evaluator across every phase and hub review | | Signal Cards | Signal-level trust records that Survey and branches quote | @@ -51,6 +60,13 @@ This hierarchy keeps VariScout out of custom integrations and 24/7 operational monitoring while still supporting process performance review at an improvement cadence. +Process Hub is the operating loop for how a team improves a process over time. +The Process Measurement System turns recurring evidence into Current Process +State. Current Process State triggers quick action, focused investigation, +chartered improvement, sustainment review, or control handoff. The process +learning levels explain what each loop is learning: outcome, flow, or local +mechanism. + ## Usage Levels The roadmap must serve several levels of product use without turning them into @@ -76,10 +92,22 @@ the team actually owns. At hub level, the recurring question is: ```text -What changed, where should we focus, what is waiting for action or verification, -and what should be sustained? +What is the Current Process State, what changed, what needs attention, and +which response path fits? ``` +### Process Measurement System And Current Process State + +The Process Measurement System is the designed layer behind Process Hub cadence: +stable measure definitions, Evidence Sources, Snapshots, targets, subgroup +logic, known x-control measures, Signal Cards, Survey readiness, and cadence +rules. + +Current Process State is the review surface produced from that system. It +should show outcome, flow, known x-control, capability structure, and trust +measures. Capability state should distinguish Cpk vs target Cpk, Cp-Cpk gap, +Cp/Cpk movement across process-rational windows, and sample/trust warnings. + ### Evidence Sources And Data Profiles Evidence Sources are the hub-level sources of recurring evidence that answer @@ -96,7 +124,37 @@ Snapshot. See FRAME, SCOUT, INVESTIGATE, and IMPROVE remain the investigation spine. They describe how one issue moves from concern to evidence-backed action and -verification. +verification. In Process Hub use, investigations are the reasoning loop between +Current Process State and response. They can discover a new x, check which +known x changed, validate a suspected mechanism, scope the problem, resolve +trust gaps, verify action effectiveness, or decide escalation. + +### Response Paths + +Process Hub cadence should route attention into five response paths: + +| Response path | Meaning | +| ----------------------------- | ----------------------------------------------------------------------- | +| Quick team action | Low-risk local action that can be done and verified quickly | +| Focused investigation | Bounded investigation when mechanism, subgroup, trust, or scope is open | +| Chartered improvement project | Formal project when impact, risk, ownership, or resources require it | +| Sustainment review | Periodic check that a verified improvement is still visible | +| Control handoff | Acknowledgement that live control belongs in another system | + +### Process Learning Levels + +Every investigation and cadence review should be readable through three levels: + +| Level | Question | +| -------------------------- | ---------------------------------------------------------------- | +| System / outcome | What result must the customer or business experience? | +| Flow / process model | What flows through which steps, at what rate, and where is loss? | +| Local mechanism / evidence | What physics, recipe, condition, or measurement issue explains? | + +FRAME's process map is a flow-level lens. Capability, Process Flow, Yamazumi, +Defect, Performance, and Standard EDA are instrument sets that help the user +move between levels. See +[Process Learning Operating Model](2026-04-27-process-learning-operating-model-design.md). ### Question-Driven EDA @@ -138,7 +196,7 @@ authority. ### Phase 2 - Process Owner Cadence UX - Evolve the selected Process Hub review surface into a cadence workspace. -- Show latest signals, Quick / Focused / Chartered work, overdue actions, +- Show Current Process State, response-path routing, overdue actions, verification queue, next moves, and sustainment candidates. - Keep the implementation Azure-only and reuse existing Process Hub metadata. @@ -162,8 +220,9 @@ authority. confirmation, snapshot history, and validation. - Define customer-owned snapshot contracts for data teams and consultants. - Document Data Profile contracts, including `EvidenceSource`, - `DataProfileDefinition`, `EvidenceSnapshot`, and `ProfileApplication` as - future conceptual objects. + `DataProfileDefinition`, `EvidenceSnapshot`, and `ProfileApplication`. These + types now exist in core, but the general product workflow is still incomplete + beyond the first profile-specific slice. - Connect Snapshots to cadence review signals, Survey readiness, investigation attachment, action verification, and sustainment handoff. - Make daily huddle and weekly process review horizons explicit: v1 cadence @@ -183,9 +242,10 @@ authority. ## Acceptance Criteria -1. A reader can explain the difference between Process Hub, Evidence Sources, - Data Profiles, Snapshots, the investigation journey, question-driven EDA, - Survey, Signal Cards, and sustainment handoff. +1. A reader can explain the difference between Process Hub, Process Measurement + System, Current Process State, Evidence Sources, Data Profiles, Snapshots, + response paths, the investigation journey, question-driven EDA, Survey, + Signal Cards, and sustainment handoff. 2. User journeys describe quick analyst work, process-owner cadence, multi-hub GB/BB work, PWA training, evidence-source enablement, and sustainment/control. diff --git a/docs/superpowers/specs/2026-04-27-layered-process-view-design.md b/docs/superpowers/specs/2026-04-27-layered-process-view-design.md new file mode 100644 index 000000000..c666bb375 --- /dev/null +++ b/docs/superpowers/specs/2026-04-27-layered-process-view-design.md @@ -0,0 +1,348 @@ +--- +title: Layered Process View — Three-Band Visual Language +audience: [product, designer, engineer, analyst] +category: design-spec +status: draft +related: + [ + methodology, + process-hub, + process-learning-operating-model, + product-method-roadmap, + frame-process-map, + evidence-sources, + investigation-wall, + eda-mental-model, + adr-070, + ] +date: 2026-04-27 +--- + +# Layered Process View — Three-Band Visual Language + +## Scope + +This is a **visual-language / design spec**, not a full implementation plan. It defines the three-band layout, per-surface render rules, vocabulary, and a phased implementation direction grounded in existing FRAME / ProcessMap code. Detailed interaction model, drag/drop semantics, mobile responsive behavior, and per-band visual tokens are out of scope and belong to follow-up specs. + +## Summary + +A three-band visual language for understanding a process across outcome, designed flow, and actual operations. The bands stack vertically; process steps align in vertical columns; the Makigami-style insight ("the gap between design and reality") becomes a vertical reading. The same shape appears in three surfaces with different scope and writability: + +- **FRAME** — design-time, writable. Match process knowledge to data inventory; expose gaps. +- **Process Hub current-state** — read-time, snapshot- and cadence-state-driven. Cadence review. +- **Multi-hub view** — portfolio scope. Cross-process pattern scan without false aggregation. + +This spec extends the river-styled SIPOC FRAME workspace ([ADR-070](../../07-decisions/adr-070-frame-workspace.md)). The river-SIPOC stays inside the Process Flow band; the layered design adds Outcome above and Operations below. Existing `ProcessMap`, `ProcessMapBase`, `FrameView`, `detectGaps`, `inferMode`, and subgroup-axis infrastructure are reused, not replaced. + +## Context + +The April 2026 spec wave (operating model + product-method roadmap) named "Process Learning System" and three process-learning levels (system / outcome → flow / process model → local mechanism / evidence) but did not specify how the levels render visually or how they integrate with existing surfaces. ADR-070 and the Investigation Wall already exist as design-time and investigation surfaces. ADR-070's underlying motivation — _"the methodology was invisible at the moments users most need it"_ — points directly at what's missing: **Watson's three-level Gamba thinking needs a visible shape in the product.** + +A brainstorm with the product owner produced this design. + +## Three-band model + +### OUTCOME band — the outcome we want + +Standard performance metrics that compare across processes. Strategic / business framing. Watson called this _"productivity, units per time, rate, standards"_ — generic outcome measures. + +**Content:** + +- Productivity / throughput per period +- Target Cpk +- Strategic context (sustainment status at process level, response-path summary) +- Customer / business requirement framing + +**Not in this band:** + +- The customer's specific experience definition (that's at Process Flow's ocean as CTS) +- Spec values (USL/LSL/target — those are Operations) + +### PROCESS FLOW band — the designed dynamic process + +The river-styled SIPOC topology _populated_ with designed dynamics. Watson's _"Level 2 should be a flow rate. A combination of different rates."_ + +**Content:** + +- Steps with names (the activities) +- Flow direction (left → right) +- Designed flow rate per step or per arc (units/hr, takt) — _requires data-model addition; see Data Model Gaps_ +- Designed wait/delay times between steps — _requires data-model addition_ +- Bottleneck markers (slowest step highlighted) — _derived from designed rates once present_ +- CTQ measurement points placed on steps +- CTS marker at the ocean (right end) — the customer experience target +- Sequencing and logic structure + +**Not in this band:** + +- Spec values (USL/LSL/target) — Operations +- Actual measurements — Operations +- Factor data — Operations (factors live at Operations as factor chips with cross-band connectors) + +### OPERATIONS band — actual control + specs + actuals + +Everything operational: factor inputs (formerly tributaries), their specs, their actuals, capability metrics, events, gemba, signal cards, trust. Watson's _"X flowing with time at the 3rd tier"_ and _"real world connections."_ + +**Content (full vision; phased per the implementation direction below):** + +- **Factor chips** (formerly tributaries) per step — one per process input/X +- **Specs per factor**: USL / LSL / target / target Cpk / designed operating window +- **Snapshot-backed actuals per factor**: latest values, current Cp/Cpk +- **Cp/Cpk-over-batches mini-i-chart** per step (Watson's design from the second transcript: each batch produces one Cp/Cpk point; the i-chart of these over time IS the capability-stability view) +- **Recipe deviations** — actual factors outside their designed operating windows +- **Process-scoped observations**: events, Signal Cards, gemba notes, MSA records +- **Trust signals**: sample size, n<30 warnings, MSA freshness, subgroup integrity + +**Render-mode variation by surface** (see "Surfaces" below): + +- Config mode (FRAME): factor chips as drag targets, spec entry fields, subgroup axis selector +- Snapshot/cadence mode (Process Hub current-state): factor chips with spec/actual badges, capability sparklines, response-path triggers — based on latest cadence-state data, not live monitoring +- Aggregate mode (multi-hub): per-hub state badges only + +**VariScout is not live monitoring.** All "actual" data in Operations comes from snapshots and cadence-state items. Updates happen at the cadence the customer chooses (hourly, shiftly, daily, weekly). + +## Cross-band design + +**Vertical step alignment.** Each process step in Process Flow has a vertical column descending into Operations. Factor chips at Operations align under the step where the factor enters. Reading vertically per step shows: declared Process Flow content (CTQs, designed rate) → actual Operations content (factors, specs, current Cp/Cpk). + +**Cross-band connector lines.** Subtle dashed lines from each Operations factor chip up to the corresponding Process Flow step. The lines visually answer "which step does this factor connect to?" + +**Capability gaps as vertical reads.** Step 2 designed for 180/hr (Process Flow) operating at 165/hr (Operations) — the vertical gap IS the methodology made visible. The same vertical read shows USL/LSL designed (Operations spec) vs. actual values (Operations actuals). + +## Surfaces + +The same `` composed view renders in three surfaces with mode-specific Operations content. + +### Component placement + +- **Pure chart primitives** (band rendering, river-SIPOC, factor chip glyph, mini-i-chart sparkline) live in `@variscout/charts` alongside existing `EvidenceMap` and `ProcessMap` primitives. +- **Composed writable view** (``) lives in `@variscout/ui` because it composes interactive controls (drag/drop, spec inputs, factor mapping). This matches the existing pattern: `ProcessMapBase` is in `@variscout/ui` while raw map primitives are in `@variscout/charts`. +- **App wrappers** (`FrameView`, `ProcessHubCurrentStatePanel`, multi-hub view) consume `` and pass surface-specific props (mode, data sources, response-path callbacks). + +### FRAME workspace (design-time, writable) + +Primary user job: **match process knowledge to data inventory; expose gaps.** + +The user has two implicit lists: + +- "Things that could affect outcomes at step N" — process knowledge (CTQs declared) +- "Columns I have in this Excel" — data inventory (factor data available) + +The FRAME workflow puts these side-by-side at the right step: + +1. **Data ingestion** — columns appear as unmapped factor candidates +2. **Build Process Flow** — name steps, set order, declare CTQs per step (process knowledge entry) +3. **Map columns to steps** — drag each candidate factor chip into its step's column under Operations +4. **Set specs** — per factor, define USL / LSL / target / operating window (V3+ once data-model supports it; see Data Model Gaps) +5. **Inspect gaps** — every step's vertical read shows what's complete and what's missing +6. **Decide on each gap** — ignore (CTQ doesn't matter), collect data (measurement plan), or remove from CTQ list + +Gap categories made visible (with current `detectGaps()` implementation): + +- CTQ declared in Process Flow with no factor in Operations → "no data for this CTQ" +- Factor in Operations with no CTQ binding → "data column not yet linked to process knowledge" +- CTS at ocean with no Cpk target → "target Cpk not set" (already detected) + +Gap categories that need data-model additions before they can render: + +- Factor in Operations with no spec → needs per-factor spec data model +- Step with no designed flow rate → needs per-step rate data model + +### Process Hub current-state (read-time, cadence-state) + +Primary user job: **cadence review — see what's drifting; choose response path.** + +The Process Flow band is the same shape as in FRAME (the process is fixed; it doesn't redesign itself). The Operations band shifts to read-mode against the latest cadence-state data: + +- Factor chips show **state badge** (green/amber/red vs. spec compliance) — initially aggregated from existing `CurrentProcessState` items; per-factor actuals later +- Capability mini-i-charts show Cp/Cpk **over recent snapshots** — phased; not in V1 +- Recent events / Signal Cards / gemba notes from last cadence period +- Trust indicator per factor (suppress conclusions when trust is low) — phased +- One-click affordance per anomaly to start an investigation, mark as quick action, enter sustainment review, or hand off (response-path routing) + +Response-path chip placement: per-anomaly affordance docked to the anomalous factor chip; summary roll-up in the Outcome band footer ("3 quick actions / 2 focused investigations / 1 charter open"). + +### Multi-hub view (portfolio scope) + +Primary user job: **cross-process pattern scan without false aggregation.** + +The layered shape persists, but heavily summarized: + +- Outcome band: portfolio rollup (counts, status mix) +- Process Flow band: collapsed to one row per hub (hub name, overall state) +- Operations band: per-hub state badge (green/amber/red); click to expand to that hub's full Hub current-state + +**Aggregation rule** (ties to A3 of the critique on Cp/Cpk additivity): the multi-hub view never sums Cp/Cpk across hubs. It shows distributions or per-hub badges. The "no false aggregation" rule is structural: the multi-hub Operations band has no "summed Cpk" or "average capability" widget by design. + +## Reconciliation with existing `ProcessStateLens` + +Code today defines `ProcessStateLens = 'outcome' | 'flow' | 'conversion' | 'measurement' | 'sustainment'` in `packages/core/src/processState.ts:10`. The new 3-band model is `Outcome | Process Flow | Operations`. Mapping: + +| `ProcessStateLens` (existing 5-lens) | 3-band placement | Notes | +| ------------------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `outcome` | **Outcome band** | Direct map | +| `flow` | **Process Flow band** | Direct map | +| `conversion` | **Process Flow band** (designed) AND **Operations band** (actual) | "Conversion" = how the process transforms entities. Designed conversion (recipe spec) is Process Flow; actual conversion (measured at CTQ points) is Operations. Conceptually wants splitting; in V1 keep `conversion` items at Operations as "what's happening in the conversion" | +| `measurement` | **Operations band** | Direct map | +| `sustainment` | **Outcome band** | "Did the improvement hold?" is an outcome question over time | + +**V1 strategy: don't rename the lens enum.** The 3-band visual is a _render-time_ projection over the 5-lens taxonomy. Each lens item is positioned in the correct band by the renderer. This keeps `ProcessStateLens`, `lensCounts`, and existing Process Hub aggregation working unchanged. + +**V2+ option: converge `conversion` into `operations`.** Once the 3-band model is settled and `conversion` items can all be re-classified as `measurement`-or-similar, deprecate `conversion` and rename the enum to align. Not in V1 scope. + +## Six user needs the Operations band serves + +| # | Need | Render | Phase | +| --- | --------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------- | +| 1 | "Is the process running OK right now?" | Traffic-light per factor based on spec compliance | V2 (needs spec data) | +| 2 | "Where did this anomaly come from?" (Watson's trace-back) | Click-to-trace; highlight upstream factors and what changed when | V4 (needs snapshot history) | +| 3 | "Can I trust this Cp/Cpk?" | Trust indicator: sample size, MSA, n<30 warning. Suppress conclusions on low trust. | V4 (needs trust data) | +| 4 | "How is capability evolving?" | Cp/Cpk-over-batches mini-i-chart per step | V4 (needs Cp/Cpk-over-time records) | +| 5 | "Should I act now or investigate?" | Response-path chip suggestions per anomaly | V2 (anomaly = current `CurrentProcessState` item) | +| 6 | "Where in the process is this?" | Vertical alignment from Operations factor chip up to Process Flow step | V1 (the layout itself) | + +## Evidence scope (load-bearing for Process Hub current-state) + +The Operations band in Hub current-state aggregates evidence across investigations on the same process. The data model is **tiered by artifact type and status**: + +| Artifact | Scope | Rationale | +| ----------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------- | +| Hypotheses, gates, contribution trees, problem statement | **Investigation only** | These are the structure of one reasoning attempt — not reusable as-is | +| Findings at status `observed` / `investigating` | **Investigation only** | Rough observations from one drill-down; may not survive scrutiny | +| Findings at status `analyzed` and above | **Promoted to process** | Status `analyzed` means "verified contribution to understanding" | +| Gemba notes, Signal Cards, MSA records, recipe observations | **Process from inception** | Observations about the actual process, not interpretations of an analysis | + +**Hub Operations band aggregation rule:** + +- Always show: gemba notes, Signal Cards, MSA records, recipe observations (process-scoped from inception) +- Show: findings with status ≥ `analyzed` from any investigation on this hub +- Hide: investigation-scoped artifacts (hypotheses, in-progress findings, one project's gates) + +**Implementation approach (no `hubId` field needed initially):** derive hub membership from existing project metadata. The Hub view already has access to its member projects' state; aggregating findings at status ≥ `analyzed` across them is a `selectProcessRelevantFindings(hubId)` selector that walks the Hub's project list and filters per status. A `hubId` reference on findings can be added later if perf or query semantics demand it; not required for V1. + +## Vocabulary changes + +Per [Process Learning Operating Model](2026-04-27-process-learning-operating-model-design.md) line 478–479 which already sanctions internal/external split: + +| Old (UI) | New (UI) | Code | +| --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Tributary | **Factor** | `tributary` stays internal in V1 — rename to `factor` is a separate follow-up PR that touches ADR-070, Wall spec, processMap types. UI strings change first; code rename is sequenced separately. | + +## Data Model Gaps + +Current `ProcessMap` has: `nodes`, `tributaries` (factors), `ctqColumn`, `ctsColumn`, `subgroupAxes`, `hunches`. The full vision needs the following additions, none of which exist today: + +| Gap | Needed for | Phase to add | +| ----------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------ | +| Per-factor spec / operating window (USL/LSL/target/range per tributary) | Operations band specs; gap detection of "factor without spec" | V3 | +| Per-step designed flow rate / wait / takt | Process Flow band rate labels and bottleneck detection | V3 | +| Per-step CTQ list (separate from `ctqColumn` for the whole process) | Multiple CTQs per step, gap detection of "CTQ without factor" | V3 | +| Snapshot-backed actuals (factor latest values per snapshot) | Operations band actuals and Cp/Cpk per batch | V4 | +| Cp/Cpk-over-batches records by step / factor | Capability mini-i-chart | V4 | +| Process-scoped gemba/MSA/recipe observations (separate from investigation findings) | Operations band non-investigation evidence | V4 | +| Factor-to-CurrentProcessState item binding | Linking state items to specific factors at specific steps | V2 | + +V1 and V2 use only what's already in `ProcessMap` plus the existing `CurrentProcessState` items. V3 adds the minimum data model for designed operating windows and per-step rates. V4 adds snapshot-backed actuals and capability-over-time. V5 is multi-hub. + +## Phased Implementation Direction + +Each phase ships independently. V1 is the minimum slice that delivers user value (visible bands without new data model). + +### V1 — Layer existing FRAME map into three visual bands + +- Wrap the existing `ProcessMapBase` river-SIPOC in a Process Flow band. +- Add an Outcome band above (initially showing Cpk target if set, plus simple metadata from `CurrentProcessState` outcome lens). +- Add an Operations band below (initially showing existing `tributaries` as factor chips, with cross-band connector lines to their parent step). +- No new data model. Read/write only what `ProcessMap` already supports. +- Renames "tributary" → "factor" in UI strings only; code stays `tributary`. +- Outcome label: **"Outcome"**; middle: **"Process Flow"**; bottom: **"Operations"**. + +### V2 — Read-only Process Hub current-state overlay + +- Add `` rendering in `ProcessHubCurrentStatePanel.tsx`. +- Operations band populates from existing `CurrentProcessState` items grouped by lens, projected into the 3-band model (per the reconciliation table above). +- Factor chips show state badges from the parent state items (no per-factor actuals yet). +- Response-path chip placement per anomaly: docked to the anomalous factor chip; summary in Outcome band footer. + +### V3 — Minimal data model for factor operating windows / specs + +- Add `factor.targetRange?` (or equivalent) to `ProcessMap.tributaries[]`. Optional field; existing maps load unchanged. +- Add per-step CTQ list as `node.ctqs?: string[]` (factor IDs). Optional. +- Add `node.designedRate?` for designed flow rate at step level. +- Update `detectGaps()` to recognize the new fields and surface gap rows: "factor without spec", "step without designed rate", "step CTQ without factor binding". +- FRAME UI gains spec entry per factor and rate entry per step. + +### V4 — Snapshot-backed actuals, trust, capability-state mini charts + +- Wire existing snapshot system (`evidenceSources` for Agent Review Log; general path TBD) into Operations band. +- Per-factor latest actuals appear in factor chips. +- Cp/Cpk per snapshot is computed and recorded; the i-chart-over-batches becomes a mini sparkline in each step's Operations column. +- Trust indicator per factor (n<30 warning, MSA freshness). + +### V5 — Multi-hub pattern scan + +- Aggregate-mode rendering of the layered view at portfolio scope. +- Per-hub state badges; no Cp/Cpk aggregation (the no-false-aggregation rule). +- Cross-process pattern primitives: distribution comparison, hub-by-hub state matrix. + +## Resolved design decisions (from brainstorm) + +These were open questions during the brainstorm; all are now resolved. They land in the implementation phases as called out: + +| # | Decision | Phase | +| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| 1 | **Code rename `tributary` → `factor`** is a **separate cleanup PR before V3**. UI strings change in V1; code rename is sequenced as its own PR (touches ADR-070, Wall spec, ProcessMap types). | between V1 and V3 | +| 2 | **Empty states**: all three bands always render; empty bands show inline placeholder text ("No outcome data yet" / "No factors mapped yet"). Layout stays consistent across full and empty states; first-time users see the three-level structure even before data. | V1 | +| 3 | **Animation / motion on Process Flow band**: static by default. User toggle to enable subtle flow-direction dashes. `prefers-reduced-motion` overrides to always-static. Accessibility-first; methodologically meaningful when on. | V2+ (toggle is post-V1) | +| 4 | **Mode × level interaction (V1)**: existing modes drive band content; bands always visible. Each mode has a primary band of focus + supporting content in others. Bands are structural; modes select which content fills each band. (See Future Directions for Way 3.) | V1 | +| 5 | **Capability mode in the layered context**: subsumed by decision 4 — Capability mode emphasizes Operations band's Cp/Cpk content (factor chips show Cp/Cpk badges; mini-i-chart of Cp/Cpk-over-batches becomes prominent). Outcome band shows Cpk vs target. Process Flow band shows step-level Cpk if data is available. | V1 / V4 | +| 6 | **Cross-investigation evidence flow UI**: click a finding chip → side sheet docks with read-only preview (finding context, source investigation reference, snapshot context). Side sheet has "open in project" button that nav-replaces to that investigation. Pattern: quick context without losing place; full nav when needed. | V2 | + +## Future directions + +These are aspirational candidates for V3+ that require their own design exploration before commitment. They are _not_ part of this spec's scope but are recorded so the design vocabulary doesn't paint itself into a corner. + +### Band × Lens grid (Way 3) + +The Four Lenses (CHANGE / FLOW / FAILURE / VALUE — pedagogical labels per `mental-model-hierarchy.md`, not in code today) could be folded with the three bands into a 3 × 4 grid. Each cell = one analytical view. Current six modes become emergent shortcuts (named (band, lens) presets): + +| | CHANGE (I-Chart) | FLOW (Boxplot) | FAILURE (Pareto) | VALUE (Capability) | +| ---------------- | ---------------------------------------------- | ----------------------------------------------- | ---------------------------------------------- | --------------------- | +| **Outcome** | Outcome trend over time | Outcome distribution | Top-N outcome failures | Outcome Cpk vs target | +| **Process Flow** | Throughput trend; Yamazumi-style time-trend | Step-level variation; Performance multi-channel | Failure concentration per step | Step-level Cp/Cpk | +| **Operations** | Cp/Cpk-over-batches (=current Capability mode) | Factor variation (=current Standard mode) | Defect rates per factor (=current Defect mode) | Cp/Cpk per factor | + +This would unify modes and lenses under one mental model. **Requires careful end-to-end thinking across use cases and user personas before commitment** — not a V1 add. Worth its own ADR + design spec when explored. + +### Other candidates worth exploring later + +- Animated flow on Process Flow band as a methodology teaching aid (only when motion is on) +- Mode-as-contextual-suggestion (Way 2 from the brainstorm) if Way 1 feels too disconnected after V1 lands +- Smart band-emphasis based on entry path (Routine Check defaults to Outcome focus; Problem to Solve defaults to Operations focus) + +## Out of scope + +Explicitly not in this spec, deferred to follow-up specs: + +- Investigation Wall layered-or-not decision (Wall keeps current structure) +- Real-time / live presence on the Hub Operations band — VariScout is not live monitoring +- Detailed FRAME drag/drop interaction model (drop targets, error states, undo) +- Mobile / responsive collapse implementation +- CoScout coaching prompt updates for level-aware guidance (touches ADR-068) +- `tributary` → `factor` code rename (separate PR; touches ADR-070, Wall spec, ProcessMap types) +- Renaming `ProcessStateLens` to align with 3-band model (V2+ migration) + +## References + +- [Process Learning Operating Model](2026-04-27-process-learning-operating-model-design.md) — three-level methodology this design renders +- [Product-Method Roadmap](2026-04-27-product-method-roadmap-design.md) — maturity horizons; this design lands in H1 (state-to-response actionability) +- [FRAME Workspace](2026-04-18-frame-process-map-design.md) and [ADR-070](../../07-decisions/adr-070-frame-workspace.md) — predecessor; the river-SIPOC stays inside Process Flow band; existing `ProcessMap` / `ProcessMapBase` / `FrameView` / `detectGaps` / `inferMode` / subgroup axes are reused +- [Investigation Wall](2026-04-19-investigation-wall-design.md) — separate paradigm (hypothesis-centric), out of scope here +- [EDA Mental Model](../../01-vision/eda-mental-model.md) — Y/X/x three-level structure that the bands generalize +- [Methodology](../../01-vision/methodology.md) — "Process Learning Levels" section maps Y/X/x to System/Flow/Local-mechanism; this design renames to Outcome/Process Flow/Operations +- `packages/core/src/processState.ts` — existing `ProcessStateLens` enum reconciled in this spec +- Devil's-advocate critique at `~/.claude/plans/i-would-need-to-drifting-hummingbird.md` — input artifact that drove this brainstorm; full transcript-vs-spec drift memo at Section G + +## Implementation plan + +V1 implementation plan: [`2026-04-27-layered-process-view-v1.md`](../plans/2026-04-27-layered-process-view-v1.md) — 11 tasks covering the new `` component, FRAME app-wrapper swaps in PWA + Azure, end-to-end verification, and documentation updates (ADR-070 amendment, methodology.md, mental-model-hierarchy.md, llms.txt). diff --git a/docs/superpowers/specs/2026-04-27-process-learning-operating-model-design.md b/docs/superpowers/specs/2026-04-27-process-learning-operating-model-design.md new file mode 100644 index 000000000..5f2cdf5fe --- /dev/null +++ b/docs/superpowers/specs/2026-04-27-process-learning-operating-model-design.md @@ -0,0 +1,490 @@ +--- +title: Process Learning Operating Model +audience: [product, designer, engineer, analyst] +category: design-spec +status: draft +related: + [ + methodology, + process-hub, + question-driven-eda-2, + frame-process-map, + evidence-sources, + data-profiles, + process-flow, + yamazumi, + capability, + survey, + signal-cards, + sustainment, + ] +date: 2026-04-27 +--- + +# Process Learning Operating Model + +## Summary + +VariScout should be designed as a process learning system, not as a collection +of statistical modes. The Process Hub is the operating home for one process. A +Process Measurement System converts recurring evidence into Current Process +State. Current Process State then triggers quick actions, investigations, +charters, sustainment checks, or handoffs. + +The strongest methodology insight is the Makigami-style three-level view of +process understanding: + +1. **System / outcome level** - what the customer or business must experience. +2. **Flow / process model level** - what flows through which steps, at what + rate, with which waits, handoffs, and bottlenecks. +3. **Local mechanism / evidence level** - the actual physics, recipe, + equipment, material, operator, environment, subgrouping, and evidence behind + the flow. + +The current SIPOC-style FRAME process map remains useful, but it is one lens +inside this model. It should not become the whole method. The product should +help a team move from one dataset to process understanding, then to repeatable +Evidence Sources, Current Process State, Process Hub cadence, and +sustainment/control handoff. + +## Product Thesis + +VariScout's wedge is not deep integration into ERP, MES, QMS, or BI systems. +The wedge is structured process learning from customer-owned evidence. + +```text +downloaded export -> dataset -> investigation project -> process understanding +-> recurring Evidence Source -> Current Process State -> response path +-> updated measurement system +``` + +This keeps the product aligned with the current architecture: + +- **Interface, not integration.** CSV and Excel exports are valid first-class + evidence. VariScout should not start by writing SQL against customer systems. +- **Process learning before statistics.** Statistics are instruments for + answering process questions. They are not the product's primary mental model. +- **Customer-owned data.** Browser processing, local cache, and customer-tenant + Blob Storage remain the trust boundary. +- **Deterministic authority.** The stats engine, Survey, Signal Cards, and + user-confirmed evidence remain authoritative. CoScout explains and drafts. +- **Quality systems are not improvement systems.** FDA, ISO, QMS, and BI + dashboards can protect consistency or visibility, but they do not by + themselves create durable process learning. +- **Shared process context.** Process Hub artifacts should be readable by + humans and structured enough for CoScout grounding without promising an open + AI-agent platform. + +## Core Vocabulary + +| Concept | Meaning | +| ------------------------------ | ----------------------------------------------------------------------- | +| **Process Learning System** | VariScout's overall product thesis: structured learning from evidence | +| **Process Hub** | Operating home for one process, team, cadence, and accumulated learning | +| **Process Measurement System** | Designed measures, evidence sources, snapshots, trust, and cadence | +| **Current Process State** | Latest process-owner review surface across outcome, flow, x, and trust | +| **Investigation** | Structured reasoning loop from Current Process State to response | +| **Response Path** | Quick action, focused investigation, charter, sustainment, or handoff | +| **CoScout** | Product assistant grounded in shared process context | + +The customer-facing promise should stay practical: VariScout creates a shared, +evidence-backed process context for teams, and CoScout uses that context to +explain, draft, and guide investigation work. Internally, every durable Process +Hub artifact should be structured for both human review and CoScout grounding: +readable, evidence-linked, deterministic-stat aware, and customer-owned. + +## Operating And Problem-Solving Loops + +The core operating loop is: + +```text +Process Measurement System +-> Current Process State +-> trigger / prompt +-> investigation or immediate response +-> response path +-> updated Process Measurement System +``` + +The distinction matters for product design: + +| Loop | Product expression | +| ---------------------------------- | ------------------------------------------------------------------------- | +| Process operating loop | Process Hub cadence, Current Process State, Evidence Sources, sustainment | +| Investigation problem-solving loop | FRAME -> SCOUT -> INVESTIGATE -> IMPROVE | +| Evidence learning loop | Snapshot -> Signal Cards -> Survey readiness -> updated source contract | +| Response loop | Quick action, focused investigation, charter, sustainment, or handoff | +| Shared process-context loop | Human review and CoScout grounding over the same evidence-backed records | + +Historical note: Xerox Leadership Through Quality is a useful analogy because +it distinguished process improvement work from specific problem solving. It is +not a template to copy, and VariScout should not use QIP/PSP as the primary +product language. + +## Process Measurement System And Current Process State + +Current Process State is not a claim that the process is stable. It is the +latest structured read of the process measure system: + +| Measure family | What it answers | +| ---------------------------- | --------------------------------------------------------------------------- | +| **Outcome / Y measures** | Are we meeting the customer, business, or specification requirement? | +| **Capability structure** | Is the issue spread, centering, subgroup movement, or gap to target Cpk? | +| **Flow measures** | Is the process moving as expected through rate, wait, queue, or bottleneck? | +| **Known x-control measures** | Are known controllable drivers inside their expected operating window? | +| **Trust measures** | Can we trust the current reading, sample, subgroup, MSA, or source mapping? | + +For capability, the Current Process State should distinguish: + +- **Cpk vs target Cpk** - whether current performance is good enough. +- **Cp-Cpk gap** - how much potential capability is lost through centering. +- **Cp/Cpk over subgroups or snapshots** - how capability itself is moving. +- **sample size, power, and measurement trust** - whether the conclusion is + safe enough to act on. + +The Process Measurement System is the designed layer underneath that state. It +includes stable measure definitions, Evidence Sources, Data Profiles, +Snapshots, Signal Cards, Survey readiness, subgroup logic, targets, and cadence +rules. Investigations improve the system by adding, validating, retiring, or +refining measures, known x's, trust rules, controls, and response logic. + +## The Three Levels + +The process-learning levels generalize the existing three-level EDA and +problem-solving model: + +| Existing investigation language | Product-wide process-learning language | +| ------------------------------- | -------------------------------------- | +| Y: problem condition | System / outcome | +| X: where it concentrates | Flow / process model | +| x: local mechanism | Local mechanism / evidence | + +The Process Flow lens has a parallel translation: line level, station level, +and activity level. The question tree can still stop at three levels for UX +clarity, but the reason is methodological: the user is moving from outcome to +flow to local mechanism. + +### 1. System / Outcome Level + +This level asks: + +```text +What result must the process deliver, who owns it, and is it meeting the +requirement? +``` + +Typical users: + +- process owner +- OpEx lead +- GB/BB +- sponsor +- quality or operations leader + +Typical evidence: + +- CTS / Y-of-Ys +- customer or business requirement +- process owner cadence +- current capability or service level +- open verification and sustainment items +- Process Hub rollup across investigations and Evidence Sources + +Product surfaces: + +- Process Hub +- cadence review +- Survey rollup +- sustainment/control handoff +- report summary + +### 2. Flow / Process Model Level + +This level asks: + +```text +What entity flows through which steps, at what rate, and where does the flow +lose time, quality, or capacity? +``` + +Typical users: + +- process engineer +- lean practitioner +- local process owner +- analyst +- team lead + +Typical evidence: + +- process steps +- CTQ per step +- throughput, rate, cycle time, lead time, wait time +- bottleneck and handoff evidence +- step-level factors and input conditions +- Process Flow and Yamazumi linkage + +Product surfaces: + +- FRAME process map +- Process Flow +- Yamazumi full-line or scoped-step view +- flow clues in QDE 2.0 branches +- measurement-gap report + +The existing SIPOC-style map belongs here. It should become a flow lens that can +be read as SIPOC, Y=f(x), or Makigami flow, depending on the user's task. + +### 3. Local Mechanism / Evidence Level + +This level asks: + +```text +What local mechanism, recipe, setting, condition, or measurement issue explains +the pattern? +``` + +Typical users: + +- local process owner +- operator or gemba observer +- maintenance or process expert +- quality engineer +- data analyst + +Typical evidence: + +- recipe, procedure, sequence, delay, and settings +- equipment class, material state, operator practice, environment +- rational subgroup axis +- sample size, power, and measurement trust +- gemba and expert validation +- Cp/Cpk over samples or subgroups +- Cp-Cpk gap as centering loss + +Product surfaces: + +- Investigation Wall / Mechanism Branches +- Signal Cards +- subgroup capability +- gemba and expert validation tasks +- local Yamazumi activity detail +- Survey power/trust recommendations + +This is where process physics matters. Granulation, coating, and nanoforming may +share a higher-level product family, but they are not the same local process. +The local owner owns the physics, recipe, constraints, and operating conditions. + +## Global And Local Ownership + +The model should make ownership visible. + +| Role | Owns | +| -------------------- | --------------------------------------------------------------------------- | +| Global process owner | comparable outcomes, common metrics, portfolio patterns, standards, cadence | +| Local process owner | process physics, recipe, constraints, operating windows, local improvement | +| Analyst / GB / BB | evidence quality, structured investigation, statistical interpretation | +| Gemba contributor | observations, photos, checks, local facts, task completion | +| Data / admin partner | export contracts, snapshot files, Blob Storage, profile enablement | +| Sponsor | priority, resources, charter decision, whether to improve or sustain | + +VariScout should support comparison without false aggregation. For example, a +global owner can compare capability patterns across tabletting families, but +Cp/Cpk from unrelated local processes should not be treated as additive. + +## Analysis Modes Become Instrument Sets + +The current modes remain useful implementation instruments, but the user-facing +question changes from "which mode?" to "what level and question are we working +on?" + +| Instrument set | Primary level | Primary question | +| -------------- | --------------------------------- | ---------------------------------------------------------- | +| Standard EDA | Outcome -> flow -> local evidence | Where does variation concentrate? | +| Capability | Outcome and local evidence | Is the process meeting spec consistently? | +| Performance | Outcome and flow | Which channel, head, cavity, or line is weakest? | +| Defect | Outcome and flow | Where do failures concentrate and what burden do they add? | +| Process Flow | Flow | Where does time, rate, wait, or bottleneck loss live? | +| Yamazumi | Flow -> local mechanism | What work content or waste explains the selected step? | +| Survey | All levels | What can this evidence support, and what is missing? | + +Mode inference can still exist in code. The UX should explain the inferred +instrument set as a consequence of process understanding and data shape. + +## Investigations And Response Paths + +Investigations are the structured reasoning loop between Current Process State +and action. They explain what changed, where it changed, why it may have +changed, whether the signal is trustworthy, and which response path fits. + +An investigation can do more than discover a new x: + +| Investigation job | Example | +| ---------------------------- | --------------------------------------------------------------------- | +| Find a new x | Material temperature was not known to drive variation. | +| Check which known x changed | Cpk dropped; compare setup, nozzle wear, batch, and cleaning delay. | +| Validate a suspected x | Confirm whether a handover change explains the latest state. | +| Scope the problem | Determine whether the issue is one line, product, shift, or step. | +| Separate spread vs centering | Cp is acceptable but Cpk dropped, so centering loss is likely. | +| Resolve trust gaps | Check sample size, MSA, subgrouping, source mapping, or missing data. | +| Verify an action | Compare post-action snapshots with the expected movement. | +| Choose the response path | Decide quick action, focused work, charter, sustainment, or handoff. | + +Response paths should be visible in Process Hub cadence: + +| Response path | When it fits | +| --------------------------------- | ------------------------------------------------------------------- | +| **Quick team action** | Cause is obvious enough, low-risk, reversible, and locally owned. | +| **Focused investigation** | Pattern is real, but mechanism, subgroup, trust, or scope is open. | +| **Chartered improvement project** | High impact, cross-functional, expensive, regulatory, or unclear. | +| **Sustainment review** | Improvement is verified and should stay checked in VariScout. | +| **Control handoff** | Live control belongs in MES, QMS, SCADA, BI, Jira, or another tool. | + +Current Process State can trigger any of these paths. For example, a widening +Cp-Cpk gap may trigger centering-loss investigation; a known x outside its +operating window may trigger a quick team action; repeated patterns across +snapshots may trigger a chartered project; a trust warning may trigger +measurement-system work before process action. + +## Upload And Maturity Path + +The current upload path parses and detects data mechanics first. That stays +necessary, but the product should add a process-understanding step after parse: + +1. **Evidence intake.** Parse CSV, Excel, paste, or snapshot file. Detect + columns, data shape, time, specs, and candidate instruments. +2. **Level read.** Show what level the evidence appears to describe: outcome, + flow, local mechanism, or measurement trust. +3. **FRAME lenses.** Let the user map CTS, CTQs, process steps, + input/condition columns, subgroup axes, hunches, and gaps. +4. **Investigation project.** SCOUT, INVESTIGATE, and IMPROVE build Current + Understanding and Mechanism Branches. +5. **Promote learning.** Attach the project to a Process Hub and decide whether + the source should become recurring evidence. +6. **Evidence Source.** Confirm the export contract, Data Profile where + applicable, cadence, mapping, validation, and snapshot history. +7. **Process Measurement System.** Define the stable measures, targets, + subgroup logic, trust checks, known x-controls, and cadence rules. +8. **Current Process State.** Use latest snapshots to review outcome, flow, + x-control, capability structure, and trust. +9. **Response path.** Route the state to quick action, focused investigation, + chartered project, sustainment review, or control handoff. +10. **Sustainment / handoff.** Keep periodic review in VariScout when that is + enough. Hand off to MES, QMS, SCADA, BI, Jira, or ticketing when live + operational control is needed. + +## Current Implementation Reality + +The repo already has several parts of this model: + +- `ProcessContext.processMap` stores the FRAME map: steps, CTS, CTQs, + input/condition columns, subgroup axes, and hunches. +- `detectGaps()` and `inferMode()` already connect map shape, data columns, and + instrument eligibility. +- QDE 2.0 already defines Current Understanding, Problem Condition, Mechanism + Branches, and Signal Cards. +- Process Flow + Yamazumi already describes the locator/microscope pattern. +- Process Hub metadata already summarizes process maps, investigations, Survey, + signals, actions, and sustainment projections. +- Evidence Source, Data Profile, Evidence Snapshot, and Profile Application + types exist in core, and Azure has an initial Agent Review Log evidence panel. +- ADR-038 and Process Moments already support the capability-state direction: + Cpk vs target, Cp/Cpk over rational windows, and Cp-Cpk gap as centering loss. + +The current gaps: + +- upload still starts as parse/detect/mode mechanics rather than process-level + intake +- Current Process State is not yet a first-class Process Hub review object +- Process Measurement System is not yet named as the stable measure/evidence + layer behind Process Hub cadence +- response paths are present as actions, sustainment, and charter candidates, + but not yet one explicit routing model +- the process map can show a flow skeleton but not full Makigami levels +- process edges, rates, waits, recipe/settings, and local operating windows are + not first-class process-model concepts +- ordinary process datasets cannot yet be promoted cleanly into recurring + Evidence Sources +- public terminology still leaks "tributary" in places where users should see + "process input" or "condition" +- Cp/Cpk stability needs clearer product treatment: Cpk over subgroups/samples + and Cp-Cpk gap as centering loss +- sample size, power, and measurement trust need to be visible as protection + against overclaiming + +## World-Class Product Evaluation Checklist + +A product team evaluating this direction should ask: + +1. **Existence.** Why should VariScout exist when users already have Excel, + Power BI, Minitab, QMS, MES dashboards, Jira, and consultants? +2. **Wedge.** Does the product own structured process learning better than those + alternatives, without trying to become a generic integration platform? +3. **Users.** Can each user see their role: process owner, local owner, analyst, + gemba contributor, data partner, sponsor? +4. **State.** Does the Process Hub show Current Process State across outcome, + flow, x-control, capability structure, and trust? +5. **Loops.** Is the screen supporting the Process Hub operating loop, the + investigation loop, the Evidence Source loop, or the response loop? +6. **Levels.** Does the user know whether they are working at outcome, flow, or + local mechanism level? +7. **Evidence.** Does the product separate what is known, what is inferred, what + is missing, and what must be checked by gemba/expert/data? +8. **Trust.** Are power, sample size, measurement trust, and subgroup logic + visible before conclusions become recommendations? +9. **Response.** Can the user choose quick action, focused investigation, + chartered project, sustainment, or handoff from the same review logic? +10. **Ownership.** Does the product avoid false global aggregation while still + helping global owners compare patterns? +11. **Path to cadence.** Can a one-off dataset become a reusable Evidence Source + and Process Hub review object? +12. **CoScout grounding.** Are artifacts structured enough for CoScout to + explain and draft without becoming the authority? +13. **Boundary.** Is VariScout clear that it is not live monitoring, generic BI, + generic task management, a QMS replacement, or a deep ERP/MES integration? + +## Non-Goals + +- No custom ERP, MES, QMS, CRM, SCADA, or ticketing integration as the first + wedge. +- No live alarms or shift-critical escalation promise. +- No open AI-agent platform, autonomous process-control promise, or external + agent access commitment. +- No claim that static SIPOC mapping is sufficient process understanding. +- No attempt to make every analysis mode a separate user journey. +- No automatic root-cause claim from statistical association. +- No additive Cp/Cpk summaries across unrelated local processes. + +## Implementation Direction + +This spec should drive several later implementation plans: + +1. **Methodology documentation alignment.** Update the public methodology to + describe Process Learning System, Process Hub, Process Measurement System, + Current Process State, investigation loop, response paths, and CoScout + grounding. +2. **Current Process State design.** Make Process Hub cadence show latest + outcome, flow, known x-control, capability-structure, and trust measures. +3. **Upload-to-FRAME redesign.** Add a process-understanding intake after parse + that classifies evidence by level and proposes map/lens work. +4. **FRAME lens model.** Evolve the current process map into level-aware lenses: + outcome, flow, local mechanism, evidence/trust, and cadence. +5. **Response-path routing.** Let Current Process State trigger quick action, + focused investigation, chartered project, sustainment review, or handoff. +6. **Evidence Source promotion.** Let a useful project/export become a recurring + Process Hub source with snapshot history. +7. **Capability improvement.** Make Cpk over subgroups/samples and Cp-Cpk gap a + primary capability story, with sample-size/power warnings. +8. **Terminology cleanup.** Keep `tributary` as internal code if needed, but use + "process input" and "condition" in user-facing language. + +## References + +- Carnegie Mellon Software Engineering Institute, _The Subject Matter of + Process Improvement_ (1995), section on Xerox QIP / PSP: + https://www.sei.cmu.edu/documents/1126/1995_005_001_16379.pdf +- Gitlow and Loredo, _Total Quality Management at Xerox: A Case Study_, + Quality Engineering, 1993: + https://scholarship.miami.edu/esploro/outputs/journalArticle/TOTAL-QUALITY-MANAGEMENT-AT-XEROX-A/991031577658102976 +- ASQ, _Advanced Problem Solving at Xerox_, 1997: + https://asq.org/quality-resources/articles/case-studies/advanced-problem-solving-at-xerox?id=a28f04a4a9fb4e0585d50021dc6f17a7 diff --git a/docs/superpowers/specs/2026-04-27-product-method-roadmap-design.md b/docs/superpowers/specs/2026-04-27-product-method-roadmap-design.md new file mode 100644 index 000000000..3f35d9842 --- /dev/null +++ b/docs/superpowers/specs/2026-04-27-product-method-roadmap-design.md @@ -0,0 +1,359 @@ +--- +title: Product-Method Roadmap +audience: [product, designer, engineer, analyst, manager] +category: design-spec +status: draft +related: + [ + product-method, + methodology, + process-hub, + process-measurement-system, + current-process-state, + evidence-sources, + process-learning, + coscout, + ] +date: 2026-04-27 +--- + +# Product-Method Roadmap + +## Summary + +VariScout should mature from a strong investigation tool into a process +learning system. The roadmap is not a calendar commitment. It is a maturity map +for product, methodology, UX, and engineering. + +The core direction is: + +```text +one dataset +-> investigation project +-> Process Hub context +-> recurring Evidence Sources +-> Process Measurement System +-> Current Process State +-> response paths +-> process learning memory for people and CoScout +``` + +This roadmap replaces a narrow feature-phase view with maturity horizons. It +keeps the existing investigation journey, deterministic statistics engine, and +customer-owned data boundary, while making Process Hub the operating home for +process-owner cadence and team learning. + +## Current Baseline + +The product is further along than the original roadmap assumed. + +| Area | Current state | +| --------------------- | ----------------------------------------------------------------------------- | +| Investigation journey | FRAME -> SCOUT -> INVESTIGATE -> IMPROVE exists as the reasoning spine | +| Deterministic stats | Stats engine remains authority; CoScout does not recompute claims | +| Process Hub | Hubs, rollups, quick/focused/chartered queues, cadence questions, and context | +| Current Process State | Branch-ready v1 projection and Azure review surface | +| Evidence Sources | Core types, IndexedDB, Blob paths, and Agent Review Log workflow exist | +| Sustainment / handoff | Sustainment records, reviews, and control handoff are implemented | +| Methodology docs | Process learning levels and Process Measurement System are now named | + +The main gap is not one missing screen. The gap is coherence: users need a +clear path from dataset, to investigation, to reusable process evidence, to +current state, to response, to sustained learning. + +## Roadmap Principles + +1. **Process learning before statistics.** Statistics are instruments for + answering process questions, not the primary product mental model. +2. **Interface, not integration.** CSV and Excel exports remain first-class. + Deep ERP, MES, QMS, CRM, ACD, SCADA, or ticketing integration is not the + wedge. +3. **Current state is not stability.** Current Process State is the latest + structured read of the process measurement system. It must not collapse into + a simple stable/unstable label. +4. **Response paths are product behavior.** Current state should route to quick + team action, focused investigation, chartered project, measurement-system + work, sustainment review, or control handoff. +5. **Local physics matter.** Global owners compare patterns; local process + owners own the mechanism, recipe, equipment, material, and operating window. +6. **CoScout is grounded by context.** CoScout explains, drafts, and proposes + from structured evidence-backed context. It is not the authority and not an + open agent platform promise. + +## Horizon 0 - Foundation Now + +**Product promise:** VariScout helps a user investigate a dataset, structure +the reasoning, and attach learning to a process context. + +**Who it serves:** + +- analyst +- GB/BB +- engineer +- trainer/student +- early process owner + +**Already real or branch-ready:** + +- investigation journey and six instrument sets +- Process Hub rollups and cadence queues +- quick, focused, and chartered work depth +- Current Understanding, Problem Condition, and branch language +- Survey readiness foundation +- Evidence Source/Data Profile/Snapshot types +- Agent Review Log as first profile-specific evidence workflow +- Sustainment and control handoff +- Current Process State v1 projection and Azure surface + +**Done when:** + +- Current Process State v1 is reviewed, merged, and visible in Azure. +- The docs explain the product as a process learning system, not as unrelated + analysis modes. +- A new contributor can distinguish Process Hub, Process Measurement System, + Current Process State, Evidence Sources, investigations, and response paths. + +## Horizon 1 - Process-Owner Operating System + +**Product promise:** A process team can open one hub and understand what needs +attention now, why, and which response path fits. + +This is the next product maturity horizon because it makes the existing Process +Hub work operationally useful before expanding data contracts. + +**Primary user jobs:** + +- process owner reviews the current state for one line, queue, lab process, or + service flow +- local team captures questions, gemba findings, and next moves +- GB/BB sees whether work is quick action, focused investigation, or charter +- owner checks verification, overdue actions, and sustainment + +**Key capabilities:** + +- make Current Process State items actionable +- route each item to the correct response path +- preserve comments, questions, gemba findings, and assumptions on the hub +- show what is known, inferred, missing, or waiting for verification +- keep daily huddle and weekly process review as cadence views, not separate + products + +**Likely next slices:** + +1. State item -> open or start the matching workflow. +2. Team notes on state items: question, gemba finding, data gap, decision. +3. Better response-path language across queues and investigation metadata. + +**Done when:** + +- a process owner can run a cadence review from the hub without understanding + internal analysis modes +- a state item can trigger a quick action, focused investigation, charter, + measurement-system work, sustainment review, or handoff +- the team can see why the path was chosen and what evidence supports it + +## Horizon 2 - Process Measurement System + +**Product promise:** A team can turn useful recurring evidence into a designed +measurement system for one process. + +This horizon is where the product moves from "latest project and snapshots" to +"stable evidence contracts and review logic." + +**Primary user jobs:** + +- data partner or consultant defines a repeatable export contract +- process owner names the measures that matter +- analyst confirms mappings, subgroup logic, target, and trust checks +- team reviews snapshot history across hourly, shiftly, daily, or weekly + cadence + +**Key capabilities:** + +- promote a useful project/export into a recurring Evidence Source +- generalize Evidence Source setup beyond Agent Review Log +- support snapshot history and latest-versus-previous comparison +- define measure families: outcome/Y, flow, known x-control, capability + structure, and trust +- make Cpk vs target Cpk, Cp-Cpk gap, Cp/Cpk over rational windows, sample size, + power, and measurement trust visible + +**Likely slices:** + +1. General Evidence Source setup for ordinary CSV/Excel exports. +2. Snapshot trend summary for Current Process State. +3. Capability-state card: Cpk vs target, Cp-Cpk gap, subgroup/sample warnings. +4. Evidence Source promotion from an existing project. + +**Done when:** + +- a one-off dataset can become recurring process evidence without custom + integration +- Current Process State is produced from stable measure definitions and + snapshots, not only from project metadata +- the system prevents overclaiming when sample size, subgrouping, or + measurement trust is weak + +## Horizon 3 - Process Learning Memory + +**Product promise:** VariScout accumulates reusable process knowledge without +pretending that different local processes are identical. + +This horizon is where global and local process ownership become useful product +concepts. + +**Primary user jobs:** + +- local process owner manages the physics and operating conditions of one + process +- global process owner compares patterns across similar processes +- OpEx lead sees repeated mechanisms, measurement gaps, and leverage points +- trainer or MBB teaches how process understanding matures + +**Key capabilities:** + +- model the three process-learning levels: system/outcome, flow/process model, + local mechanism/evidence +- link FRAME map, Process Flow, Yamazumi, capability, defect, and performance + views as lenses over the same process +- track known x-control measures and operating windows +- distinguish global pattern comparison from false aggregation of Cp/Cpk or + unrelated mechanisms +- reuse patterns across equipment classes, products, teams, or service flows + +**Likely slices:** + +1. Level-aware Process Hub map: outcome, flow, local mechanism, evidence/trust. +2. Known x-control measure records connected to state items. +3. Multi-hub comparison that compares patterns and queues, not raw process + capability as if it were additive. + +**Done when:** + +- a team can explain which level of process understanding they are working at +- local and global process owners see different but connected views +- recurring mechanisms and measurement weaknesses are reusable learning, not + buried in isolated investigations + +## Horizon 4 - CoScout Context Layer + +**Product promise:** CoScout becomes more useful because the organization has a +structured process context layer for humans first. + +This is not a promise to open an AI-agent platform. It is an internal design +principle: every durable Process Hub artifact should be readable by people and +structured enough for CoScout grounding. + +**Primary user jobs:** + +- analyst asks CoScout to explain current state and possible next moves +- process owner asks for a concise review summary +- GB/BB asks for open risks, weak evidence, and likely response path +- team asks what needs gemba check, data check, or verification + +**Key capabilities:** + +- compact Current Process State summary in Process Hub context +- evidence-linked explanation of why a response path is suggested +- summaries of known x-control, unresolved questions, assumptions, and trust + gaps +- prompt boundaries that keep deterministic statistics and user-confirmed + evidence as authority +- no autonomous decision, live control, or external-agent access promise + +**Likely slices:** + +1. CoScout hub review prompt grounded in Current Process State. +2. Draft cadence summary from state, evidence, actions, and sustainment. +3. Draft investigation charter from repeated state items and evidence gaps. + +**Done when:** + +- CoScout can explain Process Hub state without recomputing statistics +- users can trace AI text back to deterministic signals and user-owned records +- AI improves shared understanding without becoming the source of truth + +## Cross-Horizon Product Spine + +The same operating loop should remain visible across all horizons: + +```text +Process Measurement System +-> Current Process State +-> response path +-> investigation / action / sustainment / handoff +-> updated Process Measurement System +``` + +The investigation journey remains: + +```text +FRAME -> SCOUT -> INVESTIGATE -> IMPROVE +``` + +The process-learning levels remain: + +| Level | Product question | +| -------------------------- | ---------------------------------------------------------------- | +| System / outcome | What result must the customer or business experience? | +| Flow / process model | What flows through which steps, at what rate, and where is loss? | +| Local mechanism / evidence | What physics, recipe, condition, or measurement issue explains? | + +## Roadmap Review Criteria + +Use these questions when choosing the next slice: + +1. Does it strengthen the path from one dataset to reusable process learning? +2. Does it make Process Hub more useful for a real process owner or team? +3. Does it clarify Current Process State rather than adding another isolated + mode? +4. Does it improve evidence trust, sample/power protection, or measurement + system clarity? +5. Does it preserve customer-owned data and interface-not-integration? +6. Does it help CoScout only after deterministic context exists? + +## Near-Term Recommendation + +After merging Current Process State v1, the next implementation slice should be +**Horizon 1: state-to-response actionability**. + +Reason: + +- Current Process State now exists as a visible review surface. +- Evidence Source storage already exists, but generalizing it before state + actionability risks building data plumbing before the user workflow is clear. +- Team notes, questions, gemba findings, and response routing will reveal which + evidence-source contracts matter most. + +The next two slices after that should be: + +1. **General Evidence Source setup** for ordinary CSV/Excel exports. +2. **Snapshot trend and capability-state cards** for Cpk vs target, Cp-Cpk gap, + subgroup/sample warnings, and measurement trust. + +## Boundaries + +VariScout is not: + +- live monitoring or shift-critical alarm management +- generic BI +- generic task management +- QMS replacement +- MES/ERP integration platform +- autonomous process-control system +- open AI-agent platform + +VariScout is: + +- a structured investigation and process learning system +- a process-owner cadence workspace +- a deterministic stats and evidence interpretation layer +- a customer-owned Process Hub memory for humans and CoScout + +## Related Docs + +- [Process Learning Operating Model](2026-04-27-process-learning-operating-model-design.md) +- [Unified Process Hub Methodology Roadmap](2026-04-26-unified-process-hub-methodology-roadmap.md) +- [Evidence Sources And Data Profiles](2026-04-26-evidence-sources-data-profiles-design.md) +- [Process Hub Design](2026-04-25-process-hub-design.md) +- [Question-Driven EDA 2.0](2026-04-25-question-driven-eda-2-design.md) diff --git a/docs/superpowers/specs/index.md b/docs/superpowers/specs/index.md index 8c68cacf3..8e498dfb6 100644 --- a/docs/superpowers/specs/index.md +++ b/docs/superpowers/specs/index.md @@ -94,10 +94,13 @@ Once a feature stabilizes, the ADR is the canonical reference. | [2026-04-25-process-hub-design.md](2026-04-25-process-hub-design.md) | Process Hub: work-system context for process owners, team investigations, verification rollups, and control handoff | — | In progress | | [2026-04-25-process-hub-use-cases.md](2026-04-25-process-hub-use-cases.md) | Process Hub use cases: process-first contexts, multi-hub GB/BB workflows, and MVP/deferred boundaries | — | In progress | | [2026-04-26-unified-process-hub-methodology-roadmap.md](2026-04-26-unified-process-hub-methodology-roadmap.md) | Unified Process Hub methodology roadmap: operating spine, investigation spine, Survey readiness, and phased delivery | — | In progress | -| [2026-04-26-evidence-sources-data-profiles-design.md](2026-04-26-evidence-sources-data-profiles-design.md) | Evidence Sources and Data Profiles: hub evidence workflow, Snapshots, profile applications, and future contracts | — | In progress | +| [2026-04-26-evidence-sources-data-profiles-design.md](2026-04-26-evidence-sources-data-profiles-design.md) | Evidence Sources and Data Profiles: hub evidence workflow, Snapshots, profile applications, and snapshot contracts | — | In progress | | [2026-04-25-process-flow-yamazumi-integration-design.md](2026-04-25-process-flow-yamazumi-integration-design.md) | Process Flow + Yamazumi Integration: Process Flow locates the constraint, Yamazumi explains waste inside the selected step | — | Draft | | [2026-04-25-engagement-profile-raci-design.md](2026-04-25-engagement-profile-raci-design.md) | Engagement-profile RACI: identity and engagement layers for Azure collaboration | ADR-071 | Draft | | [2026-04-26-agent-review-log-process-hub-design.md](2026-04-26-agent-review-log-process-hub-design.md) | Agent Review Log Profile: safe green throughput for external AI-agent steps inside Process Hub | — | Draft | +| [2026-04-27-product-method-roadmap-design.md](2026-04-27-product-method-roadmap-design.md) | Product-method roadmap: maturity horizons from investigation foundation to Process Measurement System and CoScout context layer | — | Draft | +| [2026-04-27-process-learning-operating-model-design.md](2026-04-27-process-learning-operating-model-design.md) | Process Learning Operating Model: Process Measurement System, Current Process State, response paths, and Makigami-style levels | — | Draft | +| [2026-04-27-layered-process-view-design.md](2026-04-27-layered-process-view-design.md) | Layered Process View: three-band visual language (Outcome / Process Flow / Operations) for FRAME, Process Hub, and multi-hub | — | Draft | | [2026-04-26-phase-6-sustainment-control-handoff-design.md](2026-04-26-phase-6-sustainment-control-handoff-design.md) | Phase 6 — Sustainment & Control Handoff: periodic sustainment reviews, control handoffs to live systems, closes the roadmap arc | — | In progress (delivered 2026-04-27 in PR #93; chrome-walk acceptance pending) | | [2026-04-07-unified-whatif-explorer-design.md](../../archive/specs/2026-04-07-unified-whatif-explorer-design.md) | Unified What-If Explorer | — | Delivered (archived 2026-04-17 → archive/specs/2026-04-07-unified-whatif-explorer-design.md) | | [2026-04-17-agent-docs-architecture-design.md](2026-04-17-agent-docs-architecture-design.md) | Agent Docs Architecture (A++) | — | Delivered | diff --git a/packages/core/src/__tests__/processHub.test.ts b/packages/core/src/__tests__/processHub.test.ts index 113f2fdc2..b615645af 100644 --- a/packages/core/src/__tests__/processHub.test.ts +++ b/packages/core/src/__tests__/processHub.test.ts @@ -946,6 +946,28 @@ describe('buildProcessHubRollups', () => { actions: { total: 2, completed: 1, overdue: 1 }, verification: { waiting: 1 }, sustainment: { candidates: 0 }, + currentState: { + overallSeverity: 'red', + itemCount: expect.any(Number), + lensCounts: { + outcome: 1, + flow: 0, + conversion: expect.any(Number), + measurement: expect.any(Number), + sustainment: 0, + }, + responsePathCounts: { + 'focused-investigation': expect.any(Number), + 'quick-action': expect.any(Number), + }, + topItems: expect.arrayContaining([ + expect.objectContaining({ + id: 'capability-gap', + lens: 'outcome', + responsePath: 'focused-investigation', + }), + ]), + }, }); expect(context.investigations.map(investigation => investigation.id)).toEqual([ 'line-4-a', diff --git a/packages/core/src/__tests__/processState.test.ts b/packages/core/src/__tests__/processState.test.ts new file mode 100644 index 000000000..780c4e349 --- /dev/null +++ b/packages/core/src/__tests__/processState.test.ts @@ -0,0 +1,312 @@ +import { describe, expect, it } from 'vitest'; +import { + buildProcessHubCadence, + buildProcessHubRollups, + DEFAULT_PROCESS_HUB_ID, +} from '../processHub'; +import { buildCurrentProcessState } from '../processState'; +import type { EvidenceSnapshot, ProcessHub, ProjectMetadata } from '../index'; +import type { ControlHandoff, SustainmentRecord } from '../sustainment'; + +function makeMetadata(overrides: Partial = {}): ProjectMetadata { + return { + phase: 'scout', + findingCounts: {}, + questionCounts: {}, + actionCounts: { total: 0, completed: 0, overdue: 0 }, + assignedTaskCount: 0, + hasOverdueTasks: false, + lastViewedAt: {}, + processHubId: DEFAULT_PROCESS_HUB_ID, + investigationStatus: 'scouting', + ...overrides, + }; +} + +const hubs: ProcessHub[] = [ + { id: 'line-4', name: 'Line 4', createdAt: '2026-04-25T00:00:00.000Z' }, +]; + +describe('buildCurrentProcessState', () => { + it('routes current process signals into lenses and response paths', () => { + const now = new Date('2026-04-26T12:00:00.000Z'); + const investigations = [ + { + id: 'signal-1', + name: 'Night shift overfill', + modified: '2026-04-26T10:00:00.000Z', + metadata: makeMetadata({ + processHubId: 'line-4', + investigationDepth: 'focused', + investigationStatus: 'investigating', + processDescription: 'Line 4 filling process.', + customerRequirementSummary: 'Fill weight inside spec.', + reviewSignal: { + rowCount: 90, + outcome: 'Weight', + computedAt: '2026-04-26T10:00:00.000Z', + topFocus: { factor: 'Machine', value: 'B', variationPct: 48 }, + capability: { cpk: 0.82, cpkTarget: 1.33, outOfSpecPercentage: 4.8 }, + changeSignals: { + total: 2, + outOfControlCount: 1, + nelsonRule2Count: 1, + nelsonRule3Count: 0, + }, + }, + }), + }, + { + id: 'quick-1', + name: 'Label jam after changeover', + modified: '2026-04-26T09:00:00.000Z', + metadata: makeMetadata({ + processHubId: 'line-4', + investigationDepth: 'quick', + investigationStatus: 'scouting', + processDescription: 'Line 4 filling process.', + customerRequirementSummary: 'Fill weight inside spec.', + }), + }, + { + id: 'chartered-1', + name: 'Reduce recurring scrap', + modified: '2026-04-26T08:00:00.000Z', + metadata: makeMetadata({ + processHubId: 'line-4', + investigationDepth: 'chartered', + investigationStatus: 'ready-to-improve', + processDescription: 'Line 4 filling process.', + customerRequirementSummary: 'Fill weight inside spec.', + }), + }, + { + id: 'readiness-1', + name: 'Frame missing process context', + modified: '2026-04-26T07:00:00.000Z', + metadata: makeMetadata({ + processHubId: 'line-4', + investigationDepth: 'focused', + investigationStatus: 'framing', + }), + }, + { + id: 'verify-1', + name: 'Post-action shift check', + modified: '2026-04-26T06:00:00.000Z', + metadata: makeMetadata({ + processHubId: 'line-4', + investigationDepth: 'quick', + investigationStatus: 'verifying', + processDescription: 'Line 4 filling process.', + customerRequirementSummary: 'Fill weight inside spec.', + }), + }, + { + id: 'action-1', + name: 'Overdue valve action', + modified: '2026-04-26T05:00:00.000Z', + metadata: makeMetadata({ + processHubId: 'line-4', + investigationDepth: 'quick', + investigationStatus: 'improving', + processDescription: 'Line 4 filling process.', + customerRequirementSummary: 'Fill weight inside spec.', + actionCounts: { total: 2, completed: 0, overdue: 2 }, + }), + }, + { + id: 'resolved-1', + name: 'Nozzle replacement verified', + modified: '2026-04-26T04:00:00.000Z', + metadata: makeMetadata({ + processHubId: 'line-4', + investigationStatus: 'resolved', + processDescription: 'Line 4 filling process.', + customerRequirementSummary: 'Fill weight inside spec.', + }), + }, + { + id: 'controlled-1', + name: 'Inspection checklist updated', + modified: '2026-04-26T03:00:00.000Z', + metadata: makeMetadata({ + processHubId: 'line-4', + investigationStatus: 'controlled', + processDescription: 'Line 4 filling process.', + customerRequirementSummary: 'Fill weight inside spec.', + }), + }, + ]; + const evidenceSnapshots: EvidenceSnapshot[] = [ + { + id: 'snap-red', + hubId: 'line-4', + sourceId: 'src-agent-log', + capturedAt: '2026-04-26T11:00:00.000Z', + rowCount: 100, + latestSignals: [ + { + id: 'sig-red', + label: 'False green', + value: 12, + severity: 'red', + capturedAt: '2026-04-26T11:00:00.000Z', + }, + ], + }, + ]; + const sustainmentRecords: SustainmentRecord[] = [ + { + id: 'rec-1', + investigationId: 'resolved-1', + hubId: 'line-4', + cadence: 'monthly', + nextReviewDue: '2026-04-25T00:00:00.000Z', + createdAt: '2026-03-25T00:00:00.000Z', + updatedAt: '2026-04-25T00:00:00.000Z', + }, + ]; + const controlHandoffs: ControlHandoff[] = []; + const [rollup] = buildProcessHubRollups(hubs, investigations, { + evidenceSnapshots, + sustainmentRecords, + controlHandoffs, + }); + const cadence = buildProcessHubCadence(rollup, now); + + const state = buildCurrentProcessState(rollup, cadence, now); + + expect(state.overallSeverity).toBe('red'); + expect(state.lensCounts).toMatchObject({ + outcome: 1, + conversion: expect.any(Number), + measurement: expect.any(Number), + sustainment: expect.any(Number), + }); + expect(state.responsePathCounts['focused-investigation']).toBeGreaterThan(0); + expect(state.responsePathCounts['measurement-system-work']).toBeGreaterThan(0); + expect(state.responsePathCounts['sustainment-review']).toBe(1); + expect(state.responsePathCounts['control-handoff']).toBe(1); + expect(state.responsePathCounts['quick-action']).toBeGreaterThan(0); + expect(state.responsePathCounts['chartered-project']).toBe(1); + expect(state.items).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + id: 'capability-gap', + lens: 'outcome', + severity: 'red', + responsePath: 'focused-investigation', + metric: { + cpk: 0.82, + cpkTarget: 1.33, + cpkGap: 0.51, + outOfSpecPercentage: 4.8, + }, + }), + expect.objectContaining({ + id: 'evidence:sig-red', + lens: 'measurement', + severity: 'red', + responsePath: 'measurement-system-work', + sourceId: 'sig-red', + }), + expect.objectContaining({ + id: 'readiness', + lens: 'measurement', + severity: 'amber', + responsePath: 'measurement-system-work', + }), + expect.objectContaining({ + id: 'sustainment', + lens: 'sustainment', + responsePath: 'sustainment-review', + }), + expect.objectContaining({ + id: 'control-handoff', + lens: 'sustainment', + responsePath: 'control-handoff', + }), + expect.objectContaining({ + id: 'active:quick', + responsePath: 'quick-action', + }), + expect.objectContaining({ + id: 'active:focused', + responsePath: 'focused-investigation', + }), + expect.objectContaining({ + id: 'active:chartered', + responsePath: 'chartered-project', + }), + ]) + ); + }); + + it('orders evidence state by severity before weaker signals', () => { + const evidenceSnapshots: EvidenceSnapshot[] = [ + { + id: 'snap-green', + hubId: 'line-4', + sourceId: 'src-1', + capturedAt: '2026-04-26T10:00:00.000Z', + rowCount: 100, + latestSignals: [ + { + id: 'sig-green', + label: 'Safe green', + value: 98, + severity: 'green', + capturedAt: '2026-04-26T10:00:00.000Z', + }, + ], + }, + { + id: 'snap-red', + hubId: 'line-4', + sourceId: 'src-1', + capturedAt: '2026-04-25T10:00:00.000Z', + rowCount: 100, + latestSignals: [ + { + id: 'sig-red', + label: 'False green', + value: 12, + severity: 'red', + capturedAt: '2026-04-25T10:00:00.000Z', + }, + ], + }, + ]; + const [rollup] = buildProcessHubRollups(hubs, [], { evidenceSnapshots }); + const cadence = buildProcessHubCadence(rollup); + + const state = buildCurrentProcessState(rollup, cadence); + + expect( + state.items.filter(item => item.id.startsWith('evidence:')).map(item => item.id) + ).toEqual(['evidence:sig-red', 'evidence:sig-green']); + }); + + it('returns a stable empty state for a quiet hub', () => { + const [rollup] = buildProcessHubRollups(hubs, []); + const cadence = buildProcessHubCadence(rollup); + + const state = buildCurrentProcessState(rollup, cadence, new Date('2026-04-26T12:00:00.000Z')); + + expect(state).toMatchObject({ + hub: { id: 'line-4', name: 'Line 4' }, + assessedAt: '2026-04-26T12:00:00.000Z', + overallSeverity: 'neutral', + items: [], + lensCounts: { + outcome: 0, + flow: 0, + conversion: 0, + measurement: 0, + sustainment: 0, + }, + responsePathCounts: {}, + }); + }); +}); diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index ee568b011..beab910ae 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -489,6 +489,16 @@ export { investigationStatusFromJourneyPhase, normalizeProcessHubId, } from './processHub'; +export { buildCurrentProcessState } from './processState'; +export type { + CurrentProcessState, + ProcessStateItem, + ProcessStateLens, + ProcessStateMetric, + ProcessStateResponsePath, + ProcessStateSeverity, + ProcessStateSource, +} from './processState'; // Sustainment (Phase 6) export type { diff --git a/packages/core/src/processHub.ts b/packages/core/src/processHub.ts index 108248652..dd15ea4ad 100644 --- a/packages/core/src/processHub.ts +++ b/packages/core/src/processHub.ts @@ -2,6 +2,13 @@ import type { JourneyPhase } from './ai/types'; import type { EvidenceLatestSignal, EvidenceSnapshot } from './evidenceSources'; import type { FindingStatus, QuestionStatus } from './findings/types'; import { buildReviewItem } from './processHubReview'; +import { buildCurrentProcessState } from './processState'; +import type { + ProcessStateItem, + ProcessStateLens, + ProcessStateResponsePath, + ProcessStateSeverity, +} from './processState'; import type { HubReviewSignal } from './processReviewSignal'; import type { SurveyStatus } from './survey/types'; import { @@ -274,6 +281,18 @@ export interface ProcessHubContextContract { overdue: number; verdicts: Partial>; }; + currentState: { + overallSeverity: ProcessStateSeverity; + itemCount: number; + lensCounts: Record; + responsePathCounts: Partial>; + topItems: Array< + Pick< + ProcessStateItem, + 'id' | 'lens' | 'severity' | 'responsePath' | 'source' | 'label' | 'count' | 'metric' + > + >; + }; readinessReasons: ProcessHubReadinessReason[]; } @@ -739,6 +758,8 @@ export function buildProcessHubContext ({ + id: item.id, + lens: item.lens, + severity: item.severity, + responsePath: item.responsePath, + source: item.source, + label: item.label, + count: item.count, + metric: item.metric, + })), + }, readinessReasons: uniqueReadinessReasons( review.readinessQueue .flatMap(item => item.readinessReasons) diff --git a/packages/core/src/processState.ts b/packages/core/src/processState.ts new file mode 100644 index 000000000..a6593d545 --- /dev/null +++ b/packages/core/src/processState.ts @@ -0,0 +1,318 @@ +import type { EvidenceLatestSignal } from './evidenceSources'; +import type { + InvestigationDepth, + ProcessHub, + ProcessHubCadenceSummary, + ProcessHubInvestigation, + ProcessHubRollup, +} from './processHub'; + +export type ProcessStateLens = 'outcome' | 'flow' | 'conversion' | 'measurement' | 'sustainment'; + +export type ProcessStateSeverity = 'red' | 'amber' | 'neutral' | 'green'; + +export type ProcessStateResponsePath = + | 'monitor' + | 'quick-action' + | 'focused-investigation' + | 'chartered-project' + | 'measurement-system-work' + | 'sustainment-review' + | 'control-handoff'; + +export type ProcessStateSource = + | 'review-signal' + | 'evidence-snapshot' + | 'readiness' + | 'verification' + | 'action' + | 'sustainment' + | 'active-work'; + +export interface ProcessStateMetric { + cpk?: number; + cpkTarget?: number; + cpkGap?: number; + outOfSpecPercentage?: number; + changeSignalCount?: number; + variationPct?: number; +} + +export interface ProcessStateItem { + id: string; + lens: ProcessStateLens; + severity: ProcessStateSeverity; + responsePath: ProcessStateResponsePath; + source: ProcessStateSource; + label: string; + detail?: string; + metric?: ProcessStateMetric; + sourceId?: string; + count?: number; + investigationIds?: string[]; +} + +export interface CurrentProcessState { + hub: Pick; + assessedAt: string; + overallSeverity: ProcessStateSeverity; + items: ProcessStateItem[]; + lensCounts: Record; + responsePathCounts: Partial>; +} + +const LENSES: ProcessStateLens[] = ['outcome', 'flow', 'conversion', 'measurement', 'sustainment']; + +const DEPTH_RESPONSE_PATHS: Record = { + quick: 'quick-action', + focused: 'focused-investigation', + chartered: 'chartered-project', +}; + +const DEPTH_LABELS: Record = { + quick: 'Quick action queue', + focused: 'Focused investigation queue', + chartered: 'Chartered project queue', +}; + +const SEVERITY_RANK: Record = { + red: 0, + amber: 1, + neutral: 2, + green: 3, +}; + +function roundMetric(value: number): number { + return Math.round(value * 100) / 100; +} + +function capabilityGap(cpk?: number, cpkTarget?: number): number | undefined { + if (cpk === undefined || cpkTarget === undefined) return undefined; + const gap = cpkTarget - cpk; + return gap > 0 ? roundMetric(gap) : undefined; +} + +function capabilitySeverity(gap: number | undefined): ProcessStateSeverity { + if (gap === undefined) return 'green'; + return gap >= 0.5 ? 'red' : 'amber'; +} + +function evidenceSeverity(severity: EvidenceLatestSignal['severity']): ProcessStateSeverity { + return severity === 'red' || severity === 'amber' || severity === 'green' ? severity : 'neutral'; +} + +function overallSeverity(items: ProcessStateItem[]): ProcessStateSeverity { + if (items.length === 0) return 'neutral'; + return [...items].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])[0] + .severity; +} + +function buildLensCounts(items: ProcessStateItem[]): Record { + const counts = Object.fromEntries(LENSES.map(lens => [lens, 0])) as Record< + ProcessStateLens, + number + >; + for (const item of items) { + counts[item.lens] += 1; + } + return counts; +} + +function buildResponsePathCounts( + items: ProcessStateItem[] +): Partial> { + const counts: Partial> = {}; + for (const item of items) { + counts[item.responsePath] = (counts[item.responsePath] ?? 0) + 1; + } + return counts; +} + +function itemSort(a: ProcessStateItem, b: ProcessStateItem): number { + return ( + SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || + a.lens.localeCompare(b.lens) || + a.id.localeCompare(b.id) + ); +} + +function queueInvestigationIds( + items: { investigation: TInvestigation }[] +): string[] { + return items.map(item => item.investigation.id); +} + +export function buildCurrentProcessState( + rollup: ProcessHubRollup, + cadence: ProcessHubCadenceSummary, + now: Date = new Date() +): CurrentProcessState { + const items: ProcessStateItem[] = []; + const capability = rollup.reviewSignal?.capability; + const gap = capabilityGap(capability?.cpk, capability?.cpkTarget); + + if (capability?.cpk !== undefined && capability.cpkTarget !== undefined) { + items.push({ + id: gap === undefined ? 'capability-ok' : 'capability-gap', + lens: 'outcome', + severity: capabilitySeverity(gap), + responsePath: gap === undefined ? 'monitor' : 'focused-investigation', + source: 'review-signal', + label: gap === undefined ? 'Capability at target' : 'Capability below target', + metric: { + cpk: capability.cpk, + cpkTarget: capability.cpkTarget, + cpkGap: gap, + outOfSpecPercentage: capability.outOfSpecPercentage, + }, + }); + } + + const changeSignalCount = rollup.reviewSignal?.changeSignals.total ?? 0; + if (changeSignalCount > 0) { + items.push({ + id: 'change-signals', + lens: 'conversion', + severity: changeSignalCount >= 3 ? 'red' : 'amber', + responsePath: 'focused-investigation', + source: 'review-signal', + label: 'Change signals detected', + count: changeSignalCount, + metric: { changeSignalCount }, + }); + } + + const topFocus = rollup.reviewSignal?.topFocus; + if (topFocus?.variationPct !== undefined && topFocus.variationPct > 0) { + items.push({ + id: 'top-focus', + lens: 'conversion', + severity: topFocus.variationPct >= 50 ? 'red' : 'amber', + responsePath: 'focused-investigation', + source: 'review-signal', + label: 'Variation concentration', + detail: + topFocus.value === undefined ? topFocus.factor : `${topFocus.factor} / ${topFocus.value}`, + metric: { variationPct: roundMetric(topFocus.variationPct) }, + }); + } + + for (const signal of cadence.latestEvidenceSignals.items) { + const severity = evidenceSeverity(signal.severity); + items.push({ + id: `evidence:${signal.id}`, + lens: 'measurement', + severity, + responsePath: + severity === 'green' || severity === 'neutral' ? 'monitor' : 'measurement-system-work', + source: 'evidence-snapshot', + sourceId: signal.id, + label: signal.label, + count: signal.value, + detail: signal.capturedAt, + }); + } + + if (cadence.readiness.totalCount > 0) { + items.push({ + id: 'readiness', + lens: 'measurement', + severity: 'amber', + responsePath: 'measurement-system-work', + source: 'readiness', + label: 'Readiness gaps', + count: cadence.readiness.totalCount, + investigationIds: queueInvestigationIds(cadence.readiness.items), + }); + } + + if (cadence.verification.totalCount > 0) { + items.push({ + id: 'verification', + lens: 'conversion', + severity: 'amber', + responsePath: 'quick-action', + source: 'verification', + label: 'Verification waiting', + count: cadence.verification.totalCount, + investigationIds: queueInvestigationIds(cadence.verification.items), + }); + } + + if (cadence.actions.totalCount > 0) { + items.push({ + id: 'overdue-actions', + lens: 'conversion', + severity: cadence.snapshot.overdueActions > 1 ? 'red' : 'amber', + responsePath: 'quick-action', + source: 'action', + label: 'Overdue actions', + count: cadence.snapshot.overdueActions, + investigationIds: queueInvestigationIds(cadence.actions.items), + }); + } + + for (const depth of Object.keys(cadence.activeWork) as InvestigationDepth[]) { + const queue = cadence.activeWork[depth]; + if (queue.totalCount === 0) continue; + items.push({ + id: `active:${depth}`, + lens: 'conversion', + severity: 'neutral', + responsePath: DEPTH_RESPONSE_PATHS[depth], + source: 'active-work', + label: DEPTH_LABELS[depth], + count: queue.totalCount, + investigationIds: queueInvestigationIds(queue.items), + }); + } + + if (cadence.sustainment.items.some(item => item.reasons.includes('control-handoff-missing'))) { + items.push({ + id: 'control-handoff', + lens: 'sustainment', + severity: 'amber', + responsePath: 'control-handoff', + source: 'sustainment', + label: 'Control handoff needed', + count: cadence.sustainment.items.filter(item => + item.reasons.includes('control-handoff-missing') + ).length, + investigationIds: cadence.sustainment.items + .filter(item => item.reasons.includes('control-handoff-missing')) + .map(item => item.investigation.id), + }); + } + + const sustainmentReviewItems = cadence.sustainment.items.filter( + item => !item.reasons.includes('control-handoff-missing') + ); + if (sustainmentReviewItems.length > 0) { + items.push({ + id: 'sustainment', + lens: 'sustainment', + severity: 'amber', + responsePath: 'sustainment-review', + source: 'sustainment', + label: 'Sustainment review due', + count: sustainmentReviewItems.length, + investigationIds: sustainmentReviewItems.map(item => item.investigation.id), + }); + } + + const sortedItems = items.sort(itemSort); + + return { + hub: { + id: rollup.hub.id, + name: rollup.hub.name, + description: rollup.hub.description, + processOwner: rollup.hub.processOwner, + }, + assessedAt: now.toISOString(), + overallSeverity: overallSeverity(sortedItems), + items: sortedItems, + lensCounts: buildLensCounts(sortedItems), + responsePathCounts: buildResponsePathCounts(sortedItems), + }; +} diff --git a/packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx b/packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx new file mode 100644 index 000000000..aa05e68cb --- /dev/null +++ b/packages/ui/src/components/LayeredProcessView/LayeredProcessView.tsx @@ -0,0 +1,112 @@ +/** + * LayeredProcessView — three-band Makigami-style process visual. + * + * Stacks Outcome / Process Flow / Operations bands vertically. The Process + * Flow band wraps the existing `ProcessMapBase` river-SIPOC; the Outcome and + * Operations bands surround it. See spec at + * `docs/superpowers/specs/2026-04-27-layered-process-view-design.md` (V1). + */ + +import React from 'react'; +import type { ProcessMap, Gap } from '@variscout/core/frame'; +import { ProcessMapBase } from '../ProcessMap/ProcessMapBase'; + +export interface LayeredProcessViewProps { + map: ProcessMap; + availableColumns: string[]; + onChange: (next: ProcessMap) => void; + gaps?: Gap[]; + disabled?: boolean; + target?: number; + usl?: number; + lsl?: number; + onSpecsChange?: (next: { target?: number; usl?: number; lsl?: number }) => void; +} + +export const LayeredProcessView: React.FC = ({ + map, + availableColumns, + onChange, + gaps, + disabled, + target, + usl, + lsl, + onSpecsChange, +}) => { + const hasOutcomeData = target !== undefined || usl !== undefined || lsl !== undefined; + + return ( +
+
+

Outcome

+ {hasOutcomeData ? ( +
+ {target !== undefined && ( +
+
Target:
+
{target}
+
+ )} + {usl !== undefined && ( +
+
USL:
+
{usl}
+
+ )} + {lsl !== undefined && ( +
+
LSL:
+
{lsl}
+
+ )} +
+ ) : ( +

No outcome target set

+ )} +
+
+

Process Flow

+
+ +
+
+
+

Operations

+ {map.tributaries.length > 0 ? ( +
    + {map.tributaries.map(trib => { + const parentStep = map.nodes.find(n => n.id === trib.stepId); + const stepLabel = parentStep?.name ?? 'Unmapped'; + return ( +
  • + {trib.column} + at {stepLabel} +
    • + ); + })} +
+ ) : ( +

No factors mapped yet

+ )} +
+
+ ); +}; diff --git a/packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx b/packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx new file mode 100644 index 000000000..67872e24d --- /dev/null +++ b/packages/ui/src/components/LayeredProcessView/__tests__/LayeredProcessView.test.tsx @@ -0,0 +1,143 @@ +import { render, screen, within } from '@testing-library/react'; +import { describe, it, expect } from 'vitest'; +import { LayeredProcessView } from '../LayeredProcessView'; +import type { ProcessMap } from '@variscout/core/frame'; + +const emptyMap: ProcessMap = { + version: 1, + nodes: [], + tributaries: [], + createdAt: '2026-04-27T00:00:00.000Z', + updatedAt: '2026-04-27T00:00:00.000Z', +}; + +describe('LayeredProcessView', () => { + it('renders three bands labelled Outcome, Process Flow, Operations', () => { + render( {}} />); + + expect(screen.getByTestId('layered-process-view')).toBeInTheDocument(); + expect(screen.getByTestId('band-outcome')).toBeInTheDocument(); + expect(screen.getByTestId('band-process-flow')).toBeInTheDocument(); + expect(screen.getByTestId('band-operations')).toBeInTheDocument(); + + expect(screen.getByText('Outcome')).toBeInTheDocument(); + expect(screen.getByText('Process Flow')).toBeInTheDocument(); + expect(screen.getByText('Operations')).toBeInTheDocument(); + }); + + it('shows target value in Outcome band when target is set', () => { + render( + {}} target={1.33} /> + ); + + const outcomeBand = screen.getByTestId('band-outcome'); + expect(within(outcomeBand).getByText('Target:')).toBeInTheDocument(); + expect(within(outcomeBand).getByText('1.33')).toBeInTheDocument(); + }); + + it('shows USL and LSL in Outcome band when set', () => { + render( + {}} + usl={12.5} + lsl={8.5} + /> + ); + + const outcomeBand = screen.getByTestId('band-outcome'); + expect(within(outcomeBand).getByText('USL:')).toBeInTheDocument(); + expect(within(outcomeBand).getByText('12.5')).toBeInTheDocument(); + expect(within(outcomeBand).getByText('LSL:')).toBeInTheDocument(); + expect(within(outcomeBand).getByText('8.5')).toBeInTheDocument(); + }); + + it('shows placeholder when no outcome data', () => { + render( {}} />); + + const outcomeBand = screen.getByTestId('band-outcome'); + expect(outcomeBand).toHaveTextContent('No outcome target set'); + }); + + it('renders ProcessMapBase inside Process Flow band', () => { + const mapWithStep: ProcessMap = { + ...emptyMap, + nodes: [{ id: 'step-1', name: 'Mix', order: 0 }], + }; + + render( + {}} + /> + ); + + const processFlowBand = screen.getByTestId('band-process-flow'); + // ProcessMapBase renders the step name + expect(processFlowBand).toHaveTextContent('Mix'); + }); + + it('renders one factor chip per tributary in Operations band', () => { + const mapWithFactors: ProcessMap = { + ...emptyMap, + nodes: [ + { id: 'step-1', name: 'Mix', order: 0 }, + { id: 'step-2', name: 'Coat', order: 1 }, + ], + tributaries: [ + { id: 't-1', stepId: 'step-1', column: 'Temperature' }, + { id: 't-2', stepId: 'step-2', column: 'Speed' }, + ], + }; + + render( + {}} + /> + ); + + const operationsBand = screen.getByTestId('band-operations'); + const chips = operationsBand.querySelectorAll('[data-testid^="factor-chip-"]'); + expect(chips).toHaveLength(2); + expect(operationsBand).toHaveTextContent('Temperature'); + expect(operationsBand).toHaveTextContent('Speed'); + }); + + it('labels each factor chip with its parent step name', () => { + const mapWithFactors: ProcessMap = { + ...emptyMap, + nodes: [{ id: 'step-1', name: 'Mix', order: 0 }], + tributaries: [{ id: 't-1', stepId: 'step-1', column: 'Temperature' }], + }; + + render( {}} />); + + const chip = screen.getByTestId('factor-chip-t-1'); + expect(chip).toHaveTextContent('Temperature'); + expect(chip).toHaveTextContent('at Mix'); + }); + + it('shows placeholder when no factors are mapped', () => { + render( {}} />); + + const operationsBand = screen.getByTestId('band-operations'); + expect(operationsBand).toHaveTextContent('No factors mapped yet'); + }); + + it('renders all three band frames even when the map is fully empty', () => { + render( {}} />); + + // All three bands render with their headers regardless of content + expect(screen.getByText('Outcome')).toBeInTheDocument(); + expect(screen.getByText('Process Flow')).toBeInTheDocument(); + expect(screen.getByText('Operations')).toBeInTheDocument(); + + // Outcome and Operations show their placeholders + expect(screen.getByTestId('band-outcome')).toHaveTextContent('No outcome target set'); + expect(screen.getByTestId('band-operations')).toHaveTextContent('No factors mapped yet'); + }); +}); diff --git a/packages/ui/src/components/LayeredProcessView/index.ts b/packages/ui/src/components/LayeredProcessView/index.ts new file mode 100644 index 000000000..c1bfc8f71 --- /dev/null +++ b/packages/ui/src/components/LayeredProcessView/index.ts @@ -0,0 +1,2 @@ +export { LayeredProcessView } from './LayeredProcessView'; +export type { LayeredProcessViewProps } from './LayeredProcessView'; diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts index 461a7c1bd..341750120 100644 --- a/packages/ui/src/index.ts +++ b/packages/ui/src/index.ts @@ -593,6 +593,7 @@ export { SubgroupConfigPopover, type SubgroupConfigProps } from './components/Su // FRAME workspace — visual Process Map (ADR-070) export { ProcessMapBase, type ProcessMapBaseProps } from './components/ProcessMap/ProcessMapBase'; +export { LayeredProcessView, type LayeredProcessViewProps } from './components/LayeredProcessView'; // Hooks export {