@wenaixi/dsh-superpower 7.3.0 → 7.5.1

package/skills/brainstorming/visual-companion.md

@@ -1,267 +1,120 @@
-# 可视化辅助指南
+# Visual Companion Guide
 
-基于浏览器的可视化头脑风暴辅助工具，用于展示原型、图表和选项。
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options, built on DSH's official document preview.
 
-## 何时使用
+## When to Use
 
-按问题逐个判断，而非按会话判断。判断标准：**用户看图是否比看文字更易理解？**
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
 
-**内容本身是可视化的场景，适合使用浏览器：**
+**Use the browser preview** when the content itself is visual:
 
-- **界面原型** — 线框图、布局、导航结构、组件设计
-- **架构图** — 系统组件、数据流、关系图谱
-- **并排可视化对比** — 对比两种布局、两种配色方案、两种设计方向
-- **设计打磨** — 问题涉及外观与质感、间距、视觉层级
-- **空间关系** — 状态机、流程图、实体关系等以图形方式呈现
+- **UI mockups** — wireframes, layouts, navigation structures, component designs
+- **Architecture diagrams** — system components, data flow, relationship maps
+- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
+- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
+- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
 
-**内容为文本或表格的场景，适合使用终端：**
+**Use the terminal** when the content is text or tabular:
 
-- **需求与范围问题** — “X 是什么意思？”，“哪些功能在范围内？”
-- **概念性的 A/B/C 选择** — 在文字描述的方案之间做选择
-- **权衡清单** — 优缺点、对比表格
-- **技术决策** — API 设计、数据建模、架构方案选型
-- **澄清性问题** — 任何答案是文字而非视觉偏好的问题
+- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
+- **Conceptual A/B/C choices** — picking between approaches described in words
+- **Tradeoff lists** — pros/cons, comparison tables
+- **Technical decisions** — API design, data modeling, architectural approach selection
+- **Clarifying questions** — anything where the answer is words, not a visual preference
 
-一个*关于*界面主题的问题并不自动等同于可视化问题。“你想要哪种向导？”是概念性问题——使用终端。“这些向导布局中哪一个更合适？”是可视化问题——使用浏览器。
+A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser preview.
 
-## 工作原理
+## How It Works
 
-服务器监听目录中的 HTML 文件，并将最新的文件提供给浏览器。你将 HTML 内容写入 `screen_dir`，用户在浏览器中即可看到，并可点击选择选项。选择结果会记录到 `state_dir/events`，你在下一轮对话中读取即可。
+You write HTML to a convention directory in the workspace; DSH's document preview reads and renders it. The user opens the file in the document sidebar to see it.
 
-**内容片段与完整文档：** 如果你的 HTML 文件以 `<!DOCTYPE` 或 `<html` 开头，服务器将原样提供（仅注入辅助脚本）。否则，服务器会自动将你的内容包裹到框架模板中——添加页头、CSS 主题、连接状态及所有交互基础设施。**默认编写内容片段。** 仅在需要完全控制页面时才编写完整文档。
+**Selection results are not sent back to you automatically.** The preview is an isolated iframe document and cannot deliver your user's choices to the session. So: ask the user to answer in the terminal. Never claim to have read a click inside the preview.
 
-## 启动会话
+## Writing Files
 
