Hai Visual Report

Hai Visual Report

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Overview

Turn an idea, requirement, proposal, review result, or goal document into a readable, presentable, multi-section HTML report — a real .html artifact with a title, verdict, diagrams, matrices, sections, and next steps.

Two common misclassifications to rule out first:

• This is not create-visual-card. A visual card is a single-screen summary for sharing; hai-visual-report is a multi-section report for understanding structure, judgment, tradeoffs, route, risk, and evidence.
• This is not a Markdown-only answer. The user wants a generated HTML file, not prose.

Core Principle

Visualize the structure before polishing the copy.

Given an idea or request, do not stack paragraphs. First identify the core judgment, actors, relationships, route, risks, and verification. Then turn those into a scannable HTML page.

Report Content Model

This is the single canonical structure. Default reports include these eight blocks (drop one only with a stated reason):

1. Header: title, scope, generation date. 2. Verdict: one-sentence conclusion and the most important judgment. 3. Structure Map: Mermaid or layout diagram of actors, relationships, flow, or decision path — placed near the top as the reader's coordinate system. 4. Core Sections: problem, goal, solution, users, flow, architecture, tradeoffs, risks, or other relevant themes. Each should carry at least one visual object (chart, table, matrix, stepper, callout, or checklist). 5. Decision Matrix: options, risks, cost, value, or priority. 6. Timeline / Phases: stages, exit proof, and next step when execution is involved. 7. Risks and Proof: key risks, validation method, pass/fail signal. 8. Next Move: explicit next action.

Pick the visual structure for each block from the content itself — complex relationships become a Mermaid graph, a clear flow becomes a timeline or stepper, option comparison becomes a matrix, risk becomes a grid, scope becomes inclusion/exclusion panels.

Workflow

1. Identify report type, which sets the emphasis of the eight blocks:

• Idea report: idea value, opportunity cost, validation path.
• Requirement report: requirement structure, scope, acceptance, risk.
• Goal report: target, phases, todos, verification.
• Review report: issues, evidence, recommendation, priority.
• Architecture-style report: current chain, boundary, options, why-not, red/blue review.

2. Extract the core judgment (apply the Core Principle). Write the one thing the report should make the reader remember, and the most important actor, relationship, conflict, risk, or decision. If information is missing, state assumptions rather than inventing facts — and keep facts, assumptions, and judgments visibly separate.

3. Read the output shape before writing. Open references/output-template.md for the delivery format and references/html-skeleton.md for a minimal Tailwind + Mermaid scaffold of the eight blocks, so you produce against the target instead of inventing a page layout.

4. Write the HTML.

• Output one complete .html file.
• Prefer a system temporary directory such as $TMPDIR/hai-visual-report-<topic>/; follow the user-specified path when provided.
• Keep CSS and JS inline or CDN-based (Tailwind CDN and Mermaid CDN are fine); avoid project-local assets unless requested, so the .html stays a single portable artifact the user can open or send without a build step.
• Use Chinese UI copy for Chinese requests and English UI copy for English requests. Keep code identifiers unchanged.

5. QA, then return the path (see the QA checks below). Deliver the absolute path to the generated .html.

Style constraints

• Quiet, professional report style — not a marketing landing page.
• Use cards only for repeated findings, options, risks, metrics, or callouts.
• If the report comes from an architecture review, preserve architecture-map-first, options matrix, why-not alternatives, and red/blue adversarial review (the judgment itself stays owned by hai-architecture — see below).

Output

Deliver this skeleton in your reply, with the file actually written:

## Report Type
<idea / requirement / goal / review / architecture-style / custom> — <one line>

## Core Judgment
<the one thing the report makes the reader remember>

## Generated HTML
`<absolute path to the .html>`

## QA
- HTML generated: yes/no
- Verdict + map + next step visible near top: pass/issue
- Mermaid readable (split if dense): pass/issue/omitted because <reason>
- Multi-section page, not one long card: pass/issue
- Text fits — no overflow past cards or buttons: pass/issue
- Facts vs assumptions separated: pass/issue

