Planning Phase 20 - huqianghui/AI-Coach-vibe-coding GitHub Wiki

Phase 20: Skill Dry Run Simulation Ai Skill

Auto-generated from .planning/phases/20-skill-dry-run-simulation-ai-skill
Last synced: 2026-04-28

Plans (5)

# Plan File Status
20-01 20-01-PLAN.md Complete
20-02 20-02-PLAN.md Complete
20-03 20-03-PLAN.md Complete
20-04 20-04-PLAN.md Complete
20-05 20-05-PLAN.md Complete

UI Specification

Click to expand UI spec

Phase 20 — UI Design Contract

Visual and interaction contract for the Skill Dry Run Simulation frontend. Generated by gsd-ui-researcher, verified by gsd-ui-checker.


Design System

Property Value
Tool Custom Radix UI wrapper (shadcn-style)
Preset Figma Make Design System for SaaS (medical brand override)
Component library Radix UI primitives (Dialog, Select, Tabs, ScrollArea, Progress, etc.)
Icon library lucide-react ^0.460.0
Font Inter + Noto Sans SC (sans), JetBrains Mono (mono)

Spacing Scale

Declared values (must be multiples of 4):

Token Value Usage
xs 4px Icon gaps, inline padding, badge internal
sm 8px Compact element spacing, chat bubble gaps, step indicator spacing
md 16px Default element spacing, form field gaps, conversation message gaps
lg 24px Section padding, card body padding, report section gaps
xl 32px Layout gaps between major sections
2xl 48px Page-level top/bottom spacing
3xl 64px Full-page empty state centering

Exceptions: SOP step coverage indicator uses 28px row height (7 x 4px) for dense step list readability without wasting vertical space.


Typography

Role Size Weight Line Height
Body 14px (text-sm) 400 1.5
Label 14px (text-sm) 600 1.5
Heading 20px (text-xl) 600 1.5
Display 24px (text-2xl) 600 1.5

Notes:

  • Inherits Phase 19 typography contract exactly
  • Two font weights only: 400 (regular) for body text, 600 (semibold) for labels, headings, display
  • Simulated conversation messages use Body (14px/400) inside ChatBubble
  • SOP step names in coverage report use Label (14px/600) for scanability
  • Score numbers in report summary use Display (24px/600) for visual hierarchy
  • Score card hero numbers use text-4xl (36px) mapped to Display role at semibold weight (this is a scaled instance of Display, not a separate size declaration)
  • Mono font (JetBrains Mono) at 14px for SOP step IDs (e.g., "Step 1.2") -- same size as body text; the mono typeface alone provides sufficient visual distinction from surrounding sans-serif content

Color

Role Value Usage
Dominant (60%) var(--background) #FFFFFF Page background, conversation area background
Secondary (30%) var(--card) #FFFFFF + var(--muted) #F9FAFB Report cards, conversation panel background, step list background
Accent (10%) var(--primary) #1E40AF "Start Dry Run" button, active history item, selected run tab
Destructive var(--destructive) #EF4444 Uncovered SOP steps, critical issues, failed run status

Accent reserved for:

  • "Start Dry Run" primary CTA button
  • "Start New Run" button in report view
  • Active/selected Dry Run history item highlight (bg-primary/5 border-l-2 border-primary)
  • Coverage percentage ring fill (circular progress) when >= 70%
  • Chat bubble timestamp indicator for active message during playback

Additional semantic colors for this phase:

Color Token Usage
Success green var(--strength) #22C55E Covered SOP step indicator (check icon), high coverage (>= 80%), "completed" run status badge
Warning orange var(--weakness) #F97316 Partial coverage (50-79%), SOP steps with weak coverage, "running" status animation
Purple var(--improvement) #A855F7 AI-MR agent message bubble accent, "processing" indicator
Muted gray var(--muted-foreground) #6B7280 Uncovered step text, run metadata, disabled states
Chart colors var(--chart-1) through var(--chart-5) Multi-run comparison line chart series

Component Inventory (Phase 20 Specific)

New Pages / Panels

Page/Panel Route / Location Layout Pattern Reference
Dry Run Report /admin/skills/:id/dry-run/:runId Admin layout, full-width scoring-feedback.tsx report pattern
Dry Run History Panel Embedded in Skill Editor Quality tab Inline within existing tab Session history list pattern

New Shared/Domain Components