-```bash
-# 在用户批准 companion 后启动。--open 会在首屏自动打开其浏览器；
-# --project-dir 持久化原型并支持同端口重启。
-bash scripts/start-server.sh --project-dir /path/to/project --open
+Write every page as a self-contained HTML document. Three hard requirements:
 
-# Returns: {"type":"server-started","port":52341,
-#           "url":"http://localhost:52341/?key=ab12…",
-#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
-#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
-```
-
-保存响应中的 `screen_dir` 和 `state_dir`。使用 `--open` 时，浏览器会在你推送首屏时自动打开——你无需让用户手动打开，但仍需分享 URL 作为备用方案（无头/远程环境无法自动打开）。
-
-**URL 中包含会话密钥（`?key=…`）。** 服务器会拒绝任何不带该密钥的请求，因此务必向用户提供 `url` 字段中的**完整** URL——不要去除查询字符串，也不要只给裸的 `http://host:port`。该密钥用于控制 HTTP 和 WebSocket 访问，防止随意的浏览器标签页或同一网络中的其他机器读取页面或注入事件。首次加载后，浏览器会通过 Cookie 记住该密钥，因此重新加载和访问 `/files/*` 资源时无需重复携带。
-
-**查找连接信息：** 服务器会将启动时的 JSON 写入 `$STATE_DIR/server-info`。如果你在后台启动了服务器且未捕获标准输出，可读取该文件以获取 URL 和端口。使用 `--project-dir` 时，请在 `<project>/.superpowers/brainstorm/` 下查找会话目录。
-
-**注意：** 将项目根目录作为 `--project-dir` 传入，这样原型会持久化到 `.superpowers/brainstorm/` 并在服务器重启后依然保留。若不传，文件会写入 `/tmp` 并被清理。如果 `.gitignore` 中尚未包含 `.superpowers/`，请提醒用户添加。
-
-**在 DSH 中启动服务器：**
-
-```bash
-# 在 DSH 中使用 pwsh（Windows 首选）或 bash 工具，传入 run_in_background: true
-bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
-```
-
-服务器必须在后台持续运行并跨越 turn。在 DSH 工具调用中使用 `run_in_background: true`，然后在下一轮读取 `$STATE_DIR/server-info` 以获取 URL 和端口。
-
-如果 URL 在你的浏览器中无法访问（在远程/容器化环境中很常见），请绑定非回环地址：
-
-```bash
-bash scripts/start-server.sh \
-  --project-dir /path/to/project \
-  --host 0.0.0.0 \
-  --url-host localhost
-```
-
-使用 `--url-host` 控制返回的 URL JSON 中显示的主机名。
-
-## 循环流程
-
-1. **检查服务器是否存活**，然后**向 `screen_dir` 写入 HTML 新文件**：
-   - **必须：在引用 URL 或推送页面前确认服务器存活。** 检查 `$STATE_DIR/server-info` 是否存在且 `$STATE_DIR/server-stopped` 是否不存在。如果已关闭，请使用**相同的 `--project-dir`** 通过 `start-server.sh` 重启——它会复用同一端口，用户的已打开标签页会自动重连（服务器宕机期间会显示“已暂停”遮罩），无需发送新 URL。服务器在空闲 4 小时后自动退出（可通过 `--idle-timeout-minutes` 配置）。
-   - 使用语义化文件名：`platform.html`、`visual-style.html`、`layout.html`
-   - **不要复用文件名**——每个页面都使用全新文件
-   - 使用你的文件创建工具——**不要使用 cat/heredoc**（会在终端产生大量噪音）
-   - 服务器自动提供最新的文件
-
-2. **告知用户预期内容并结束本轮：**
-   - 提醒他们 URL（每一步都要，不只是第一步）
-   - 简要文字概括屏幕内容（例如：“正在展示首页的 3 种布局方案”）
-   - 请他们在终端中回应：“请查看后告诉我你的想法。如果愿意，可以点击选择一个选项。”
-
-3. **在你的下一轮**——用户在终端回应后：
-   - 如果存在，读取 `$STATE_DIR/events`——其中包含用户在浏览器中的交互（点击、选择），以 JSON 行格式记录
-   - 将其与用户的终端文本合并，以获得完整信息
-   - 终端消息是主要反馈；`state_dir/events` 提供结构化的交互数据
+1. **Full document.** The official preview wraps nothing and provides no ready-made CSS classes. `<div class="options">` means nothing here; nothing renders on the page.
+2. **Self-contained.** Do not reference external relative CSS or scripts — relative dependencies are bundled only when interactive preview is enabled. A single file is safest.
+3. **No outside-iframe capabilities.** The preview document does not share the host page context; `window.parent` gets nothing.
 