Read references/output-template.md before finalizing; the inline skeleton above is its summary.

Two traps to avoid

• A decorative page that hides the verdict and the next step. Readability and judgment beat ornament.
• Mixing facts, assumptions, and judgments together so the reader cannot tell which is which.

Use a different skill when

• The user wants a single visual card, info card, social card, or one-screen summary — use create-visual-card.
• The user needs architecture-level judgment (APoSD/Ousterhout review, module-boundary critique) — use hai-architecture. Even when they also want HTML, the architecture judgment is owned by hai-architecture; this skill renders a report, it does not produce the architecture verdict.

Hai Visual Report — HTML Skeleton

Read this at the start of the write phase. It is a minimal, complete .html scaffold for the eight blocks in the Report Content Model (Header, Verdict, Structure Map, Core Sections, Decision Matrix, Timeline / Phases, Risks and Proof, Next Move). Fill in the empty sections; drop a block only with a stated reason.

It uses Tailwind CDN and Mermaid CDN so the file stays a single portable artifact — no build step. Keep the quiet, professional report style; use cards only for repeated findings, options, risks, metrics, or callouts. Use Chinese UI copy for Chinese requests and English for English; keep code identifiers unchanged.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>REPORT TITLE</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <script type="module">
    import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
    mermaid.initialize({ startOnLoad: true, theme: "neutral" });
  </script>
