| 1 | <!-- English translation of adr/0014-situational-checklists.md. Canonical Russian: ../../adr/0014-situational-checklists.md --> |
| 2 | |
| 3 | # ADR 0014: Situational Checklists (Model, Triggers, UI) |
| 4 | |
| 5 | **Status:** Accepted |
| 6 | **Date:** 2026-04-02 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0013](0013-command-surface-and-discoverability.md) | Palette and command surface — parent decision | |
| 13 | | [0010](0010-ui-modes-toml-configuration.md) | Modes | |
| 14 | | [0011](0011-debug-situational-awareness.md) | Status strip vs checklist steps | |
| 15 | | [0002](0002-debug-human-agent-parity.md) | Single debug state layer for human and agent | |
| 16 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | Stable MCP contracts and testable infrastructure | |
| 17 | |
| 18 | ## Summary |
| 19 | |
| 20 | - Situational **checklists**: model, triggers, UI; child of [0013](0013-command-surface-and-discoverability.md). |
| 21 | - Discoverability via palette and task context, not a separate app. |
| 22 | |
| 23 | ## Split with [0013](0013-command-surface-and-discoverability.md) |
| 24 | |
| 25 | - **[0013](0013-command-surface-and-discoverability.md)** — command surface: palette, discoverability overall, minimal toolbar. |
| 26 | - **0014 (this ADR)** — **situational checklists**: scenario catalog, triggers, binding steps to `command_id`, checklist card behavior. |
| 27 | |
| 28 | --- |
| 29 | |
| 30 | ## Context |
| 31 | |
| 32 | [0013](0013-command-surface-and-discoverability.md) introduces discoverability beyond palette search and proposes **mini-checklists** as situational hints (including aviation metaphor). This ADR records **checklist mechanics** separately; otherwise “what entry points exist” (0013) mixes with “how one scenario’s steps are structured”. |
| 33 | |
| 34 | ## Decision |
| 35 | |
| 36 | A checklist is not a palette replacement but a **narrow layer** of “what makes sense to do *now* in this situation”, even when the user does not know command names. Details — [“Vision: mechanics”](#checklist-vision) below. |
| 37 | |
| 38 | <a id="checklist-vision"></a> |
| 39 | |
| 40 | ## Vision: situational checklist mechanics |
| 41 | |
| 42 | Below — target implementation vision (iterations and checklist set per plan). |
| 43 | |
| 44 | ### Roles of three mechanisms |
| 45 | |
| 46 | | Mechanism | Purpose | |
| 47 | |-----------|---------| |
| 48 | | **Command palette** | Find **any** known command by name / substring / hotkey. | |
| 49 | | **Situational checklist** | Show a **short ordered scenario** for current context; answers “what people usually do next”, not “what commands exist in the product”. | |
| 50 | | **Toolbar** | Rare **anchor** actions; do not move whole scenarios here. | |
| 51 | |
| 52 | A step bound to a command invokes the **same** operation as the palette and (by contract) automation — via the **unified registry** (`command_id`) from [0013](0013-command-surface-and-discoverability.md) / [0008](0008-mcp-contracts-and-testable-infrastructure.md). |
| 53 | |
| 54 | ### Logical checklist model |
| 55 | |
| 56 | - **`checklist_id`** — stable id (telemetry, mode binding, content evolution). |
| 57 | - **`situation`** — relevance condition (see triggers below). |
| 58 | - **`steps[]`** — ordered steps: human-readable text; optional **`command_id`** from registry; optional **deep link** (open panel, file, setting). |
| 59 | - **Step UI state** (session or persisted in settings — per iteration): e.g. `todo` / `done` / `skipped` / `na`. |
| 60 | - **`anchors`** — where a checklist *may* appear (compact card at editor edge, strip, first-run modal, etc.); one scenario need not be tied to one widget forever. |
| 61 | |
| 62 | A checklist **guides attention** and delegates to the command layer on click; it need not “do magic” bypassing the registry. |
| 63 | |
| 64 | ### When a checklist is relevant (triggers) |
| 65 | |
| 66 | Rules are **declarative in TOML** — same spirit as UI mode config ([0010](0010-ui-modes-toml-configuration.md)); a parallel JSON “official” format for this is **not** needed (see 0010 on one textual config stack). Show conditions — structure like `when` with `ui_mode`, `phase`, events, etc. (exact schema at implementation), without logic in VM. |
| 67 | |
| 68 | - **UI mode** ([0010](0010-ui-modes-toml-configuration.md)) — e.g. in Debug show “typical debug loop”. |
| 69 | - **Scenario phase** — high-level state machine (`no solution` → `build` → `debug` → …); each phase may have its checklist or step branch. |
| 70 | - **Event** — first launch, first breakpoint in session, build failure, etc. |
| 71 | - **Explicit request** — “Show checklist…” from palette or context menu. |
| 72 | |
| 73 | ### UI behavior |
| 74 | |
| 75 | - Default — **compact card** (collapsible); visual reference — mockup [docs/ui-ux/concept-screens/cascade-ide-checklist-ui-concept.png](../ui-ux/concept-screens/cascade-ide-checklist-ui-concept.png). |
| 76 | - Click on a step with `command_id` = same invocation as from the palette; mark `done` — manually and/or heuristically after successful command (complexity per iteration). |
| 77 | - **Do not obstruct:** Hide / “do not show for this scenario” without losing reopen from palette. |
| 78 | - **Link to [0011](0011-debug-situational-awareness.md):** awareness strip is about *state*; checklist is about *typical next steps*. Do not mix long log and long checklist in one zone. |
| 79 | |
| 80 | ### Data flow (target) |
| 81 | |
| 82 | ```mermaid |
| 83 | flowchart LR |
| 84 | subgraph triggers [Triggers] |
| 85 | Mode[UI mode] |
| 86 | Phase[Scenario phase] |
| 87 | Event[Event] |
| 88 | end |
| 89 | subgraph core [Core] |
| 90 | Registry[Command registry] |
| 91 | Catalog[Checklist catalog] |
| 92 | end |
| 93 | subgraph ui [UI] |
| 94 | Palette[Palette] |
| 95 | Checklist[Checklist] |
| 96 | end |
| 97 | triggers --> Catalog |
| 98 | Catalog --> Checklist |
| 99 | Registry --> Palette |
| 100 | Registry --> Checklist |
| 101 | Checklist -->|command_id| Registry |
| 102 | ``` |
| 103 | |
| 104 | ### Out of nearest v1 scope |
| 105 | |
| 106 | - Long “aviation” preflight lists with dozens of items per action. |
| 107 | - Embedded knowledge base inside the checklist (except links to commands and external docs). |
| 108 | - Mandatory sync of checklist “ticks” with the agent: parity on **commands** ([0002](0002-debug-human-agent-parity.md)); checklist state for the human may stay local until a separate decision. |
| 109 | |
| 110 | ### Rollout order (recommendation) |
| 111 | |
| 112 | 1. **Command registry + palette** ([0013](0013-command-surface-and-discoverability.md)) — shared base for toolbar, MCP, checklist steps. |
| 113 | 2. **Checklist catalog + UI card** — steps with `command_id`, triggers and hide rules as above. |
| 114 | |
| 115 | ## Consequences |
| 116 | |
| 117 | - Need a **scenario catalog** (steps, `command_id`, `situation` rules) on top of the **unified command registry**; otherwise the checklist becomes a second source of truth. |
| 118 | - Checklist UI is a **presentation of invocations** through the same registry as palette and MCP. |
| 119 | - Tests and docs (later): which checklists show by default in which modes. |
| 120 | |
| 121 | ## Rejected alternatives (as end state) |
| 122 | |
| 123 | - **Checklist as a separate command channel** without `command_id` and registry — rejected: diverges from palette and agent. |
| 124 | - **Long checklists only**, no palette — rejected: see [0013](0013-command-surface-and-discoverability.md). |
| 125 | |
| 126 | ## Discussion (open questions for next iterations) |
| 127 | |
| 128 | - **Scenario set** per UI mode and overlap with [0011](0011-debug-situational-awareness.md) / [0012](0012-floating-workspace-chrome.md) (where to show the card with floating chrome). |
| 129 | - Separate UX for **first launch** vs **day two**. |
| 130 | |