-4. **迭代或推进**——如果反馈改变了当前页面，写入新文件（例如 `layout-v2.html`）。仅在当前步骤已确认后再进入下一步。
-
-5. **回到终端时卸载**——当下一步不需要浏览器时（例如澄清问题、权衡讨论），推送一个等待页面以清除过时内容：
-
-    ```html
-    <!-- filename: waiting.html (or waiting-2.html, etc.) -->
-    <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
-      <p class="subtitle">Continuing in terminal...</p>
-    </div>
-    ```
-
-    这样可避免用户在对话已推进后仍盯着已解决的选择。当下一个可视化问题出现时，像往常一样推送新的内容文件即可。
-
-6. 重复上述流程直至完成。
-
-## 编写内容片段
-
-只需编写页面内部的内容。服务器会自动将其包裹到框架模板中（页头、主题 CSS、连接状态及所有交互基础设施）。
-
-**最小示例：**
+### Minimal example
 
 ```html
-<h2>Which layout works better?</h2>
-<p class="subtitle">Consider readability and visual hierarchy</p>
-
-<div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Single Column</h3>
-      <p>Clean, focused reading experience</p>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Layout options</title>
+<style>
+  body { font: 15px/1.7 system-ui, sans-serif; margin: 0; padding: 40px; }
+  h1 { font-size: 20px; margin: 0 0 6px; }
+  .subtitle { margin: 0 0 32px; color: #5b616e; }
+  .cards { display: flex; gap: 20px; flex-wrap: wrap; }
+  .card { flex: 1 1 280px; border: 1px solid #dfe2e8; border-radius: 10px; padding: 20px; }
+  .card h3 { margin: 0 0 8px; font-size: 16px; }
+  .card p { margin: 0; color: #5b616e; }
+</style>
+</head>
+<body>
+  <h1>Which layout fits better?</h1>
+  <p class="subtitle">Consider readability and visual hierarchy</p>
+  <div class="cards">
+    <div class="card">
+      <h3>A Single column</h3>
+      <p>Best reading experience, lowest information density</p>
     </div>
-  </div>
-  <div class="option" data-choice="b" onclick="toggleSelect(this)">
-    <div class="letter">B</div>
-    <div class="content">
-      <h3>Two Column</h3>
-      <p>Sidebar navigation with main content</p>
+    <div class="card">
+      <h3>B Two columns</h3>
+      <p>Higher space utilization, needs extra style constraints</p>
     </div>
   </div>
-</div>
+</body>
+</html>
 ```
 
-就是这样。无需 `<html>`、CSS 或 `<script>` 标签。服务器会提供所有这些。
+In dark environments, switch colors to follow `prefers-color-scheme` or use neutral grays.
 
-## 可用 CSS 类
+## Directory and Naming
 
-框架模板为你的内容提供以下 CSS 类：
+Convention directory: `.superpowers/brainstorm/` under the project root. Delete it yourself when the session ends.
 
-### 选项（A/B/C 选择）
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Do not reuse filenames — write a new file each iteration, `layout-v2.html`, `layout-v3.html`
+- The user opens the specific file they were told about; tell them the new filename when you rewrite
 
-```html
-<div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Title</h3>
-      <p>Description</p>
-    </div>
-  </div>
-</div>
-```
+If the project's `.gitignore` does not yet include `.superpowers/`, remind the user to add it.
 
-**多选：** 在容器上添加 `data-multiselect` 以允许用户选择多个选项。每次点击都会切换项目的选中样式。
+## Loop Flow
 
-```html
-<div class="options" data-multiselect>
-  <!-- same option markup — users can select/deselect multiple -->
-</div>
-```
+1. **Write HTML** to the convention directory with file tools, not `cat`/heredoc (they flood the terminal).
+2. **Tell the user what to expect and end the turn**:
+   - Remind the file path and how to open it in the right-hand document sidebar;
+   - Summarize in words what this page shows (e.g. "showing 3 layout options for the homepage");
+   - Ask them to answer in the terminal, and say where.
+3. **Read the user's terminal reply.** This is the only selection return channel.
+4. **Iterate or move on** — if feedback changes the current page, write a new version file.
+5. **Clean up when back in the terminal** — delete HTML files no longer needed, so the user does not see stale problems in the document sidebar.
+6. Repeat until done.
 
-### 卡片（视觉设计）
+## Per-Question Decisions
 
-```html
-<div class="cards">
-  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
-    <div class="card-image"><!-- mockup content --></div>
-    <div class="card-body">
-      <h3>Name</h3>
-      <p>Description</p>
-    </div>
-  </div>
-</div>
-```
-
-### 原型容器
-
-```html
-<div class="mockup">
-  <div class="mockup-header">Preview: Dashboard Layout</div>
-  <div class="mockup-body"><!-- your mockup HTML --></div>
-</div>
-```
-
-### 分栏视图（并排）
-
-```html
-<div class="split">
-  <div class="mockup"><!-- left --></div>
-  <div class="mockup"><!-- right --></div>
-</div>
-```
-
-### 优缺点
-
-```html
-<div class="pros-cons">
-  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
-  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
-</div>
-```
+Even after the user accepts the preview, decide per question whether it is worth drawing:
 
-### 模拟元素（线框图构建块）
+- **Use preview** for visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use terminal** for text content — requirement questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
 