</head>
<body class="bg-slate-50 text-slate-800">
  <main class="max-w-5xl mx-auto px-6 py-10 space-y-10">

    <!-- 1. Header -->
    <header class="border-b border-slate-200 pb-6">
      <h1 class="text-3xl font-semibold tracking-tight">REPORT TITLE</h1>
      <p class="mt-2 text-slate-500">Scope · Generated YYYY-MM-DD</p>
    </header>

    <!-- 2. Verdict -->
    <section class="rounded-lg bg-white border border-slate-200 p-6">
      <h2 class="text-sm font-medium uppercase tracking-wide text-slate-400">Verdict</h2>
      <p class="mt-2 text-xl font-medium">ONE-SENTENCE CONCLUSION</p>
    </section>

    <!-- 3. Structure Map (reader's coordinate system — keep near the top) -->
    <section>
      <h2 class="text-xl font-semibold mb-4">Structure Map</h2>
      <div class="rounded-lg bg-white border border-slate-200 p-6 overflow-x-auto">
        <pre class="mermaid">
flowchart TD
  A[Actor] --> B[Relationship]
  B --> C[Outcome]
        </pre>
      </div>
    </section>

    <!-- 4. Core Sections (one per theme; each carries a chart/table/matrix/stepper/callout/checklist) -->
    <section>
      <h2 class="text-xl font-semibold mb-4">Core Section</h2>
      <div class="rounded-lg bg-white border border-slate-200 p-6">
        <p>Body. Include at least one visual object.</p>
      </div>
    </section>

    <!-- 5. Decision Matrix -->
    <section>
      <h2 class="text-xl font-semibold mb-4">Decision Matrix</h2>
      <table class="w-full text-left border-collapse">
        <thead>
          <tr class="border-b border-slate-300 text-slate-500">
            <th class="py-2 pr-4">Option</th><th class="py-2 pr-4">Cost</th>
            <th class="py-2 pr-4">Value</th><th class="py-2">Risk</th>
          </tr>
        </thead>
        <tbody>
          <tr class="border-b border-slate-100"><td class="py-2 pr-4">A</td><td></td><td></td><td></td></tr>
        </tbody>
      </table>
    </section>

    <!-- 6. Timeline / Phases (when execution is involved) -->
    <section>
      <h2 class="text-xl font-semibold mb-4">Timeline / Phases</h2>
      <ol class="space-y-3">
        <li class="rounded-lg bg-white border border-slate-200 p-4"><span class="font-medium">Phase 1</span> — exit proof / next step</li>
      </ol>
    </section>

    <!-- 7. Risks and Proof -->
    <section>
      <h2 class="text-xl font-semibold mb-4">Risks and Proof</h2>
      <div class="grid gap-4 sm:grid-cols-2">
        <div class="rounded-lg bg-white border border-slate-200 p-4">
          <p class="font-medium">Risk</p>
          <p class="text-sm text-slate-500">Validation method · pass/fail signal</p>
        </div>
      </div>
    </section>

    <!-- 8. Next Move -->
    <section class="rounded-lg bg-slate-900 text-slate-50 p-6">
      <h2 class="text-sm font-medium uppercase tracking-wide text-slate-400">Next Move</h2>
      <p class="mt-2 text-lg">EXPLICIT NEXT ACTION</p>
    </section>

  </main>
</body>
</html>

Hai Visual Report 输出模板

用于交付可视化 HTML 报告。HTML 路径必须是真实生成的文件路径。

# Hai Visual Report Delivery

## Report Type
<idea / requirement / goal / review / architecture-style / custom> — <一句话说明>

## Core Judgment
<这份报告最想让读者记住的判断。>

## Visual Structure
- **Map**: <Mermaid graph / flow / system map / none and why>
- **Matrix**: <options / risk / priority / decision / none and why>
- **Sections**: <主要 section 列表>
- **Next Move Block**: yes / no

## Generated File
- **HTML**: `<absolute path>`

## QA Checks
- **HTML generated**: yes / no
- **Mermaid included or intentionally omitted**: yes / no / omitted because <reason>
- **Verdict visible near top**: pass / issue
- **Readable structure**: pass / issue
- **No single-card misuse**: pass / issue
- **Facts vs assumptions separated**: pass / issue

## Notes
- <重要设计选择、限制或后续建议>

Hai Visual Report 中文版

本文件是中文阅读版；执行规则以 SKILL.md 为准。

描述

从想法、需求、PRD、目标、评审、架构议题、计划或方案，生成一份完整、自包含的多 section HTML 报告——标题 + 一句话结论、Mermaid 结构图、决策矩阵、风险/证明表、下一步行动块——并返回生成的文件路径。当用户想把内容变成可视化报告、可视化页面、HTML report、网页版、dashboard 或类似 PPT/幻灯片的网页时使用；即使只是随口说也要触发：可视化一下、做个可视化、做成网页、做个网页版、把这个评审做成网页、做成一页 HTML、输出 HTML、做个汇报页/展示页、做成 PPT 样子的网页、弄个好看点的报告、整理成一份报告页面、带 mermaid 图的报告，以及 render this as a page/webpage、make it visual/interactive、turn my analysis into slides-like html、dashboard of this（含 html repot / viz report 这类拼写错误）。当内容是多 section、需要结构、权衡、路线、风险和证据，而不是一张可传播的卡片时，优先用本 skill 而不是 create-visual-card。

概览

把想法、需求、方案、评审结果或目标文档做成可阅读、可展示的多 section HTML 报告——一个真实的 .html 文件，带标题、结论、图表、矩阵、各 section 和下一步。

先排除两个最常见的误判：

• 它不是 create-visual-card。视觉卡片是单屏摘要，适合传播；hai-visual-report 是多 section 报告，适合看清结构、判断、权衡、路线、风险和证据。
• 它也不是只写 Markdown 的回答。用户要的是生成出来的 HTML 文件，不是一段散文。

核心原则

先把结构可视化，再把文案写漂亮。

拿到想法或请求，不要直接堆段落。先找出核心判断、对象、结构关系、路径、风险和验证方式，再把它们变成可扫读的 HTML 页面。

报告结构

这是唯一的标准结构。默认报告包含这八个块（只能在说明理由后删减某一块）：

1. 标题：标题、范围、生成日期。 2. 结论：一句话结论和最重要的判断。 3. 结构图：Mermaid 或布局图，表达对象、关系、流程或决策路径——放在靠前位置，作为读者的坐标系。 4. 核心 section：问题、目标、方案、用户、流程、架构、权衡、风险或其它相关主题。每个 section 至少带一个可视化对象（图、表、矩阵、stepper、callout 或 checklist）。 5. 决策矩阵：选项、风险、成本、价值或优先级。 6. 时间线 / 阶段：涉及执行时给出阶段、退出证明和下一步。 7. 风险与证明：关键风险、验证方式、通过/不通过信号。 8. 下一步：明确的下一步行动。

每个块的可视化形式从内容本身选：复杂关系画 Mermaid 图，清晰流程做 timeline 或 stepper，选项对比用矩阵，风险用 grid，范围用 included/excluded 面板。

工作流

1. 判断报告类型，它决定八个块的侧重：

• Idea 报告：想法价值、机会成本、验证路径。
• Requirement 报告：需求结构、范围、验收、风险。
• Goal 报告：目标、阶段、todos、验证。
• Review 报告：问题、证据、建议、优先级。
• Architecture-style 报告：当前链路、边界、选项、why-not、红蓝评审。

2. 提炼核心判断（应用核心原则）。写下这份报告最想让读者记住的那一点，以及最重要的对象、关系、冲突、风险或决策。信息缺失时声明假设而不是编造事实，并让事实、假设、判断三者在视觉上区分清楚。

3. 下笔前先读输出形态。 打开 references/output-template.md 看交付格式，打开 references/html-skeleton.md 看八个块的 Tailwind + Mermaid 最小骨架，对着目标产出，而不是每次现编页面布局。

4. 写 HTML。

• 输出一个完整的 .html 文件。
• 优先放系统临时目录，如 $TMPDIR/hai-visual-report-<topic>/；用户指定路径时按用户的来。
• CSS、JS 内联或走 CDN（Tailwind CDN、Mermaid CDN 都行）；除非用户要求，不要依赖项目本地资源，这样 .html 才是一个可直接打开或发送、无需构建的单一可移植文件。
• 中文请求用中文 UI 文案，英文请求用英文 UI 文案。代码标识符保持不变。

5. QA 后返回路径（见下方 QA）。交付生成的 .html 的绝对路径。

样式约束

• 安静、专业的报告风格，不是营销落地页。
• 卡片只用于重复出现的发现、选项、风险、指标或 callout。
• 如果报告来自架构评审，保留 architecture-map-first、选项矩阵、why-not 备选、红蓝对抗评审（判断本身仍归 hai-architecture——见下）。

输出

在回复中交付这个骨架，并实际写出文件：

## Report Type
<idea / requirement / goal / review / architecture-style / custom> — <一句话>

## Core Judgment
<这份报告最想让读者记住的判断>

## Generated HTML
`<.html 的绝对路径>`

## QA
- HTML 已生成：yes/no
- 结论 + 结构图 + 下一步首屏可见：pass/issue
- Mermaid 可读（太密就拆）：pass/issue/omitted because <原因>
- 是多 section 页面而非一张长卡片：pass/issue
- 文本不溢出卡片或按钮：pass/issue
- 事实与假设已区分：pass/issue

定稿前先读 references/output-template.md；上面的内联骨架是它的摘要。

两个要避免的坑

• 页面很花，却把结论和下一步藏起来了。可读性和判断优先于装饰。
• 把事实、假设、判断混在一起，读者分不清哪个是哪个。

何时改用别的 skill

• 用户要的是单张视觉卡片、信息卡、社交卡或单屏摘要——用 create-visual-card。
• 用户要的是架构级判断（APoSD/Ousterhout 评审、模块边界批评）——用 hai-architecture。即使他同时想要 HTML，架构判断也归 hai-architecture；本 skill 负责渲染报告，不产出架构结论。