ADR-004: Use One Operational Maturity Slice Before Specialized Modules
- Status: Proposed
- Date: 2026-04-16
Context
After the first three slices, the remaining core prototype work clusters around the same seams:
- diagnostics and operational visibility
- alarm acknowledgment and recovery behavior
- simulator variability across scenarios
- richer inspection results and run metrics
These concerns all touch the same core assets:
- canonical
AppState - workflow and alarm guard behavior
- simulator abstraction and configuration
- run summary persistence and UI projection
If they are prepared as several tiny future slices, each slice will reopen the same files, repeat the same architectural context, and force external AI tools to spend tokens restating shared rules.
At the same time, handing all remaining work to one giant AI prompt would be too risky and too expensive.
The next planning decision should favor:
- one clear umbrella spec for the remaining core work
- medium-sized AI-friendly implementation tasks
- reuse of the existing main operational UI rather than a new screen architecture
- continued use of canonical app state and existing application boundaries
Decision
Prepare the remaining core prototype work as one umbrella slice: SLICE-004: Operational Maturity.
Within that umbrella slice:
- diagnostics, alarm handling, recovery, simulator profiles, and richer run metrics remain part of one operational workspace
- state continues to flow through canonical
AppState - simulator variability is introduced through named configuration-backed profiles rather than hard-coded constants scattered through services
- richer inspection results and metrics extend existing run summary and history contracts rather than creating hidden UI-only caches
- implementation is split into medium sub-tasks sized for external AI tools
Rationale
This approach keeps the next phase coherent without making it monolithic.
It improves token efficiency for tools such as Claude or Copilot because the umbrella spec holds the shared context once, while the task pack keeps coding prompts bounded.
It also matches the product goal of a believable operator/developer workstation: diagnostics, recovery, scenario selection, and richer results are closely related in day-to-day use.
Consequences
Positive
- one shared vocabulary for the remaining core prototype work
- fewer repeated edits across
AppState, workflow services, and UI projection - better AI task sizing without fragmenting the roadmap
- clearer distinction between core maturity work and optional later expansions
Trade-Offs
- the umbrella slice still needs careful sub-task boundaries
- documentation must be explicit about in-scope vs optional behaviors
- implementation review needs to watch for hidden coupling between metrics, profiles, and recovery logic
Non-Goals
This ADR does not choose:
- a new multi-screen application architecture
- historical charts or analytics dashboards
- performance instrumentation as a required core slice
- immediate adoption of an explicit state machine library