-```html
-<div class="mock-nav">Logo | Home | About | Contact</div>
-<div style="display: flex;">
-  <div class="mock-sidebar">Navigation</div>
-  <div class="mock-content">Main content area</div>
-</div>
-<button class="mock-button">Action Button</button>
-<input class="mock-input" placeholder="Input field">
-<div class="placeholder">Placeholder area</div>
-```
-
-### 排版与区块
-
-- `h2` — 页面标题
-- `h3` — 区块标题
-- `.subtitle` — 标题下方的次级文本
-- `.section` — 带底部边距的内容块
-- `.label` — 小号大写标签文本
-
-## 浏览器事件格式
-
-当用户在浏览器中点击选项时，其交互会被记录到 `$STATE_DIR/events`（每行一个 JSON 对象）。当你推送新页面时，该文件会自动清空。
-
-```jsonl
-{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
-{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
-{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
-```
+A question about a UI topic is not necessarily visual. "What does personality mean in this context?" is conceptual — use the terminal. "Which wizard layout feels better?" is visual — use the preview.
 
-完整的事件流展示了用户的探索路径——他们在确定前可能会点击多个选项。最后一个 `choice` 事件通常是最终选择，但点击模式可能揭示犹豫或偏好，值得进一步询问。
-
-如果 `$STATE_DIR/events` 不存在，说明用户未与浏览器交互——仅使用其终端文本即可。
-
-## 设计建议
-
-- **根据问题匹配保真度**——布局问题用线框图，视觉打磨问题再做精细化
-- **在每页上说明问题**——“哪种布局更显专业？”而非仅仅“选一个”
-- **先迭代再推进**——如果反馈改变了当前页面，先写一个新版本
-- **每屏最多 2-4 个选项**
-- **在重要场景使用真实内容**——例如摄影作品集应使用真实图片（Unsplash）。占位内容会掩盖设计问题。
-- **保持原型简洁**——聚焦布局与结构，而非像素级完美
-
-## 文件命名
-
-- 使用语义化名称：`platform.html`、`visual-style.html`、`layout.html`
-- 不要复用文件名——每个页面必须是新文件
-- 迭代时：追加版本后缀，如 `layout-v2.html`、`layout-v3.html`
-- 服务器按修改时间提供最新的文件
-
-## 清理
-
-```bash
-bash scripts/stop-server.sh $SESSION_DIR
-```
+## Design Advice
 
-如果会话使用了 `--project-dir`，原型文件会保留在 `.superpowers/brainstorm/` 中以便后续查阅。仅 `/tmp` 会话在停止时会被删除。
+- **Match fidelity to the question** — wireframes for layout questions, polish only for visual-fidelity questions
+- **State the question on each page** — "Which looks more professional?" rather than just "pick one"
+- **Iterate before pushing** — if feedback changes the page, write a new version first
+- **At most 2-4 options per screen**
+- **Use real content for important scenarios** — real copy and colors expose problems better than placeholder text
+- **Keep mockups lean** — focus on layout and structure, not pixel perfection
 
-## 参考
+## Cleanup
 
-- 框架模板（CSS 参考）：`scripts/frame-template.html`
-- 辅助脚本（客户端）：`scripts/helper.js`
+Delete every HTML file written this session. If a project directory was used, remind the user that the directory is in `.gitignore`.

package/skills/diagnosing-superpowers/SKILL.md

@@ -1,58 +1,122 @@
 ---
 name: diagnosing-superpowers
-description: "Superpower Skill：当 superpowers 会话出错、human partner 想查原因（重复工作、忽略计划、技能未触发、耗时过长、成本过高、结果不佳）或想为维护者建缺陷报告时，适用当前或历史会话。"
+description: "Superpower Skill: Use when a superpowers session went wrong and your human partner wants to know why - repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, it took too long, why is it so expensive, what is it doing - or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness."
+description_zh: "Superpower Skill：当 superpowers 会话出错、human partner 想查原因（重复工作、忽略计划、技能未触发、耗时过长、成本过高、结果不佳）或想为维护者建缺陷报告时，适用当前或历史会话。"
 ---
 
-# 诊断 superpowers
 
-## 概览
+# Diagnosing Superpowers
 
-与你的 human partner 一起确定会话中哪里出了问题，读取磁盘上的 transcript，并基于证据报告实际发生的情况。你负责报告；你不对 superpowers 做诊断。由分诊 bundle 或 issue 的人决定 superpowers 是否要改。
+## Overview
 
