running-bug-review-board

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Running the Bug Review Board (BRB) QA pass

执行Bug Review Board（BRB）QA测试

This skill runs a real-user QA pass on an app and feeds the output into a Bug Review Board: a folder of structured bug reports, per-pass run reports, a self-contained HTML dashboard, and a final YES/NO sign-off the team can act on. Engineering's tracker (Linear / GitHub / Jira / Notion) syncs bi-directionally so QA and engineering stay in step.

It generalizes a battle-tested workflow that already shipped phase QA on Mokuhoe — the techniques are repo-agnostic.

本技能会对应用执行真实用户QA测试，并将输出结果导入Bug Review Board：一个包含结构化漏洞报告、每次测试运行报告、独立HTML仪表盘的文件夹，以及团队可据此采取行动的最终YES/NO验收结论。工程团队的追踪器（Linear / GitHub / Jira / Notion）支持双向同步，确保QA与工程团队保持步调一致。

它整合了一套经过实战检验的工作流程，该流程已在Mokuhoe项目的阶段QA中成功应用——相关技术与代码仓库无关。

Why this exists

设计初衷

Most engineers test their own code. They confirm what they wrote works. That misses the bugs real users hit first — stale state across flows, mobile overflow, copy that lies, paths that 404 mid-onboarding, race conditions between auth and routing.

This skill simulates a real user. The QA agent acts like a careful, mildly unforgiving customer who does not read the source code.

大多数工程师会自行测试代码，确认自己编写的功能正常运行。但这会遗漏真实用户最先遇到的漏洞——跨流程的 stale state、移动端内容溢出、误导性文案、注册流程中出现404的路径、认证与路由之间的竞态条件等。

本技能模拟真实用户行为，QA Agent会像一位细心且略带挑剔的客户那样操作应用，不会查看源代码。

Two workflows — Auto QA and Interactive BRB

两种工作流——自动QA与交互式BRB

The skill splits the work into two distinct modes that share artifacts but run in separate sessions on purpose:

Auto QA pass — the agent drives the app, runs scenarios, files bugs, generates the HTML report, writes a verdict. Optimized for thoroughness and speed.
Interactive BRB — a different agent meets with the user to triage open / in-progress / fixed bugs. Runs the bi-directional pull first, applies pattern-based heuristics to surface duplicates and clusters, walks each bug, flips statuses, syncs to the tracker, regenerates HTML, writes minutes. Optimized for shared judgment.

Keep them separate. Running BRB inside an auto pass lets triage bias contaminate discovery and confuses attribution. See references/brb-interactive.md.

该技能将工作拆分为两种截然不同的模式，它们共享工件但特意在单独会话中运行：

自动QA测试——Agent驱动应用、运行测试场景、提交漏洞、生成HTML报告、给出结论。以全面性和速度为优化目标。
交互式BRB——由另一个Agent与用户协作，对未处理/处理中/已修复的漏洞进行分类。首先执行双向同步，基于模式化启发式规则识别重复漏洞和漏洞集群，逐一梳理漏洞、更新状态、同步至追踪器、重新生成HTML报告并记录会议纪要。以协同决策为优化目标。

请将两者分开运行。在自动测试会话中运行BRB会让分类偏见影响漏洞发现过程，并导致归属混淆。详情请见references/brb-interactive.md。

The trifecta — three hats, one pass

三位一体——一次测试，三重角色

For every pass, wear all three hats:

Product Manager. Confirm the build delivers the user-visible promise documented in the product spec or phase doc. If it does not, that is a product gap, not a bug — flag it in the run report.
QA. Execute every scenario from a real user's perspective on the primary supported viewport(s). Capture evidence (snapshot, console, server data when relevant). Pass / Fail / Blocked.
Engineer. Watch for invalidated assumptions: phase doc says "X uses function Y" but Y was renamed; new client orchestration appeared in a flow the docs say is server-driven; fields exist in UI that aren't in the spec. Finding gaps is the point — don't reverse- engineer the docs to match buggy behavior.

Do not fix product code unless the user explicitly asks. Test, document, file bugs, hand off.

每次测试都要兼顾以下三个角色：

产品经理：确认构建版本是否实现了产品规格或阶段文档中承诺的用户可见功能。若未实现，这属于产品缺口而非漏洞——需在运行报告中标记出来。
QA测试人员：从真实用户的视角在主要支持的视口上执行所有测试场景。捕获证据（快照、控制台日志、相关的服务器数据）。标记通过/失败/阻塞状态。
工程师：留意无效假设：阶段文档称“X使用函数Y”但Y已被重命名；文档说明由服务器驱动的流程中出现了新的客户端编排逻辑；UI中存在规格未提及的字段。发现缺口是核心目标——不要为了匹配有问题的行为而反向修改文档。

除非用户明确要求，否则不要修改产品代码。只需测试、记录、提交漏洞并移交。

