ss-tools/specs/038-dashboard-scenario-model/ux_reference.md

#region DashboardScenarioModel.UxReference [C:3] [TYPE ADR] [SEMANTICS ux,reference,scenario,dashboard-testing] @BRIEF UX reference for reviewing a generated DashboardTestScenario graph as a goal-oriented test flow.

Feature Branch: 038-dashboard-scenario-model Created: 2026-07-07 | Status: Ready for Implementation

1. User Persona & Context

• Who is the user?: QA engineer or dashboard owner reviewing the agent's proposed test scenario before execution or artifact generation.
• What is their goal?: Understand what will be tested, which tools each step uses, what parameters are needed, and what cannot be automated.
• Context: Agent workspace shows a scenario graph produced from dashboard metadata, checklist template, and baselines.

2. Happy Path Narrative

The agent proposes a scenario called "Проверка фильтров, метрик и XLSX выгрузки". The user sees phases, steps, dependencies, tool categories, expected outcomes, and missing parameters. The scenario is a business flow, not a menu of technologies, so the user approves the goal and parameters while the graph records tool selection internally.

3. Interface Mockups

Scenario Summary

┌──────────────────────── Proposed scenario ──────────────────────────────────┐
│ Goal: проверить фильтры, метрику, XLSX выгрузку и baseline                  │
│ Steps: 18 | Tools: browser, Superset API, XLSX, assertions, report          │
│ Parameters required: test_date, counterparty                                │
│ Blockers: 0 | Warnings: 2                                                   │
└─────────────────────────────────────────────────────────────────────────────┘

Scenario Graph

[open_dashboard]
      │
      ▼
[apply_filters] ───────► [execute_superset_metric]
      │                              │
      ▼                              ▼
[download_xlsx] ───────► [parse_xlsx_metric]
      │                              │
      └──────────────► [compare_to_baseline] ──► [generate_report]

Step Table

┌────┬────────────────────────────┬──────────────┬───────────────────────────┐
│ №  │ Step                       │ Tool         │ Expected result           │
├────┼────────────────────────────┼──────────────┼───────────────────────────┤
│ 1  │ Открыть дашборд            │ browser      │ dashboard_loaded          │
│ 2  │ Применить фильтры          │ browser      │ filter_state.normalized   │
│ 3  │ Выполнить chart query      │ Superset API │ metric value returned     │
│ 4  │ Скачать XLSX               │ browser      │ xlsx.file                 │
│ 5  │ Сравнить с baseline        │ assertion    │ pass/fail/inconclusive    │
└────┴────────────────────────────┴──────────────┴───────────────────────────┘

4. Error Experience

Scenario A: Missing Selector

• System Response: Step is marked NEEDS_SELECTOR and executable generation for that step is blocked.
• Recovery: User can provide selector hint, convert to human checkpoint, or remove the step.

Scenario B: Stale Baseline

• System Response: Assertion step shows warning and stale fingerprint category.
• Recovery: User can run baseline discovery through 037 or mark the check as pending.

Scenario C: Unsupported Checklist Case

• System Response: Checklist case is listed under unsupported/manual-only with rationale.
• Recovery: User can accept partial coverage or add manual checkpoint instructions.

5. Tone & Voice

• Style: Goal-oriented, explicit about confidence and blockers.
• Terminology: Use "scenario", "step", "tool", "parameter", "baseline ref", "human checkpoint".

#endregion DashboardScenarioModel.UxReference