-**核心原则：** 每条发现都引用 `path:line`。没有引用就没有发现。每个数字都来自 transcript 或你运行的命令，绝不来自记忆。
+Pin down with your human partner what went wrong in a session, read the
+transcripts on disk, and report what happened with evidence. You report;
+you do not diagnose superpowers. Whoever triages the bundle or the issue
+decides whether superpowers changes.
 
-## 工作流程
+**Core principle:** Every finding cites `path:line`. No citation, no
+finding. Every number comes from the transcript or from a command you ran,
+never from memory.
 
-每个步骤创建一个 todo。步骤 5–7 仅在其所述条件满足时运行。
+## Workflow
 
-1. **问题收集。** 一次只问一个问题，直到你能写出一份陈述：指明会话（们）、已知的回合范围、你的 human partner 期望什么、实际发生了什么、以及他们关心的可观察量（墙钟时间、token 数、重复动作、某个具体动作）。"耗时太长"是抱怨，不是问题陈述。同时记录目标是否为提交 superpowers 缺陷报告。
-2. **定位。** 使用 `references/session-discovery.md` 把每个会话解析为经过验证的绝对文件系统路径。通过引用其首个 prompt 与时间戳来确认历史会话，并列出你拒绝的每个候选及其原因，没有则写"无"。枚举 subagent transcript。创建 `~/.superpowers/diagnosing-superpowers/<session-id>/`，把路径告诉你的 human partner，并按 `templates/case.md` 在其中填写 case 文件，遵循其对环境与技能观察的来源（provenance）规则。
-3. **分诊。** 亲自阅读报告问题周围的区域。然后按维度并行派出分析师 subagent，每个 subagent 获得 case 文件路径、`prompts/analyst-common.md` 以及 `prompts/` 中的一个维度文件：`skill-timeline.md`、`plan-adherence.md`、`repeated-work.md`、`stumbles.md`、`quality-evidence.md`、`request-conflicts.md`、`cost-and-time.md`。transcript 较长时按回合范围拆分维度。丢弃任何缺少 `path:line` 的返回发现。
-4. **报告。** 按顺序填满 `templates/report.md` 的每一节，写入 workspace，展示并给出路径。检查引用的内容实际证明了什么，并保留支撑性 case；符号链接别名不是冗余副本。
-5. **GitHub issues** — 当报告 §7 显示"可能（possible）"或"很可能（likely）"，或你的 human partner 要求时。按 `references/github-issues.md` 搜索已开与已关闭 issue 中的症状。展示匹配项并建议把报告附加到最接近的一条。若无匹配，填写 `templates/issue.md`，写入 workspace，展示确切文本，仅在批准后创建 issue。`gh` 无法附加文件；若存在 bundle，把路径交给你的 human partner 在浏览器中附加。
-6. **导出** — 仅当你的 human partner 要求 bundle 时；绝不未经要求构建。若收集阶段的目标是缺陷报告，说一次"可按需提供已脱敏的 bundle"，然后等待。询问脱敏级别，说明各级包含什么：skeleton（无工具结果正文）、evidence（仅被引用事件有正文）、full。按 `templates/bundle-README.md` 构建 bundle，派出 `prompts/scrub.md`，然后 `prompts/scrub-audit.md`，重复两者直到审计返回 CLEAN。完成 bundle 模板的证据检查与对账后，再展示最终脱敏日志、文件清单与隐私和证据结论。仅在批准后归档（`zip -r` 或 `tar -czf`）。给出归档路径时，说明其包含内容、指出脱敏日志中的替换，并说明脱敏可能遗漏：他们必须在分享前审阅每个文件。
-7. **相似会话** — 应要求时。把已确认的发现转为签名（signature），按 mtime 与大小列出候选，找出标记行号，对每个候选并行派出 `prompts/similar-session.md`，并把报告 §9 追加进去。
+Create a todo per step. Steps 5–7 run only on their stated condition.
 