Component Purpose Base UI
DryRunButton Entry point in Skill Editor header — triggers Dry Run Button + Tooltip
DryRunProgress Real-time progress indicator during simulation (step counter + spinner) Progress + Badge + animated icon
DryRunConversation Read-only chat transcript of simulated MR-HCP dialogue ScrollArea + ChatBubble (reused)
SopCoverageMap Visual map of all SOP steps with covered/uncovered/partial status Custom list with status indicators
SopStepRow Individual SOP step row: step ID, name, coverage status icon, linked messages Button-like row with expand
CoverageRingChart Circular percentage ring for overall SOP coverage recharts PieChart (donut) or SVG
DryRunScoreSummary Score card showing executability score + coverage % + issues count Card + stat numbers
DryRunHistoryList List of past Dry Runs with date, score, coverage — click to view Scrollable list items
DryRunHistoryItem Single history entry with timestamp, score badge, coverage bar Card-like row
DryRunComparisonChart Line chart comparing scores across multiple Dry Runs recharts LineChart
DryRunReportHeader Report page header with run metadata, back nav, re-run button Page header pattern
DryRunIssueCard Individual issue/problem identified during simulation Card with severity badge

Reused Existing Components

Component From Usage in Phase 20
ChatBubble shared/chat-bubble.tsx Simulated MR and HCP messages in conversation transcript
ScrollArea ui/scroll-area.tsx Conversation scroll, SOP step list scroll, history scroll
Badge ui/badge.tsx Run status badges, coverage badges, step status pills
Dialog ui/dialog.tsx "Start Dry Run" confirmation dialog, run detail dialog
Progress ui/progress.tsx Linear progress during simulation
Button ui/button.tsx All CTAs (Start Dry Run, View Report, Re-run, Back)
Tabs ui/tabs.tsx Already used in Skill Editor — Quality tab hosts Dry Run results
Card ui/card.tsx Report summary cards, issue cards
Skeleton ui/skeleton.tsx Loading states for report, conversation, history
Separator ui/separator.tsx Section dividers in report
Tooltip ui/tooltip.tsx SOP step hover detail, score explanation
QualityRadarChart shared/quality-radar-chart.tsx Reused for L3 quality dimension radar in report
QualityScoreCard shared/quality-score-card.tsx Reused for dimension breakdown in report

Layout Specifications

Dry Run Entry Point (within Skill Editor)

The Dry Run button is integrated into the existing Skill Editor page header, next to "Save Draft" and "Publish Skill". It appears only when the Skill has content (not in new/empty state).

+-----------------------------------------------------------+
| [< Back] Skill: {name}    [Dry Run] [Save Draft] [Publish]|
+-----------------------------------------------------------+
  • "Dry Run" button uses variant="outline" with a Play/FlaskConical icon to differentiate from save/publish
  • Disabled when: skill is new (no id), no content, or a dry run is currently in progress
  • Tooltip on disabled: "Save the skill first to run a simulation"

Start Dry Run Confirmation Dialog

+----------------------------------------------------+
| Start Dry Run Simulation                           |
|----------------------------------------------------|
| The system will simulate a complete MR-HCP         |
| training conversation using AI agents to validate  |
| this Skill's SOP.                                  |
|                                                    |
| Estimated time: 1-3 minutes                        |
|                                                    |
|                  [Go Back]  [Start Simulation]      |
+----------------------------------------------------+
  • Dialog width: max-w-md (448px)
  • "Start Simulation" uses primary variant
  • "Go Back" uses outline variant

Dry Run In-Progress State (replaces Quality tab content)

+-----------------------------------------------------------+
| Dry Run in Progress                                        |
| +---------------------------------------------------------+|
| | [Spinner] Simulating conversation...                    ||
| | Step 3 of 8 SOP steps covered                           ||
| | [==========------] 37%                                  ||
| +---------------------------------------------------------+|
| |                                                         ||
| | Live Conversation Preview (optional, streaming)         ||
| | [MR]: ...                                               ||
| | [HCP]: ...                                              ||
| | [MR]: ...                                               ||
| +---------------------------------------------------------+|
|                              [Cancel Run]                  |
+-----------------------------------------------------------+
  • Progress card: rounded-lg border bg-card p-lg
  • Progress bar: w-full, striped animation while in progress
  • Live conversation: ScrollArea with auto-scroll to bottom, max-h-[400px]
  • Cancel button: variant="outline" with destructive text color

Dry Run Report Page (/admin/skills/:id/dry-run/:runId)

Focal point: The report header with the three key metrics (Executability Score, SOP Coverage %, Issues Found) should be the first thing the admin sees. The conversation transcript and SOP coverage map are secondary, detailed views.