Discover the app first (or you'll write bad tests)

先了解应用（否则会写出糟糕的测试用例）

Before writing a single test, understand the intent of the app — what the customer is hired to do with it. See references/discovering-the-app.md for the full investigation playbook. The short version:

Read the product spec / README / landing page / pitch deck (in that priority order) for what the app promises.
Read the phase doc (or current sprint plan) for what was just built.
Read prior QA gates / checklists for what passed before — regressions are your highest-value finds.
Read the bug-reports index — open bugs are scenarios you must re-test first.
Detect the project type(s). A repo can ship more than one app — a web + iOS monorepo is common — so collect every surface whose signals are present instead of stopping at the first hit. Two disambiguation rules resolve overlapping signals inside a single app; they are not a reason to skip a genuinely separate surface:
- Electron / Tauri beats Web app for the same app. An Electron / Tauri project (
```
electron
```
  ,
```
@electron/
```
  ,
```
@tauri-apps/
```
  in
```
package.json
```
  , or
```
electron-builder.yml
```
  /
```
tauri.conf.json
```
  ) also contains
```
package.json
```
  and web framework deps, but those deps belong to the desktop app — count it once as a desktop app, do not also count it as a separate Web app.
- macOS vs iOS on a shared
  *.xcodeproj
  /
  *.xcworkspace
  . A bare Xcode project is shared between the two, so don't classify on it alone — require a platform-specific marker (below).
The surfaces, with the playbook each activates:
- Electron / Tauri desktop app → use computer-use-playbook.md. (On non-macOS hosts where Computer Use is unavailable, the playbook's graceful-degradation table directs you to drive the app's dev-server URL via browser-playbook.md instead.)
- Web app (web framework deps without Electron / Tauri markers) → use browser-playbook.md.
- iOS / iPadOS app (an iOS-specific marker is present —
```
.iOS(...)
```
  ,
```
platform :ios
```
  ,
```
UIDeviceFamily
```
  , or an
```
ios/
```
  directory) → use ios-simulator-playbook.md.
- Native macOS app (a macOS-specific marker is present —
```
.macOS(...)
```
  , a
```
.app
```
  bundle, or
```
LSMinimumSystemVersion
```
  — and no iOS marker) → use computer-use-playbook.md.
- Mixed (monorepo) — signals for two or more distinct surfaces above (e.g. web framework deps and an iOS marker) → run every matched playbook; the test plan gets per-platform scenario blocks. A web match must never short-circuit a co-located iOS (or macOS) pass.
- Other (no UI signals) → no UI playbook activates.
Also note whether Codex Computer Use is available (macOS only) — it enables a human-fidelity pass on web apps and is the only way to reach a native Mac or Electron/Tauri app. Most VMs (Cursor cloud, CI) won't have it, so never make the pass depend on it.
Detect the issue tracker (Linear, GitHub, Jira, Notion, or none). Surface every signal found and ask the user to confirm before writing
```
qa-config.json
```
. See issue-trackers.md.
List the public routes / surfaces / entry points and decide which a real new user would touch.

If the user says "QA this app" but no docs exist, ask — see references/discovering-the-app.md § Asking the user.

在编写任何测试用例之前，先理解应用的意图——客户使用它的目的是什么。完整的调研指南请见references/discovering-the-app.md。以下是精简版步骤：

按优先级阅读产品规格/README/登录页面/演示文稿，了解应用承诺提供的功能。
阅读阶段文档（或当前冲刺计划），了解刚完成的功能。
阅读之前的QA检查点/清单，了解之前通过的内容——回归漏洞是最有价值的发现。
阅读漏洞报告索引——未处理的漏洞是你必须优先重新测试的场景。
检测项目类型。一个代码仓库可能包含多个应用——网页+iOS单体仓库很常见——因此要收集所有存在信号的界面，不要在找到第一个匹配项后就停止。以下两条歧义消除规则用于解决单个应用内的重叠信号；它们不是跳过真正独立界面的理由：
- 同一应用中，Electron/Tauri优先于网页应用。Electron/Tauri项目（
```
package.json
```
  中包含
```
electron
```
  、
```
@electron/
```
  、
```
@tauri-apps/
```
  ，或存在
```
electron-builder.yml
```
  /
```
tauri.conf.json
```
  ）也会包含
```
package.json
```
  和网页框架依赖，但这些依赖属于桌面应用——应将其仅算作一次桌面应用测试，不要同时将其视为独立的网页应用。
- 共享
  *.xcodeproj
  /
  *.xcworkspace
  的macOS与iOS应用。仅靠Xcode项目无法区分两者，因此需要特定平台的标记（如下所示）。
不同界面及其对应的测试指南：
- Electron/Tauri桌面应用 → 使用computer-use-playbook.md。（在无法使用Computer Use的非macOS主机上，指南中的优雅降级表会引导你通过browser-playbook.md驱动应用的开发服务器URL。）
- 网页应用（存在网页框架依赖但无Electron/Tauri标记）→ 使用browser-playbook.md。
- iOS/iPadOS应用（存在iOS特定标记——
```
.iOS(...)
```
  、
```
platform :ios
```
  、
```
UIDeviceFamily
```
  或
```
ios/
```
  目录）→ 使用ios-simulator-playbook.md。
- 原生macOS应用（存在macOS特定标记——
```
.macOS(...)
```
  、
```
.app
```
  包或
```
LSMinimumSystemVersion
```
  ，且无iOS标记）→ 使用computer-use-playbook.md。
- 混合类型（单体仓库）——存在上述两种或多种不同界面的信号（例如网页框架依赖和iOS标记）→ 运行所有匹配的测试指南；测试计划会按平台划分场景模块。网页匹配绝不能中断共存的iOS（或macOS）测试。
- 其他类型（无UI信号）→ 不启用任何UI测试指南。
同时注意是否支持Codex Computer Use（仅macOS可用）——它能实现网页应用的高保真测试，也是测试原生Mac或Electron/Tauri应用的唯一方式。大多数虚拟机（Cursor云、CI环境）不支持该功能，因此测试不要依赖它。
检测问题追踪器（Linear、GitHub、Jira、Notion或无）。列出所有发现的信号，并请用户确认后再编写
```
qa-config.json
```
。详情请见issue-trackers.md。
列出公开路由/界面/入口点，判断真实新用户会接触哪些内容。

如果用户要求“对这个应用进行QA测试”但没有相关文档，请询问用户——详情请见references/discovering-the-app.md § Asking the user。

Workflow (any phase, any repo)

工作流（适用于任何阶段、任何仓库）

1. Scope        → which surface / phase / build
2. Discover     → product intent + recent change + open bugs
                + project type + issue tracker (confirmed)
3. Plan         → manual test plan (scenarios, IDs, expected, gates)
4. Prepare      → env, build, test accounts, viewport / device matrix
5. Mode         → parallel coordinator OR sequential wrap-up
6. Execute      → real-user scenarios with evidence
7. File bugs    → P0/P1/P2 with reproduction steps
8. Merge        → results + verdict (YES/NO + open P0/P1)
9. Generate HTML → apply html-report-style-guide.md
10. Hand off    → next QA agent (if NO) or engineering (if blockers)
11. Schedule BRB → separate session for interactive triage

Detail in references/workflow.md.

1. 确定范围 → 测试哪个界面/阶段/构建版本
2. 调研 → 产品意图+近期变更+未处理漏洞
          +项目类型+问题追踪器（已确认）
3. 制定计划 → 手动测试计划（场景、ID、预期结果、检查点）
4. 准备 → 环境、构建版本、测试账号、视口/设备矩阵
5. 选择模式 → 并行协调或串行收尾
6. 执行 → 真实用户场景测试并收集证据
7. 提交漏洞 → 包含复现步骤的P0/P1/P2级漏洞报告
8. 合并结果 → 测试结果+结论（YES/NO+未处理的P0/P1漏洞）
9. 生成HTML报告 → 遵循html-report-style-guide.md
10. 移交 → 交给下一位QA Agent（若结论为NO）或工程团队（若存在阻塞问题）
11. 安排BRB会话 → 单独会话进行交互式漏洞分类

详细内容请见references/workflow.md。

Mode picker

模式选择器

Situation	Mode	Reference
Fresh full pass on a phase, multi-agent OK	Parallel coordinator	references/parallel-coordinator.md
Fresh full pass and the `waves` / `waves-codex` skill is installed	Parallel coordinator, run as a bounded wave (coverage gate, structured handoffs, tiered verification, cheap-model shards)	references/parallel-coordinator.md § Run the pass as a wave
Prior parallel run stalled or partial	Sequential wrap-up	references/sequential-wrapup.md
Solo agent, small surface	Sequential, ordered top-to-bottom	references/sequential-wrapup.md
Re-testing 1–3 fixed bugs after engineering shipped	Sequential, scoped to bug Test IDs	references/sequential-wrapup.md
Need to triage the open bug backlog with the human	Interactive BRB (separate session)	references/brb-interactive.md
Repo is a native macOS app, or you want a human-fidelity pass on the real signed-in app	Auto pass + Computer Use playbook (macOS)	references/computer-use-playbook.md
Repo is an iOS / iPadOS app	Auto pass + iOS playbook (use a companion skill for input)	references/ios-simulator-playbook.md
No test plan exists yet	Generate plan first	references/test-plan.md
Phase doc lists features not yet implemented in code	Stop. Tell user — QA needs a working build	—

场景	模式	参考文档
针对某个阶段的全新完整测试，允许多Agent并行	并行协调	references/parallel-coordinator.md
全新完整测试且已安装 `waves` / `waves-codex` 技能	并行协调，作为有限wave运行（覆盖检查点、结构化移交、分层验证、低成本模型分片）	references/parallel-coordinator.md § Run the pass as a wave
之前的并行测试停滞或不完整	串行收尾	references/sequential-wrapup.md
单Agent测试，界面规模小	串行，从上到下依次执行	references/sequential-wrapup.md
工程团队修复漏洞后，重新测试1-3个已修复漏洞	串行，限定在漏洞Test ID范围内	references/sequential-wrapup.md
需要与用户协作分类未处理漏洞积压	交互式BRB（单独会话）	references/brb-interactive.md
仓库是原生macOS应用，或需要对已登录的真实应用进行高保真测试	自动测试+Computer Use指南（macOS）	references/computer-use-playbook.md
仓库是iOS/iPadOS应用	自动测试+iOS指南（使用配套技能进行输入操作）	references/ios-simulator-playbook.md
尚无测试计划	先生成测试计划	references/test-plan.md
阶段文档列出的功能尚未在代码中实现	停止测试。告知用户——QA测试需要可运行的构建版本	—

Surfaces — which playbook activates

界面——启用哪个测试指南

Detected during the discovery step. Match repo signals to the playbook(s) for every surface present — usually one, but a monorepo matches more than one (see Mixed below). Record the choice(s) in

docs/qa/qa-config.json

so later passes don't re-litigate it.

Surface	Signals	Playbook
Electron / Tauri desktop app (check first — beats Web app)	`electron` , `@electron/` , or `@tauri-apps/` in `package.json` ; `electron-builder.yml` ; `tauri.conf.json`	computer-use-playbook.md
Web app	`package.json` with web framework deps (no Electron / Tauri markers), `app/` / `pages/` / `src/routes/` , deploy config for Vercel / Netlify / Cloudflare	browser-playbook.md (add Computer Use for a human-fidelity pass on a Mac)
iOS / iPadOS app	`Package.swift` with `.iOS(...)` , `Podfile` with `platform :ios` , `Info.plist` with `UIDeviceFamily` , `ios/` directory (bare `.xcodeproj` / `.xcworkspace` are shared with macOS — require at least one of these iOS-specific markers)	ios-simulator-playbook.md
Native macOS app	`Package.swift` with `.macOS(...)` , a `.app` bundle, `Info.plist` with `LSMinimumSystemVersion`	computer-use-playbook.md
Mixed (monorepo)	Signals for two or more distinct surfaces above (e.g. web + iOS) — a web match must not short-circuit the iOS / macOS pass	Run every matched playbook — the test plan gets per-platform scenario blocks
CLI / library / backend	No UI signals	Neither UI playbook; QA focuses on integration tests + error paths

For iOS app QA, our skill orchestrates (discovery, test plan, bug filing, BRB) and defers the simulator driving to one of the iOS community's purpose-built skills — AXe (Cameron Cooke), XcodeBuildMCP (Cameron Cooke / Sentry), ios-simulator-skill (Conor Luddy), ios-build-verify (Josh Adams), baguette (tddworks), ios-idb-skill (Hao Wu), serve-sim-skill (malopezr7), swiftui-autotest-skill (Yusuf Karan), xcode-build-skill (pzep1), and App Store Connect CLI + skills (Rudrank Riyam) for the TestFlight hand-off. See the playbook for the recommended-stack table.

在调研步骤中检测。将仓库信号与所有匹配的界面测试指南对应——通常是一个，但单体仓库可能匹配多个（见下文混合类型）。将选择结果记录在

docs/qa/qa-config.json

中，避免后续测试重复确认。

界面	信号	测试指南
Electron/Tauri桌面应用（优先检查——优先级高于网页应用）	`package.json` 中包含 `electron` 、 `@electron/` 或 `@tauri-apps/` ；存在 `electron-builder.yml` ；存在 `tauri.conf.json`	computer-use-playbook.md
网页应用	`package.json` 包含网页框架依赖（无Electron/Tauri标记），存在 `app/` / `pages/` / `src/routes/` ，存在Vercel/Netlify/Cloudflare部署配置	browser-playbook.md（在Mac上添加Computer Use可实现高保真测试）
iOS/iPadOS应用	`Package.swift` 包含 `.iOS(...)` ， `Podfile` 包含 `platform :ios` ， `Info.plist` 包含 `UIDeviceFamily` ，存在 `ios/` 目录（仅 `.xcodeproj` / `.xcworkspace` 与macOS共享——至少需要一个上述iOS特定标记）	ios-simulator-playbook.md
原生macOS应用	`Package.swift` 包含 `.macOS(...)` ，存在 `.app` 包， `Info.plist` 包含 `LSMinimumSystemVersion`	computer-use-playbook.md
混合类型（单体仓库）	存在上述两种或多种不同界面的信号（例如网页+iOS）——网页匹配不能中断iOS/macOS测试	运行所有匹配的测试指南——测试计划会按平台划分场景模块
CLI/库/后端	无UI信号	不启用任何UI测试指南；QA测试重点为集成测试+错误路径

对于iOS应用QA，本技能负责编排（调研、测试计划、漏洞提交、BRB），并将模拟器驱动操作交给iOS社区的专用技能——AXe（Cameron Cooke）、XcodeBuildMCP（Cameron Cooke/Sentry）、ios-simulator-skill（Conor Luddy）、ios-build-verify（Josh Adams）、baguette（tddworks）、ios-idb-skill（Hao Wu）、serve-sim-skill（malopezr7）、swiftui-autotest-skill（Yusuf Karan）、xcode-build-skill（pzep1），以及用于TestFlight移交的App Store Connect CLI+技能（Rudrank Riyam）。推荐栈表格请见测试指南。

Issue tracker integration

问题追踪器集成

The skill discovers and confirms — it never assumes. The discovery ceremony probes signals (

LINEAR_API_KEY

gh auth status

, Atlassian URL, registered MCP servers, etc.) and surfaces every finding to the user before writing

docs/qa/qa-config.json

. Once confirmed, the agent files bugs locally and syncs to the tracker (push at file time or BRB time per config) and pulls engineering's status changes back (default ON for BRB start). Bi-directional reconciliation rules are spelled out in the reference so divergences surface as user-decision diffs, never silent overwrites.

Tracker IDs live in the bug front-matter —

Tracker / Linear

Tracker / GitHub

Tracker / Jira

Tracker / Notion

Tracker / lastSyncedAt

. The HTML report renders them as tags on every bug card.

Helpers:

scripts/bugs-needing-sync.sh

lists bugs missing tracker IDs (push candidates).

scripts/bugs-needing-pull.sh

lists bugs whose

Tracker / lastSyncedAt

is stale (pull candidates).

本技能会调研并确认——绝不假设。调研流程会探测信号（

LINEAR_API_KEY

、

gh auth status

、Atlassian URL、已注册的MCP服务器等），并在编写

docs/qa/qa-config.json

前将所有发现告知用户确认。确认后，Agent会在本地提交漏洞并同步至追踪器（根据配置在提交时或BRB会话时推送），并拉取工程团队的状态变更（BRB会话开始时默认启用）。参考文档中明确了双向协调规则，确保分歧以用户决策差异的形式呈现，而非静默覆盖。

追踪器ID位于漏洞前置信息中——

Tracker / Linear

、

Tracker / GitHub

、

Tracker / Jira

、

Tracker / Notion

、

Tracker / lastSyncedAt

。HTML报告会在每个漏洞卡片上将其渲染为标签。

辅助脚本：

scripts/bugs-needing-sync.sh

列出缺少追踪器ID的漏洞（待推送候选）。

scripts/bugs-needing-pull.sh

列出

Tracker / lastSyncedAt

已过期的漏洞（待拉取候选）。

HTML report (Zite + Dieter Rams)

HTML报告（Zite + Dieter Rams风格）

At the end of every pass and every BRB session, regenerate

docs/qa/report/index.html

plus per-bug and per-run detail pages by applying html-report-style-guide.md.

The report reads like a magazine, not a Kanban board. Typography does the work — priority is the word

P0

in small caps, status is the word

Open

, verdict is a single display-type word (

YES

NO

). One ink colour for body, one quiet terracotta accent for links and CTAs, hairline rules for separation. No coloured chips, no pills, no shadows. A 640px reading column on every screen size; on desktop, bug detail pages add a quiet right rail for metadata. On mobile, a sticky thumb-zone duplicates the primary action so the reader doesn't have to scroll back up.

The information hierarchy is engineered for the engineer-reviewer's sweep: Title → Deck → Impact → Actual / Expected → Risk to fix → Steps → Evidence. The bug template grew

Impact

and

Risk to fix

sections in v0.3 (additive — old bugs render gracefully without them).

Markdown stays the source of truth. HTML is read-only and regenerated. Never edit the HTML to change bug state — edit the markdown and regenerate. The dashboard is what stakeholders open during BRB and ship reviews.

每次测试和BRB会话结束后，根据html-report-style-guide.md重新生成

docs/qa/report/index.html

以及每个漏洞和每次测试的详情页面。

报告风格类似杂志，而非看板。排版传递信息——优先级使用小型大写字母的

P0

，状态使用

Open

，结论使用单个醒目单词（

YES

或

NO

）。正文使用一种颜色，链接和CTA使用柔和的赤陶色作为强调色，使用细线条分隔内容。无彩色芯片、胶囊按钮或阴影。所有屏幕尺寸均采用640px阅读栏；桌面端漏洞详情页面右侧添加安静的元数据侧边栏；移动端添加粘性拇指操作区，复制主要操作按钮，避免用户滚动返回顶部。

信息层级专为工程师评审设计：标题 → 概述 → 影响 → 实际/预期结果 → 修复风险 → 复现步骤 → 证据。漏洞模板在v0.3版本新增了

影响

和

修复风险

部分（向后兼容——旧漏洞无此部分也能正常显示）。

Markdown始终是事实来源。HTML为只读文件，需重新生成。绝不要通过编辑HTML来修改漏洞状态——编辑Markdown后重新生成即可。仪表盘是利益相关者在BRB和发布评审时查看的内容。

Pattern-based triage suggestions

基于模式的分类建议

The Interactive BRB opens with a Suggestions card surfaced by a catalog of named heuristics in triage-heuristics.md — same suspect file, steps-prefix overlap, same console error, same persona+surface+ outcome, phase cascade, cosmetic cluster, regression marker, same owner. Every suggestion cites a heuristic name and the matching text so the user always sees why something was flagged. No embeddings, no LLM API, no auto-merge. The agent suggests; the user decides.

The same heuristics are also opt-in during the auto pass at file time (

triage.runHeuristicsOnFile

, default

false

) so the pass can ask "file new, or update BUG-007?" instead of double-filing.

交互式BRB会话开始时，会展示一张建议卡片，该卡片由triage-heuristics.md中的命名启发式规则目录生成——包括相同可疑文件、步骤前缀重叠、相同控制台错误、相同角色+界面+结果、阶段级联、外观集群、回归标记、相同负责人等。每条建议都会引用启发式规则名称和匹配文本，让用户始终了解标记原因。不使用嵌入、LLM API或自动合并。Agent仅提供建议，最终由用户决策。

这些启发式规则也可在自动测试提交漏洞时选择启用（

triage.runHeuristicsOnFile

，默认

false

），这样测试过程中会询问“提交新漏洞，还是更新BUG-007？”，避免重复提交。

Scaffold folders if missing

若缺少目录则自动生成

If the target repo has no QA folder structure yet, run the bundled scaffolder to create it:

bash

bash <skill>/scripts/scaffold-qa.sh "$REPO_ROOT" PHASE_NUM [SLUG]

It creates (idempotent — won't overwrite existing files):

<repo>/docs/qa/
├── README.md                         # how QA works in this repo
├── qa-config.json                    # stub; discovery rewrites once user confirms
├── phase-NN-<slug>-manual-test-plan.md  # filled-in skeleton (if PHASE_NUM given)
├── report/                           # HTML report destination (agent generates)
├── bug-reports/
│   ├── README.md                     # index + status workflow
│   ├── _template.md                  # bug template
│   └── assets/                       # screenshots (incl. ios/ for iOS QA)
└── runs/                             # per-shard + coordinator merges + BRB minutes

If a different layout already exists in the repo (e.g.

tests/manual/

qa/

, an issue tracker), adopt that layout — do not duplicate it.

如果目标仓库尚无QA目录结构，运行内置的脚手架脚本创建：

bash

bash <skill>/scripts/scaffold-qa.sh "$REPO_ROOT" PHASE_NUM [SLUG]

它会创建（幂等操作——不会覆盖现有文件）：

<repo>/docs/qa/
├── README.md                         # 本仓库的QA测试说明
├── qa-config.json                    # 模板；调研后经用户确认重写
├── phase-NN-<slug>-manual-test-plan.md  # 填充好的骨架（若提供PHASE_NUM）
├── report/                           # HTML报告生成目录（由Agent生成）
├── bug-reports/
│   ├── README.md                     # 索引+状态工作流
│   ├── _template.md                  # 漏洞模板
│   └── assets/                       # 截图（包含iOS QA的ios/目录）
└── runs/                             # 分片报告+协调合并报告+BRB会议纪要

如果仓库已有不同的目录布局（例如

tests/manual/

、

qa/

或问题追踪器），采用现有布局——不要重复创建。

Always

必须遵守的规则

Real user perspective. Drive the app, not the source. Test from URLs and clicks (or simulator taps), not from
```
convex/users.ts
```
or the API layer alone.
Test mobile, tablet, and desktop. Real users arrive on all three, and layout / overflow / tap-target bugs hide at the breakpoint you skip. Cover all three modes for web apps — reference sizes mobile 375 × 812, tablet 768 × 1024, desktop 1280 × 800 (adjust to the spec's breakpoints). Lead with the app's primary target: take it from the product spec; if the spec is unclear, ask the user which mode matters most; if the user isn't available, infer the most likely primary from what you discovered in the repo (responsive CSS / breakpoints, framework defaults, marketing copy) and note the assumption. Record the modes and the chosen primary in
```
qa-config.json#platforms.web
```
so later passes don't re-litigate it. For iOS apps, the device matrix comes from
```
qa-config.json#platforms.ios.devices
```
.
One browser tab per agent. Parallel agents on a shared tab cause auth-provider rate limits and stale sessions.
Capture evidence. Snapshot or screenshot at the moment of failure, console errors verbatim, server data row when relevant.
File bugs immediately on FAIL — see references/bug-filing.md. Do not wait until end of pass.
Use the test account playbook. See references/test-accounts.md. If none documented, ask the user before guessing.
Session hygiene between scenarios. See references/session-hygiene.md. Stale storage / cookies /
```
+test
```
email reuse silently poisons fresh-user flows.
Run the discovery ceremony in issue-trackers.md once per repo before filing bugs.
Regenerate the HTML report at the end of every pass and every BRB session per html-report-style-guide.md.
For iOS app QA, defer the actual simulator driving to a companion skill from ios-simulator-playbook.md; do not reinvent boot / tap / screenshot.

真实用户视角。操作应用，而非查看源代码。通过URL和点击（或模拟器点击）进行测试，而非仅通过
```
convex/users.ts
```
或API层。
测试移动端、平板端和桌面端。真实用户会使用所有设备，布局/溢出/点击目标漏洞会隐藏在你跳过的断点处。网页应用需覆盖三种模式——参考尺寸移动端375×812、平板端768×1024、桌面端1280×800（可根据规格中的断点调整）。优先测试应用的主要目标设备：从产品规格获取；若规格不明确，询问用户哪种模式最重要；若用户不可用，从仓库调研结果（响应式CSS/断点、框架默认值、营销文案）推断最可能的主要设备，并记录假设。将模式和选定的主要设备记录在
```
qa-config.json#platforms.web
```
中，避免后续测试重复确认。iOS应用的设备矩阵来自
```
qa-config.json#platforms.ios.devices
```
。
每个Agent使用一个浏览器标签页。共享标签页的并行Agent会导致认证提供商限流和会话失效。
捕获证据。在失败瞬间拍摄快照或截图，记录完整的控制台错误，必要时记录服务器数据行。
失败后立即提交漏洞——详情请见references/bug-filing.md。不要等到测试结束后再提交。
遵循测试账号指南。详情请见references/test-accounts.md。若无文档记录，询问用户后再操作。
场景间保持会话清洁。详情请见references/session-hygiene.md。过期存储/ cookie/重复使用
```
+test
```
邮箱会悄无声息地破坏新用户流程。
执行问题追踪器调研流程。详情请见issue-trackers.md，提交漏洞前每个仓库只需执行一次。
每次测试和BRB会话结束后重新生成HTML报告，遵循html-report-style-guide.md。
iOS应用QA时，将模拟器驱动操作交给配套技能，详情请见ios-simulator-playbook.md；不要重新实现启动/点击/截图功能。

Never

禁止操作

Mark a scenario PASS from code inspection alone. The user does not experience source — they experience the app.
Mark a phase gate ☑ without evidence (snapshot, server row, console clean).
Fix product code unprompted. Document. File. Hand off.
Skip the Known issues / deferrals section in the phase doc — those drive your scope and prevent false bugs.
Rename phase docs or specs to match buggy behavior. Hides regressions.
Run multiple QA browser sub-agents on one cursor-ide-browser tab.
Reuse a previously-failed test email without changing the run-tag suffix.
Assume an issue tracker without asking the user — even when signals are obvious.
Run Interactive BRB in the same session as an auto QA pass — they are intentionally separate to keep triage bias out of discovery.
Auto-import tracker-only bugs into local markdown without asking the user (default
```
pull.createLocalForUntracked: "ask"
```
).
Auto-merge bugs the heuristics flag as duplicates — every merge / dedup needs user confirmation.
Edit the HTML to change bug state. Edit the markdown; regenerate.
Use the iOS simulator playbook for web-app QA. It's for iOS app projects only. Mobile web QA stays in the browser playbook.

仅通过代码检查标记场景为通过。用户体验的是应用，而非源代码。
无证据（快照、服务器数据行、干净的控制台）就标记阶段检查点为☑。
未经请求修改产品代码。只需记录、提交、移交。
跳过阶段文档中的已知问题/延期处理部分——这些内容决定了测试范围，避免误报漏洞。
修改阶段文档或规格以匹配有问题的行为。这会隐藏回归漏洞。
在同一个cursor-ide-browser标签页运行多个QA浏览器子Agent。
不修改运行标签后缀就重复使用之前失败的测试邮箱。
未询问用户就假设问题追踪器——即使信号明显。
在自动QA测试会话中运行交互式BRB——两者特意分开，避免分类偏见影响漏洞发现。
未填写
qa-config.json
就将漏洞同步至追踪器——会导致重复漏洞和丢失编辑内容。
自动合并启发式规则标记的重复漏洞——每次合并/去重都需要用户确认。
编辑HTML以修改漏洞状态。编辑Markdown后重新生成即可。
使用iOS模拟器指南测试网页应用。该指南仅适用于iOS应用项目。移动端网页QA请使用浏览器指南。

Bug priority (BRB taxonomy)

漏洞优先级（BRB分类体系）

Level	Definition	Action
P0	Blocks core flow; data loss; auth bypass; security	Phase cannot ship; halt QA pass until triaged
P1	Feature broken or wrong; workaround exists	Blocks current phase sign-off
P2	Cosmetic, edge case, accessibility, dev console noise	Defer to polish phase or release hardening

When in doubt between P0 and P1, choose P0 if a user could land in a non-recoverable state or lose data.

级别	定义	操作
P0	阻塞核心流程；数据丢失；认证绕过；安全漏洞	当前阶段无法发布；分类前暂停QA测试
P1	功能损坏或异常；存在替代方案	阻塞当前阶段验收
P2	外观问题、边缘情况、可访问性问题、开发控制台噪音	延期至优化阶段或发布加固环节处理

若无法确定是P0还是P1，若用户可能进入不可恢复状态或丢失数据，则选择P0。

Pass criteria (any phase)

测试通过标准（适用于任何阶段）

All scenarios in the phase manual test plan PASS (or are explicitly deferred with reason in the phase doc).
Phase gate / checklist all green.
No open P0 or P1 bugs against this phase.
For phases that touch auth / invites / notifications: the regression matrix is green.

阶段手动测试计划中的所有场景通过（或在阶段文档中明确延期并说明原因）。
阶段检查点/清单全部通过。
针对当前阶段无未处理的P0或P1漏洞。
若阶段涉及认证/邀请/通知：回归测试矩阵全部通过。

Definition of done

完成定义

Every pass ends with a coordinator merge doc whose top line reads:

Phase N ready? YES — all gates ☑, no open P0/P1. Phase N ready? NO — list open P0/P1 + remaining unrun scenarios

a one-paragraph handoff prompt for the next QA agent.

If NO, the merge doc must be paste-ready into a new conversation. The next agent should not need to rediscover state. See references/gate-merge.md.

The HTML report (

docs/qa/report/index.html

) is also regenerated and committed.

每次测试结束后，协调合并文档的第一行需包含：

阶段N是否可发布？YES——所有检查点☑，无未处理的P0/P1漏洞。 阶段N是否可发布？NO——列出未处理的P0/P1漏洞+剩余未运行的场景

给下一位QA Agent的一段移交提示。

若结论为NO，合并文档需可直接粘贴到新会话中。下一位Agent无需重新调研状态。详情请见references/gate-merge.md。

同时需重新生成并提交HTML报告（

docs/qa/report/index.html

）。

Browser tools (cursor-first, fallback ladder)

浏览器工具（优先使用Cursor，按阶梯降级）

Default to cursor-ide-browser MCP when running inside Cursor. If the session is in another tool or browser MCP is missing, fall back per the ladder in references/browser-playbook.md:

cursor-ide-browser MCP (Cursor / Claude Code)
Chrome DevTools for agents (
```
chrome-devtools-mcp
```
) — auto-waits for results and adds DevTools-grade network / console / Lighthouse / a11y inspection; can attach to your real signed-in Chrome so auth flows don't get bot-flagged
browser-use MCP (provider-agnostic)
Playwright (CLI or MCP)
Codex Computer Use (macOS) — human-fidelity pass on the real signed-in app; see computer-use-playbook.md
Driving manually + asking user to paste console errors / screenshots

Whatever tool, the playbook is the same: navigate → snapshot → act on fresh refs → capture evidence → unlock when done. The reference covers each tool's specifics, including how to drive like a human so the app doesn't trip on bot detection or timing races. The pass must succeed with whatever the environment has — don't depend on Computer Use, which most VMs lack.

在Cursor中运行时，默认使用cursor-ide-browser MCP。若会话在其他工具中或缺少浏览器MCP，按browser-playbook.md中的阶梯降级：

cursor-ide-browser MCP（Cursor / Claude Code）
Chrome DevTools for agents（
```
chrome-devtools-mcp
```
）——自动等待结果，添加DevTools级别的网络/控制台/Lighthouse/可访问性检查；可连接到你已登录的真实Chrome浏览器，避免认证流程被标记为机器人
browser-use MCP（跨提供商）
Playwright（CLI或MCP）
Codex Computer Use（macOS）——对已登录的真实应用进行高保真测试；详情请见computer-use-playbook.md
手动操作+请求用户粘贴控制台错误/截图

无论使用哪种工具，测试指南都是相同的：导航→快照→基于新引用操作→捕获证据→完成后解锁。参考文档涵盖了每种工具的细节，包括如何模拟人类操作，避免应用触发机器人检测或时序竞态。测试必须在当前环境可用的工具下完成——不要依赖大多数虚拟机都不支持的Computer Use。

Deliverables per pass

每次测试的交付物

Path	What
`docs/qa/qa-config.json`	Tracker + triage + report + platforms config (discovery rewrites the stub)
`docs/qa/phase-NN-<slug>-manual-test-plan.md`	(if newly generated)
`docs/qa/runs/QA-<shard>-run-YYYY-MM-DD.md`	Per-shard results
`docs/qa/runs/COORDINATOR-MERGE-YYYY-MM-DD.md`	Merge + verdict
`docs/qa/runs/BRB-YYYY-MM-DD.md`	(Interactive BRB only) session minutes
`docs/qa/bug-reports/BUG-NNN-*.md` + `assets/BUG-NNN/`	Each defect
`docs/qa/report/index.html` + `bugs/` + `runs/` + `assets.css`	Apple-language HTML dashboard
`docs/QA_GATES.md` (or your repo's equivalent)	Gate boxes updated
Phase doc § QA status	Sign-off note + link to merge
Tracker issues (Linear / GitHub / …)	If `syncOnFile` or after BRB

Adapt paths to whatever the target repo already uses.

路径	内容
`docs/qa/qa-config.json`	追踪器+分类+报告+平台配置（调研后重写模板）
`docs/qa/phase-NN-<slug>-manual-test-plan.md`	（若为新生成）
`docs/qa/runs/QA-<shard>-run-YYYY-MM-DD.md`	分片测试结果
`docs/qa/runs/COORDINATOR-MERGE-YYYY-MM-DD.md`	合并结果+结论
`docs/qa/runs/BRB-YYYY-MM-DD.md`	（仅交互式BRB）会话纪要
`docs/qa/bug-reports/BUG-NNN-*.md` + `assets/BUG-NNN/`	每个漏洞的详情
`docs/qa/report/index.html` + `bugs/` + `runs/` + `assets.css`	类Apple风格的HTML仪表盘
`docs/QA_GATES.md` （或仓库中的等效文件）	更新检查点状态
阶段文档§ QA状态	验收说明+合并文档链接
追踪器问题（Linear / GitHub / …）	若启用 `syncOnFile` 或BRB会话后同步

可根据目标仓库的现有路径调整。

References (load on demand)

参考文档（按需加载）

references/workflow.md — full PM/QA/Eng decision tree
references/discovering-the-app.md — investigate intent + ask user when docs missing
references/test-plan.md — derive a phase manual test plan from spec + phase doc + gate
references/test-accounts.md — Clerk / Auth0 / Supabase / custom — and the "ask the user" pattern
references/session-hygiene.md — stale storage, rate limits, persona suffixing
references/browser-playbook.md — cursor-ide-browser, Chrome DevTools MCP, browser-use, Playwright recipes + how to drive like a human (web apps)
references/computer-use-playbook.md — Codex Computer Use for web and native macOS apps (macOS; graceful fallback to a browser driver elsewhere)
references/ios-simulator-playbook.md — iOS / iPadOS app QA, curated companion-skill ladder (AXe, baguette, XcodeBuildMCP, ios-simulator-skill, ios-build-verify, …)
references/parallel-coordinator.md — shard map, write-path-first rule, copy-paste shard prompts, and running the pass as a bounded wave when
```
waves
```
/
```
waves-codex
```
is installed
references/sequential-wrapup.md — single-agent finish; copy-paste prompt
references/bug-filing.md — bug template, severity, evidence rules, status transitions
references/gate-merge.md — merge shard reports → gates + verdict
references/issue-trackers.md — discover-and-confirm ceremony, Linear / GitHub / Jira / Notion adapters, bi-directional sync
references/brb-interactive.md — Interactive Bug Review Board workflow (separate session)
references/triage-heuristics.md — named heuristics catalog for duplicate / cluster detection
references/html-report-style-guide.md — Apple-language tokens, components, rendering rules
references/extending-the-skill.md — add a tracker, heuristic, surface, or mode without rewriting
references/templates/ — bug-report, test-plan, run-report, coordinator-merge, brb-interactive-prompt, brb-minutes, qa-config.example.json, html-report/ skeletons

references/workflow.md — 完整的PM/QA/Eng决策树
references/discovering-the-app.md — 调研应用意图+文档缺失时询问用户的方法
references/test-plan.md — 根据规格+阶段文档+检查点生成阶段手动测试计划
references/test-accounts.md — Clerk/Auth0/Supabase/自定义测试账号——以及“询问用户”的模式
references/session-hygiene.md — 过期存储、限流、角色后缀规则
references/browser-playbook.md — cursor-ide-browser、Chrome DevTools MCP、browser-use、Playwright示例+如何模拟人类操作（网页应用）
references/computer-use-playbook.md — Codex Computer Use用于网页和原生macOS应用（macOS；其他环境优雅降级为浏览器驱动）
references/ios-simulator-playbook.md — iOS/iPadOS应用QA，精选配套技能阶梯（AXe、baguette、XcodeBuildMCP、ios-simulator-skill、ios-build-verify等）
references/parallel-coordinator.md — 分片映射、优先写入路径规则、可复制粘贴的分片提示、安装
```
waves
```
/
```
waves-codex
```
时作为有限wave运行测试
references/sequential-wrapup.md — 单Agent收尾；可复制粘贴的提示
references/bug-filing.md — 漏洞模板、严重级别、证据规则、状态转换
references/gate-merge.md — 合并分片报告→检查点+结论
references/issue-trackers.md — 调研并确认流程、Linear/GitHub/Jira/Notion适配器、双向同步
references/brb-interactive.md — 交互式Bug Review Board工作流（单独会话）
references/triage-heuristics.md — 用于重复/集群检测的命名启发式规则目录
references/html-report-style-guide.md — 类Apple风格的标记、组件、渲染规则
references/extending-the-skill.md — 添加追踪器、启发式规则、界面、模式无需重写技能
references/templates/ — 漏洞报告、测试计划、运行报告、协调合并、交互式BRB提示、BRB纪要、qa-config.example.json、HTML报告骨架

Scripts

脚本

```
scripts/scaffold-qa.sh REPO_ROOT PHASE_NUM [SLUG]
```
— creates the QA folder layout, qa-config stub, and report folder in any repo.
```
scripts/bugs-needing-sync.sh REPO_ROOT [--tracker …]
```
— lists bugs missing a tracker ID; the agent reads the list and pushes per
```
issue-trackers.md
```
.

scripts/bugs-needing-pull.sh REPO_ROOT [--threshold 24h] [--tracker …]

— lists bugs whose

Tracker / lastSyncedAt

is stale; the agent reads the list and pulls per

issue-trackers.md

```
scripts/scaffold-qa.sh REPO_ROOT PHASE_NUM [SLUG]
```
— 在任何仓库中创建QA目录布局、qa-config模板和报告目录。
```
scripts/bugs-needing-sync.sh REPO_ROOT [--tracker …]
```
— 列出缺少追踪器ID的漏洞；Agent会根据
```
issue-trackers.md
```
推送这些漏洞。

scripts/bugs-needing-pull.sh REPO_ROOT [--threshold 24h] [--tracker …]

— 列出

Tracker / lastSyncedAt

已过期的漏洞；Agent会根据

issue-trackers.md

拉取这些漏洞的状态。

Extending this skill

扩展本技能

Adding a new issue tracker, triage heuristic, surface playbook, or mode is additive — copy a section, fill it in, the agent picks it up on the next session. Forward-compatible

qa-config.json

schema (

version: 1

, unknown fields ignored), additive bug front-matter, versioned HTML report marker. See references/extending-the-skill.md.

添加新的问题追踪器、分类启发式规则、界面测试指南或模式都是增量式的——复制一个部分，填充内容，Agent会在下一次会话中自动识别。

qa-config.json

schema向前兼容（

version: 1

，忽略未知字段），漏洞前置信息增量扩展，HTML报告带有版本标记。详情请见references/extending-the-skill.md。

Anti-patterns to avoid

需避免的反模式

Don't	Why
Mark scenarios PASS from code inspection	Users don't experience source
Defer P0 bugs to "next phase"	Foundation bugs cascade everywhere
Trust prior PASS marks without re-running on a fresh build	Regressions appear from unrelated work
Run multiple QA agents on one browser tab	Auth providers throttle; sessions bleed
Edit the phase doc to match buggy behavior	Hides the regression — file a bug instead
File a bug without Steps to reproduce	Engineering can't act on it
Test only the happy path	The happy path is what engineers tested already
Run BRB and an auto pass in the same session	Triage bias contaminates discovery
Sync bugs to a tracker without filling `qa-config.json`	Duplicates and lost edits
Use the iOS playbook to test a web app on Mobile Safari	Out of scope; the iOS playbook is for iOS app projects only
Auto-merge heuristic suggestions	Every dedup needs user confirm
Auto-import tracker-only bugs as local markdown	Engineering may have filed them in a context QA shouldn't claim
Edit the HTML to change bug state	Markdown is the source of truth; regenerate the HTML

禁止操作	原因
通过代码检查标记场景为通过	用户体验的是应用，而非源代码
将P0漏洞延期至“下一阶段”	基础漏洞会引发连锁问题
不重新测试就信任之前的通过标记	无关工作可能导致回归漏洞
在一个浏览器标签页运行多个QA Agent	认证提供商会限流；会话会互相干扰
修改阶段文档以匹配有问题的行为	会隐藏回归漏洞——应提交漏洞
提交无复现步骤的漏洞	工程团队无法处理
仅测试正常流程	正常流程是工程师已经测试过的内容
在同一会话中运行BRB和自动测试	分类偏见会影响漏洞发现
未填写 `qa-config.json` 就将漏洞同步至追踪器	会导致重复漏洞和丢失编辑内容
使用iOS指南测试Mobile Safari上的网页应用	超出范围；iOS指南仅适用于iOS应用项目
自动合并启发式规则建议	每次去重都需要用户确认
自动导入仅存在于追踪器的漏洞作为本地Markdown	工程团队可能是在QA不应介入的上下文提交的这些漏洞
编辑HTML以修改漏洞状态	Markdown是事实来源；重新生成HTML即可

When a QA pass reveals work bigger than QA

当QA测试发现超出QA范围的工作

If during the pass you find:

A missing feature the phase claims exists (no code path at all)
A schema diverging from the spec across multiple scenarios
A P0 blocking every remaining scenario

Stop testing. Surface the finding. The user decides whether to escalate to engineering or carve a smaller phase. Continuing wastes time on a foundation that needs replacing.

如果测试过程中发现：

阶段声称已实现的功能缺失（完全没有代码路径）
多个场景中存在与规格不符的架构问题
P0漏洞阻塞所有剩余场景

停止测试。告知用户该发现。用户会决定是否升级至工程团队或缩小阶段范围。继续测试会在需要重构的基础上浪费时间。