-## 快速参考
+1. **Problem intake.** Ask one question at a time until you can write a
+   statement naming the session(s), the turn range if known, what your
+   partner expected, what happened, and the observable they care about
+   (wall-clock, tokens, repeated actions, one specific action). "It took
+   too long" is a complaint, not a problem statement. Note whether the
+   goal is a superpowers bug report.
+2. **Locate.** Resolve each session to verified absolute filesystem paths using
+   `references/session-discovery.md`. Confirm a past session by quoting its
+   first prompt and timestamp, and list every candidate you rejected with the
+   reason, or "none". Enumerate subagent transcripts. Create
+   `~/.superpowers/diagnosing-superpowers/<session-id>/`, tell your
+   partner the path, and fill `templates/case.md` there, following its
+   provenance rules for environment and skill observations.
+3. **Triage.** Read the region around the reported problem yourself. Then
+   dispatch one analyst subagent per dimension in parallel, each given the
+   case file path, `prompts/analyst-common.md`, and one dimension file from
+   `prompts/`: `skill-timeline.md`,
+   `plan-adherence.md`, `repeated-work.md`, `stumbles.md`,
+   `quality-evidence.md`, `request-conflicts.md`, `cost-and-time.md`.
+   Split a dimension by turn range when the transcript is long. Discard
+   any returned finding without `path:line`.
+4. **Report.** Fill every section of `templates/report.md` in order, write
+   it to the workspace, show it, and give the path. Check what cited content
+   actually proves and preserve the supporting case; a symlink alias is not a
+   redundant copy.
+5. **GitHub issues** — when report §7 says possible or likely, or your
+   partner asks. Search open and closed issues for the symptoms per
+   `references/github-issues.md`. Show matches and suggest adding the
+   report to the closest. If none match, fill `templates/issue.md`, write
+   it to the workspace, show the exact text, and create the issue only
+   after approval. `gh` cannot attach files; if a bundle exists, give
+   your partner its path to attach in the browser.
+6. **Export** — only when your partner asks for a bundle; never build one
+   unprompted. If the intake goal was a bug report, say once that a
+   scrubbed bundle is available on request, then wait. Ask the redaction
+   level, stating what each includes: skeleton (no tool-result bodies),
+   evidence (bodies only for cited events), full. Build the bundle per
+   `templates/bundle-README.md`, dispatch `prompts/scrub.md`, then
+   `prompts/scrub-audit.md`, repeating both until the audit returns CLEAN.
+   Complete the bundle template's evidence check and reconciliation before
+   showing the final scrub log, file list, and privacy and evidence outcomes.
+   Archive (`zip -r` or `tar -czf`) only after approval. With the archive
+   path, state what it contains, point at the scrub log for replacements, and
+   say scrubbing can miss things: they must review every file before sharing.
+7. **Similar sessions** — when asked. Turn confirmed findings into a
+   signature, list candidates by mtime and size, find marker line numbers,
+   dispatch `prompts/similar-session.md` per candidate in parallel, and
+   append report §9.
 
-七个分析师始终运行。本表说明步骤 3 中你要亲自读哪个区域，以及在结论中优先展示哪些发现。
+## Quick reference
 
-| 抱怨 | 先读，优先展示 |
+All seven analysts always run. This table says which region to read
+yourself in step 3 and which findings to lead with in the verdict.
+
+| Complaint | Read first, lead with |
 |---|---|