+-----------------------------------------------------------+
| [< Back to Editor]  Dry Run Report  [Start New Run]       |
+-----------------------------------------------------------+
| Run #3 | 2026-04-26 14:32 | Duration: 2m 18s              |
+-----------------------------------------------------------+
| +--------+ +----------+ +----------+                       |
| | Score  | | Coverage | | Issues   |                       |
| |  78    | |  85%     | |  3       |                       |
| | /100   | | 17/20    | | warnings |                       |
| +--------+ +----------+ +----------+                       |
+-----------------------------------------------------------+
| [Conversation]  [SOP Coverage]  [Issues]  <- Sub-tabs     |
+-----------------------------------------------------------+
| Sub-tab: Conversation                                      |
| +-------------------------------------------------------+ |
| | [AI-MR]: Good morning Dr. Chen, I'm here to discuss..| |
| | [AI-HCP]: Hello. I have 10 minutes. What's new?      | |
| | [AI-MR]: Our latest data on Zanubrutinib shows...     | |
| | [AI-HCP]: What about the comparison with ibrutinib?   | |
| | ...                                                    | |
| | (SOP step annotations on right margin)                 | |
| +-------------------------------------------------------+ |
+-----------------------------------------------------------+
| Sub-tab: SOP Coverage                                      |
| +-------------------------------------------------------+ |
| | [Ring Chart: 85%]                                      | |
| | Step 1: Opening greeting .............. [COVERED]      | |
| | Step 2: Need identification ........... [COVERED]      | |
| | Step 3: Product introduction .......... [COVERED]      | |
| | Step 4: Efficacy data presentation .... [PARTIAL]      | |
| | Step 5: Safety profile ................ [NOT COVERED]   | |
| | Step 6: Objection handling ............ [COVERED]      | |
| | ...                                                    | |
| +-------------------------------------------------------+ |
+-----------------------------------------------------------+
| Sub-tab: Issues                                            |
| +-------------------------------------------------------+ |
| | [!] SOP Step 5 was never triggered (Safety profile)   | |
| |     Suggestion: Add a natural transition from efficacy | |
| |     to safety in the SOP flow.                         | |
| |                                                        | |
| | [!] Step 4 had incomplete coverage (only mentioned     | |
| |     primary endpoint, missed secondary endpoints)      | |
| +-------------------------------------------------------+ |
+-----------------------------------------------------------+
  • Report header: Display title (24px/600), metadata row in text-sm text-muted-foreground
  • Summary cards: 3 columns on desktop, grid-cols-1 on mobile, gap-md (16px)
    • Each card: min-w-[140px], padding-lg (24px), centered numbers
    • Score card: number in text-4xl (36px) font-semibold, color-coded by threshold
    • Coverage card: CoverageRingChart at 64x64px + percentage text
    • Issues card: count + severity indicator
  • Sub-tabs: Tabs component (reuse existing), gap below tabs: mt-md (16px)
  • Conversation sub-tab: ChatBubble list with sender="hcp" and sender="mr"
    • MR messages use speakerName="AI-MR" with speakerColor=var(--improvement) (#A855F7)
    • HCP messages use speakerName="AI-HCP" with speakerColor=var(--primary) (#1E40AF)
    • Optional: right margin annotation showing which SOP step each message maps to
  • SOP Coverage sub-tab: CoverageRingChart centered + SopCoverageMap below
    • Each SopStepRow: h-[28px] padded row, step ID in mono (14px JetBrains Mono), name in body, status icon right-aligned
    • COVERED: check icon in var(--strength), PARTIAL: alert icon in var(--weakness), NOT COVERED: x icon in var(--destructive)
    • Click row to expand: shows matched conversation excerpts
  • Issues sub-tab: list of DryRunIssueCard, each with severity badge + description + suggestion

Dry Run History (within Skill Editor Quality Tab)

When the Quality tab already shows L1/L2 results, the Dry Run history appears as a new section below, separated by a heading.

+-----------------------------------------------------------+
| Quality Tab (existing content above)                       |
| ...L1/L2 results...                                       |
+-----------------------------------------------------------+
| --- Separator ---                                          |
| Dry Run History                              [View All]    |
| +-------------------------------------------------------+ |
| | Run #3 | 2026-04-26 | Score: 78 | Coverage: 85% [>]  | |
| | Run #2 | 2026-04-25 | Score: 65 | Coverage: 72% [>]  | |
| | Run #1 | 2026-04-24 | Score: 52 | Coverage: 60% [>]  | |
| +-------------------------------------------------------+ |
| [Comparison Chart: Score trend across runs]                |
+-----------------------------------------------------------+
  • Section heading: Heading (20px/600), "Dry Run History" / "模拟测试历史"
  • History list: max 5 items visible, "View All" link navigates to full report list
  • Each history item: border-b border-border, padding-sm (8px) vertical, hover bg-muted/50
    • Run number, date, score (color-coded badge), coverage (mini progress bar), chevron-right icon
  • Comparison chart: DryRunComparisonChart at 200px height, below history list
    • X-axis: run number, Y-axis: score (0-100), line color var(--primary)
    • Second series for coverage % in var(--chart-2)

Interaction Contracts

Dry Run Launch Flow

  1. Admin opens Skill Editor for a skill with content
  2. Admin clicks "Dry Run" button in editor header
  3. Confirmation dialog appears with estimated time
  4. Admin clicks "Start Simulation"
  5. Quality tab activates automatically, showing DryRunProgress
  6. System polls backend every 3 seconds for progress updates
  7. Live conversation messages stream into preview area (if enabled)
  8. On completion: DryRunProgress replaced by summary + link to full report
  9. History list updates with the new run entry

Dry Run Cancellation

  1. While Dry Run is in progress, "Cancel Run" button is visible
  2. Click triggers confirmation: "Cancel this simulation? Progress will be lost."
  3. On confirm: POST cancel request, revert to previous Quality tab state
  4. Toast: "Dry Run cancelled" / "模拟测试已取消"

Conversation Playback

  • In the report, conversation messages are rendered as static ChatBubble list
  • Each message has an optional SOP step annotation (small badge on the right margin)
  • Clicking a SOP step annotation scrolls the SOP Coverage tab to that step
  • Clicking a step in SOP Coverage sub-tab scrolls the Conversation sub-tab to the first matching message

SOP Coverage Drill-Down

  1. Admin views SOP Coverage sub-tab
  2. Clicks on a step row to expand
  3. Expanded view shows: matched conversation excerpts (quoted text from transcript)
  4. If step is NOT COVERED: shows "No matching conversation turns found"
  5. If step is PARTIAL: shows matched turns + what was missed

Multi-Run Comparison

  1. Admin views Dry Run History section in Quality tab
  2. Comparison chart auto-renders when >= 2 runs exist
  3. Hovering on chart point shows tooltip: "Run #N: Score X, Coverage Y%"
  4. Clicking chart point navigates to that run's full report

Lifecycle Integration

Skill Status Dry Run Available? Notes
draft Yes Primary use case — validate before publish
review Yes Re-validate after quality review
published Yes (read-only history) Can view past runs, cannot start new
archived No Dry Run button hidden
failed No Dry Run button hidden

Copywriting Contract

Element Copy (en-US) Copy (zh-CN)
Dry Run CTA Dry Run 模拟测试
Start dialog title Start Dry Run Simulation 启动模拟测试
Start dialog body The system will simulate a complete MR-HCP training conversation using AI agents to validate this Skill's SOP. Estimated time: 1-3 minutes. 系统将使用 AI Agent 模拟完整的 MR-HCP 培训对话,以验证此 Skill 的 SOP 可执行性。预计耗时:1-3 分钟。
Start button Start Simulation 开始模拟
Start dialog dismiss Go Back 返回
Cancel Run button Cancel Run 取消测试
Cancel confirmation Cancel this simulation? Progress will be lost. 取消此模拟测试?进度将丢失。
Progress heading Dry Run in Progress 模拟测试进行中
Progress step counter Step {current} of {total} SOP steps covered 已覆盖 {current}/{total} 个 SOP 步骤
Progress simulating Simulating conversation... 正在模拟对话...
Report title Dry Run Report 模拟测试报告
Score label Executability Score 可执行性评分
Coverage label SOP Coverage SOP 覆盖率
Issues label Issues Found 发现问题
Tab: Conversation Conversation 对话记录
Tab: SOP Coverage SOP Coverage SOP 覆盖率
Tab: Issues Issues 问题列表
Step covered Covered 已覆盖
Step partial Partial 部分覆盖
Step not covered Not Covered 未覆盖
History heading Dry Run History 模拟测试历史
View all link View All 查看全部
Start new run Start New Run 启动新测试
Empty state heading No Dry Runs yet 暂无模拟测试
Empty state body Run a simulation to validate your Skill's SOP before publishing. 在发布前运行模拟测试以验证 Skill 的 SOP 可执行性。
Error: run failed Simulation failed. Please check the SOP content and try again. 模拟测试失败,请检查 SOP 内容后重试。
Error: load failed Failed to load Dry Run results. 加载模拟测试结果失败。
Run complete toast Dry Run completed. View the report for details. 模拟测试已完成,请查看报告了解详情。
Run cancelled toast Dry Run cancelled. 模拟测试已取消。
Tooltip: disabled Save the skill content first to run a simulation. 请先保存 Skill 内容后再运行模拟测试。
AI-MR speaker AI-MR AI-MR
AI-HCP speaker AI-HCP AI-HCP
Duration label Duration 耗时
Issue severity: warning Warning 警告
Issue severity: error Error 错误
Issue suggestion prefix Suggestion: 建议:
No issues No issues found. The SOP drives a complete and effective conversation. 未发现问题。SOP 能驱动完整有效的培训对话。

State Specifications

Loading States

Context Implementation
Dry Run report loading 3 Skeleton summary cards (inline grid) + Skeleton conversation area
History list loading 3 Skeleton rows (h-[40px] w-full) with gap-sm spacing
Comparison chart loading Skeleton rectangle 200px height
Conversation playback loading 6 alternating ChatBubble Skeletons (left/right)
SOP coverage map loading 8 Skeleton rows at 28px height

Error States

Context Implementation
Dry Run failed mid-simulation DryRunProgress card with destructive banner: error message + "Retry" button
Report fetch failed EmptyState with AlertTriangle icon + "Failed to load results" + Retry button
History fetch failed Inline error text in muted-foreground + Retry link
Start Dry Run failed (API error) Toast error via sonner: "Failed to start simulation"

Empty States

Context Implementation
No Dry Runs exist (Quality tab) Muted card: FlaskConical icon, "No Dry Runs yet", body text, "Start Dry Run" CTA
Conversation has no messages (edge case) Centered muted text: "No conversation data available"
SOP Coverage with 0 steps Muted text: "No SOP steps detected in skill content"
Issues list empty (all passed) Success card: Check icon green, "No issues found..." text

Registry Safety

Registry Blocks Used Safety Gate
shadcn official (Radix wrappers) Dialog, Tabs, ScrollArea, Progress, Badge, Button, Card, Skeleton, Separator, Tooltip not required -- all already installed
No third-party registries n/a n/a

Accessibility Requirements

Element Requirement
Dry Run button aria-label with tooltip text when disabled; aria-disabled="true" when not available
Progress indicator aria-live="polite" region for step counter and percentage updates
Conversation transcript role="log" aria-label="Simulated conversation", each message with role="article"
SOP Coverage map Each step row: role="button" aria-expanded, keyboard nav (Arrow Up/Down, Enter to expand)
Coverage ring chart aria-label="SOP coverage {N} percent, {covered} of {total} steps covered"
Summary score cards aria-label with full context (e.g., "Executability score 78 out of 100")
History list role="list", each item role="listitem" with keyboard Enter to navigate
Sub-tabs in report Standard Tabs accessibility (already provided by Radix Tabs)
Cancel confirmation dialog Focus trap, ESC to dismiss, confirmation requires explicit click

Responsive Behavior

Breakpoint Adaptation
Desktop (>= 1024px) 3-column summary cards, conversation + SOP annotations side-by-side in report
Tablet (768-1023px) 3-column summary cards (smaller), annotations hidden (toggle button), conversation full width
Mobile (< 768px) 1-column summary cards stacked, sub-tabs as scrollable pills, conversation full width

Animation & Transitions

Element Animation Duration
Page mount page-fade-in (existing) 150ms
Progress bar fill width transition linear 300ms
Progress spinner animate-spin (Tailwind) continuous
SOP step expand/collapse height transition ease 200ms
Coverage ring chart fill stroke-dashoffset transition 600ms ease-out
History item hover bg-muted/50 fade 150ms
Summary card number count-up CSS counter or JS increment 400ms ease-out
Run completion notification sonner default slide-in sonner default
Sub-tab switch opacity crossfade 100ms
Report card hover shadow elevation 150ms ease

i18n Namespace

Extends existing skill.json namespace (both en-US and zh-CN).

New key groups:

  • skill.dryRun.* -- Dry Run flow labels (start, progress, cancel, complete)
  • skill.dryRun.report.* -- Report page labels (score, coverage, issues, tabs)
  • skill.dryRun.coverage.* -- SOP coverage status labels (covered, partial, notCovered)
  • skill.dryRun.history.* -- History section labels (heading, viewAll, empty state)
  • skill.dryRun.errors.* -- Error messages (runFailed, loadFailed, startFailed)
  • skill.dryRun.issues.* -- Issue card labels (severity, suggestion)

Checker Sign-Off

  • Dimension 1 Copywriting: PASS
  • Dimension 2 Visuals: PASS
  • Dimension 3 Color: PASS
  • Dimension 4 Typography: PASS
  • Dimension 5 Spacing: PASS
  • Dimension 6 Registry Safety: PASS

Approval: pending

⚠️ **GitHub.com Fallback** ⚠️