---
name: visual-report
description: >-
  功能开发/需求实现的可视化验证证据产出流程（日常对话自动触发，替代「测试先行」）。
  触发场景：日常对话中用户提出/聊到任何新需求、新功能、功能开发、修改功能、修复 bug、
  「帮我开发」「帮我实现」「帮我写」「帮我做」「改一下」「优化一下」「重构一下」，
  以及「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」等
  任何越过「闲聊」、涉及写代码/改代码/排查问题/验证功能/实现需求的实质内容——
  只要对话进入这类实质内容，就自动触发本 Skill，无需用户额外说「做验证」「加测试」「写报告」。
  触发不依赖用户正式说「提需求/做功能」；日常对话里随口提到的开发任务同样触发。
  职责：用真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），
  把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
  ⚠️ 仅当用户显式提到「测试 / TDD / 测试用例」时才改走 /tdd-workflow。
---

# 可视化验证报告流程（Visual Report）

⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `visual-report`，按可视化验证流程交付（真实数据 + 截图证据），不写测试用例」然后严格按照以下步骤执行，不得跳过。**

## 核心原则

- **验证职责 = 可视化证据，不是测试断言。** 功能对不对，用「用户能一眼看懂」的证据证明，而不是用「AI 自己写、AI 自己看」的测试用例（用户也看不懂、也影响不到最终质量）。
- **默认不写测试用例。** 除非用户显式说「加测试 / 写测试用例 / 补回归」，否则不创建任何单测 / E2E / 冒烟脚本。
- **证据必须基于运行时真实数据**，禁止 mock/虚构数据凑证据（真实数据会暴露空值、超长文本、特殊字符、异常关联等边界情况）。

## 触发时机

- **日常对话里只要出现实质性开发内容就自动触发本 Skill**，不依赖用户说「提需求/做功能」。包括：写代码、改代码、修 bug、排查问题、优化、重构、实现一个小功能，以及用户随口描述的一个开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」）。都要默认走可视化验证。
- 用户说「加测试 / TDD / 测试用例」→ 改走 `/tdd-workflow`。

## 验证矩阵（什么改动截什么证）

| 改动类型 | 证据来源 | 具体动作 |
|------|------|------|
| 页面 / 界面改动 | 真实页面 | 打开真实页面，用真实数据走真实交互（点击、填写、提交、等待渲染），全页截图 + 箭头标注关键改动区域 |
| Redis 相关 | Redis for VS Code 插件 | 查看运行时 Redis 的 key/value，A/B 对比改动前后的值（SET 已知值 → 触发业务动作 → 截图看值是否如预期） |
| 数据库相关 | SQLTools 插件 | 查看运行时数据库的 row 数据，A/B 对比改动前后的值（插入/更新 → 触发业务动作 → 截图看落库是否如预期） |
| 纯后端接口 / 定时任务无页面 | 运行时真实返回 | curl / 日志 / 查库 / 查 Redis，把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 截图） |

> Redis 和数据库截图优先用插件页截图：信息密度远高于命令行输出，且能直接看到 key 名、类型、TTL、行数据等完整上下文。

## 用户配合截图

- **AI 的屏幕截图能力是辅助，优先邀请用户配合一起截图。** 用户是真人验证关卡：截到的数据必须真实，AI 不得用 mock 数据骗自己（也骗用户）。
- 需要用户操作浏览器/插件时，明确告诉用户「请打开 X，做 Y 操作，然后截图发给我」——具体到点哪个按钮、看哪个 key。
- 用户截的图与 AI capability（agent-browser 截图 / 后台页面自动化截图）互为验证，双证据对齐。

## 报告格式（交付物 = 可视化 HTML 报告）

- 用 `/create-doc` skill 生成 HTML 格式报告（中文文件名），存到 `docs/` 对应子目录。
- **报告骨架**（每个验证点必须有）：
  1. **结论卡**：本次改动改了什么、验证结果是对是错、用户确认没有
  2. **「为什么这样验证成立」原理说明卡**：先讲清楚 bug/功能差异的本质是哪一个动作，再论证「手动模拟该动作 = 真实场景」
  3. **A/B 对照表**：修复前 vs 修复后（或改动前 vs 改动后），代码行为 / 等价操作 / 观测结果三列并排
  4. **每步截图**：必须带箭头标注关键区域/验证点，图注写清「这张图证明了什么」，标注关键行/关键数据
- 截图本身遵循「⚠️ 截图规范」：浏览器真实视口宽（需要更清晰时提高 DPR）、`fullPage` 全页、URL 可见、存到 `docs/` 对应子目录、文件名「编号 + 英文描述」。

## 不写测试 ≠ 不查错

- 禁写测试不代表带着基本错误交付。**改完代码至少必须跑通：编译 / 类型检查 / 最小冒烟**，能自行发现并修复语法、类型、启动崩溃这类基本错误后再交付验证。

## 两类例外（用户显式要求或真实风险时才写测试）

⚠️ 仅以下两类情况允许写测试用例（有明确触发路径，非默认行为）：

1. **时序/并发/缓存失效类逻辑**：问题出在「某个时刻的状态」，截图截不出来（如并发竞态、延迟失效），必须写测试证明行为正确。
2. **回归事故补种**：出现「改 A 把 B 改坏」的回归事故后，当场为出问题的点补一条回归测试，防止同类问题再次悄悄发生。

## 重要规则

- ⚠️ 第一反应不是写代码、也不是写测试，而是「想清楚怎么用证据证明功能对了」
- ⚠️ 验证报告必须先给用户看、用户确认无误才算完成，禁止 AI 自认为「看起来对」就宣称完成
- ⚠️ 带得动的改动（页面/Redis/数据库）必须走可视化验证；只有带不动又不属于上面两类的，才需要向用户说明并请用户决定