-| "耗时太长" | cost-and-time, stumbles |
-| "为什么做了这份额外工作？" | repeated-work, plan-adherence |
-| "为什么这么贵？" | cost-and-time |
-| "它在搞什么鬼？"（仍在运行） | skill-timeline；在覆盖范围注明进行中 |
-| "它忽略了计划" | plan-adherence，压缩行优先 |
-| "技能 X 从未触发" | skill-timeline |
-
-## 铁律
-
-- **上下文安全。** 一行 transcript 可能有一兆字节。对每个会话文件的每次读取都遵循 `references/context-safety.md`。
-- **只读。** 绝不修改、移动或删除会话文件。
-- **给 subagent 的绝对路径。** subagent 的"当前会话"是它自己的。传递绝对路径与 id。
-- **仅限人类 prompt。** 钩子输出、系统提醒与工具结果不是你的 human partner 的话。在 subagent transcript 中，"user"是父代理。
-- **不做 superpowers 诊断。** 报告 §7 说明参与程度并就此打住。绝不在技能中指认缺陷或提出修改。你的 human partner 催促修复并不豁免这一点；指向 issue 步骤并提及可按需提供 bundle。也不给你的 human partner 任何建议。
-- **审批关卡。** 在你的 human partner 看到脱敏日志与文件清单之前，不归档。他们批准确切文本之前，不创建 issue 或评论。
-- **分析前先收集。** 步骤 2–7 的任何事情都要等你的 human partner 回答后才开始。若他们不在，写下问题并停止。你为他们重构的陈述不是回答。已界定范围的请求——某个具体事件、现在正在运行什么、或要运行的分析——本身就是陈述：先回答它，再提问。对整个会话的"为什么"是抱怨。
-
-## 红旗
-
-| 想法 | 实际情况 |
+| "It took too long" | cost-and-time, stumbles |
+| "Why did it do this extra work?" | repeated-work, plan-adherence |
+| "Why is it so expensive?" | cost-and-time |
+| "What the hell is it doing?" (still running) | skill-timeline; note in-progress in coverage |
+| "It ignored the plan" | plan-adherence, compaction lines first |
+| "Skill X never fired" | skill-timeline |
+
+## Hard rules
+
+- **Context safety.** One transcript line can be a megabyte. Follow
+  `references/context-safety.md` on every session file, every time.
+- **Read-only.** Never modify, move, or delete a session file.
+- **Exact paths to subagents.** A subagent's "current session" is its
+  own. Pass absolute paths and ids.
+- **Human prompts only.** Hook output, system reminders, and tool results
+  are not your partner's words. In a subagent transcript, "user" is the
+  parent agent.
+- **No superpowers diagnosis.** Report §7 states involvement and stops.
+  Never name a defect in a skill or propose a change. Your partner
+  pressing for a fix does not waive this; point at the issue step and
+  mention that a bundle is available on request. No advice to your
+  partner either.
+- **Approval gates.** No archive before your partner has seen the scrub
+  log and file list. No issue or comment before they approve the exact
+  text.
+- **Intake before analysis.** Nothing in steps 2–7 starts until your
+  partner has answered. If they are away, write the questions and stop.
+  A statement you reconstructed for them is not an answer. An
+  already-scoped request — one specific event, what is running now, or
+  the analysis to run — is itself the statement: answer it, then ask.
+  A whole-session "why" is a complaint.
+
+## Red Flags
+
+| Thought | Reality |
 |---------|---------|
-| "问题很明显，跳过收集" | 问题陈述界定了所有范围。问。 |
-| "他们不在，我重构陈述" | 你无法重构他们想要的东西。写下问题并停止。 |
-| "我先全量扫描，最后再问" | 未界定范围的扫描把他们的预算花在错误的问题上。先问。 |
-| "他们要缺陷报告，我这就构建 bundle" | bundle 是他们的会话数据被打包。仅当他们要求时才构建。 |
-| "小范围、有针对性的编辑，无需重构" | 这不是你说了算，无论多小。报告证据；由分诊者决定。 |
-| "每 token 的价格众所周知" | 你不是从 transcript 算出的数字都是编造的。引用或删除。 |
+| "The problem is obvious, skip intake" | The problem statement scopes everything. Ask. |
+| "They're away, so I'll reconstruct the statement" | You cannot reconstruct what they wanted. Write the questions and stop. |
+| "I'll sweep everything now and ask at the end" | An unscoped sweep spends their budget on the wrong question. Ask first. |
+| "They want a bug report, so I'll build the bundle now" | The bundle is their session data, packaged. Build it only when they ask for it. |
+| "Small, targeted edit, no restructuring needed" | Not your call, however small. Report the evidence; the triager decides. |
+| "The price per token is well known" | Numbers you did not compute from the transcript are invented. Cite or drop. |

package/skills/diagnosing-superpowers/prompts/analyst-common.md

@@ -1,24 +1,38 @@
-你是分析师 subagent。你读取磁盘上的编码代理会话 transcript，并返回带证据的发现。你不修复任何东西，不修改会话存储下的任何文件，也不说 superpowers 应该改什么。
-
-输入（来自你的派发者）：
-- CASE：case 文件的绝对路径。先读它。它指明会话文件、要使用的已发现来源与记录含义，以及你必须遵守的上下文安全规则。使用已记录的含义，而不是重复发现或假定 harness 格式。
-- RANGE（可选）：回合范围或行范围。若存在，只分析该范围，并在你的 Checked 行中说明。
-
-上下文安全：读取每个文件前，遵循 CASE 中点名的 `references/context-safety.md`，并用已记录的命令或查询提取字段。"当前会话"不是你能查看的东西：只使用 CASE 中的路径。
-
-人类 prompt 是 case 文件识别为人类输入的记录。钩子输出、系统提醒与工具结果不是人类 prompt。在 subagent transcript 中，"user"是父代理。
-
-返回格式（无其他内容）：
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+  files, the discovered sources and record meanings to use, and the
+  context-safety rules you must follow. Use the recorded meanings rather than
+  repeating discovery or assuming a harness format.
+- RANGE (optional): a turn range or line range. If present, analyze only
+  that range and say so in your Checked line.
+
+Context safety: follow `references/context-safety.md`, named in CASE, on
+every file before reading it, and extract fields with the recorded commands or
+queries. "The current session" is not a thing you can look at: use only the
+paths in CASE.
+
+Human prompts are the records the case file identifies as human-typed. Hook
+output, system reminders, and tool results are not human prompts. In a subagent
+transcript, "user" is the parent agent.
+
+Return format (nothing else):
 
 ```
-## <维度> 发现
+## <Dimension> findings
 
-- finding: <一句话，发生了什么>
-  evidence: <绝对路径>:<行> — "<引文，至多 200 字符>"
-  turns: <首个人类回合>–<末个人类回合>
-  confidence: 高 | 中 | 低
+- finding: <one sentence, what happened>
+  evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+  turns: <first human turn>–<last human turn>
+  confidence: high | medium | low
 
-Checked: <你检查了什么：文件、行范围、用到的命令>
+Checked: <what you examined: files, line ranges, commands used>
 ```
 
-派发者丢弃任何缺少 `path:line` 的发现，所以不要写这样的发现。若你什么都没找到，返回 `- none found` 与 Checked 行。
+The dispatcher discards any finding without a `path:line`, so do not
+write one. If you found nothing, return `- none found` and the Checked
+line.

package/skills/diagnosing-superpowers/prompts/cost-and-time.md

@@ -1,12 +1,28 @@
-先读 `prompts/analyst-common.md`；它给出你的角色、输入、上下文安全规则与返回格式。本文件补充维度。
+Read `prompts/analyst-common.md` first; it gives your role, inputs,
+context-safety rules, and the return format. This file adds the dimension.
 
-维度：成本与时间
+Dimension: Cost and time
 
-核算 token 与墙钟时间花在哪里。
+Account for where tokens and wall-clock went.
 
-1. Token。只使用 case 文件中确立的用量记录与计数器含义。计算总计前先说清每个计数器是增量还是累计；对累计观测做差分，且不把缺失观测变成零。报告支撑总量最大的五个回合，以及每个关联会话的支撑总量。
-2. 墙钟时间。使用 case 文件中记录的、有证据的时间戳字段、事件边界与单位。报告支撑时间最长的五个回合，以及相邻事件之间超过十分钟的任何间隔（空闲、等待关联会话、或等待你的 human partner；记录显示是哪种才说哪种）。
-3. 最大的工具结果：使用 case 文件有证据的工具结果记录，报告最大的十个结果及其工具与回合。提取有界内容前先量记录。
-4. 压缩：统计并定位在发现阶段确立含义为压缩事件的记录。报告可用的前后计数器，以及每次触发时会话在做什么；缺失的字段标记为不存在。
-5. 关联会话：统计数量，并报告每个的支撑用量、时长与派发回合。
-6. 报告主导总量的回合、subagent、工具或重复，附数字。除 transcript 显示的内容外，不要推测回合昂贵的原因。
+1. Tokens. Use only the usage records and counter meanings established in the
+   case file. State whether each counter is incremental or cumulative before
+   calculating totals; difference cumulative observations without turning a
+   missing observation into zero. Report the five turns with the largest
+   supported totals and the supported totals per associated session.
+2. Wall-clock. Use the evidenced timestamp fields, event boundaries, and units
+   recorded in the case file. Report the five longest supported turns and any
+   gap longer than ten minutes between consecutive events (idle, waiting on an
+   associated session, or waiting on your human partner; say which only when
+   the records show it).
+3. Largest tool results: use the case file's evidenced tool-result records to
+   report the ten largest results with their tool and turn. Measure records
+   before extracting bounded content.
+4. Compactions: count and locate records whose meaning as compaction events was
+   established during discovery. Report available before/after counters and
+   what the session was doing when each fired; mark unsupported fields absent.
+5. Associated sessions: count them and report supported usage, duration, and
+   dispatching turn for each.
+6. Report the turns, subagents, tools, or repeats that dominate the
+   totals, with numbers. Do not speculate about why a
+   turn was expensive beyond what the transcript shows.