qa-report

真实用户 QA 规划器

像真实用户经历旅程那样规划 QA，而不是不断累积测试用例。本技能负责项目的持续更新的 QA 文档——一个已提交的目录树（<qa-docs-path>，默认为 docs/qa/），每轮都会向其中追加内容——并规划由 qa-execution 执行的、由用户画像驱动的测试环节。

以下两条规则是所有工作的核心：

1. 持续更新文档，而非每轮的产物。 所有持久的 QA 知识都存放在同一个已提交的目录树中；每轮都向其中追加内容（结构、持久性和反模式：references/qa-docs-layout.md）。
2. 测试环节，而非用例。 最小规划单元是测试环节章程（用户画像 + 旅程 + 测试路线 + 时间限制），由旅程流程图推导而来。覆盖率意味着“本周期内，每条规划旅程都由某个用户画像实际走过”——记录在测试环节台账中，绝不按单个用例计数。

根据请求的变更选择冒烟测试、针对性测试或完整测试范围，再执行相关步骤。复用现有用户画像、旅程、章程和证据；仅阅读所需模式或流程对应的参考章节。针对性更新不会重新初始化或审查整个 QA 目录树。

必需输入

• qa-docs-path（可选）：持续更新目录树的根目录；默认为仓库根目录下的 docs/qa——必须是持久且已提交的位置，绝不能是临时目录。遵循明确提供的路径；默认使用仓库管理的持久目录树。仅在预期输出位置尚未确定时才询问。

流程

步骤 1 — 确定目录树位置或初始化目录树。 阅读 references/qa-docs-layout.md（规范目录树、gitignore 区块、初始化流程，以及采用分散的旧版产物的流程）。确定 <qa-docs-path>。如果目录树已存在，先阅读其中的 README.md，并搜索受影响的 scenarios/ 和相关未解决的 bugs/；以下所有决策都以此为依据。如果当前分支刚合并了并行 QA 工作，应在规划前进行协调：描述同一行为或同一症状的两个文件应合并到较早的 ID 中（根据 last_report 的时效合并 verdict 字段、更新引用、删除重复文件，并在本周期的报告中记录合并情况）。如果目录树不存在，则按照布局参考初始化——创建目录树、填充 templates/，并添加 gitignore 区块。仅当迁移属于本次工作范围时，才采用旧版 QA 产物；普通的针对性更新应保留历史证据。

步骤 2 — 确定项目用户画像。 阅读 references/personas.md（种子目录 + 推导规则）。用户画像是 <qa-docs-path>/personas.md 中持久的实例数据：仅在产品受众发生变化时更新；如果文件不存在，则定义当前范围内旅程所需的用户画像；如果受众覆盖需要，则扩充目录。

步骤 3 — 将旅程映射为流程（先于任何场景）。 阅读 references/journeys-and-flows.md（旅程构成、Mermaid 映射、先流程后矩阵）。确定映射范围：分支/PR 周期覆盖差异中所有用户可见的变更；发布周期覆盖产品中具有高价值的旅程。对于每条旅程，编写或更新 <qa-docs-path>/journeys/J-<slug>.md——其中包含 YAML 旅程映射，以及从入口 → 操作 → 分支点 → 副作用 → 真实终态的 Mermaid 流程图，并至少包含一条放弃路径。先映射流程；场景由流程推导而来。

步骤 4 — 将场景推导至跟踪器。 阅读 references/state-schema.md（字段、枚举、ID 生成——必须严格遵循）和 references/taxonomy.md（五个覆盖维度）。遍历每张流程图并推导场景：每个场景一个 scenarios/<AREA>-<slug>.md 文件，使用内容寻址 ID，在原处更新，并在 overlaps 字段中记录重叠。使用与变更旅程相关的分类维度；完整的发布计划可覆盖全部五个维度。场景文件是规划产物——在 qa-execution 执行之前，qa_status 保持为 untested。 步骤 5 — 规划会话章程。 阅读 references/session-charters.md（章程结构、频率层级、覆盖反转）。选择频率层级（冒烟 / 定向 / 全面 / 健全性检查）；层级决定要走查的用户旅程。根据 <qa-docs-path>/templates/charter.md（种子文件：assets/charter-template.md），为每个会话在 <qa-docs-path>/charters/CH-<slug>.md 中编写一份章程，并保留模板中的标题——任务、角色、用户旅程、恰好一项游览、时间限制、必试指导——按风险排序：影响最大的用户旅程 × 影响范围最大的游览排在最前。若现有章程的任务仍然适用，优先复用，不要另写一份相近的章程。

步骤 6 — 登记 Bug。 阅读 references/bug-registry.md（ID 生成、去重、五级用户影响标准——两项技能共用的规范严重性模型）。提交前先去重：在 <qa-docs-path>/bugs/ 中搜索相关症状，并更新已有文件，而不是重复登记——再次发现的 Bug 值得保留在同一个 ID 下，作为历史记录。只有真正的新症状才生成新的内容寻址 ID BUG-<YYYYMMDD>-<slug>；根据 <qa-docs-path>/templates/bug.md（种子文件：assets/bug-template.md）创建文件，保留模板中的标题，并将该 ID 链接到受影响场景文件的 bug_ids 中。

步骤 7 — 验证周期完整性。 对于新周期或全面周期，核实以下规划约定。定向周期复用未变更的地图 / 章程，只检查受影响的条目；如实记录缺口，不要为了凑数而填充内容：

• 每个范围内的用户旅程都有流程图，其中包含真实的终止状态和至少 1 条放弃路径；
• 每个范围内的用户旅程至少有 1 份指定了角色的章程；
• 每个范围内的场景文件都有内容寻址 ID、关联的用户旅程，以及如实反映现状的 qa_status；
• 每个未解决的 Bug 都有登记文件，并出现在至少 1 个场景的 bug_ids 中；
• 已逐个用户旅程考虑五个分类维度；跳过的维度必须附上原因。

完整性标准是“每个用户旅程都由一个角色实际走查”，也就是会话台账——绝不是用测试用例数量衡量。不断累积测试用例正是这项技能旨在避免的失误模式。

当某个用户旅程足够稳定或容易出现回归，值得编写自动化端到端测试规范时，请阅读 references/automation-backlog.md 中适用的部分，然后在 <qa-docs-path>/automation-backlog/ 中记录自动化意图，每个意图单独一个文件——只维护一份待办列表，绝不在单个场景或章程上添加自动化字段。

配套技能

• qa-execution — 执行本技能规划的会话，并将结果写回同一目录树（状态、Bug、报告）。这棵持续更新的目录树是两项技能之间的约定。
• agent-output-audit — 负责 CI 验证门禁、AI 测试卫生扫描和任务状态核对。将技术集成 / 安全 / 性能 / 负载测试套件交由该技能或专用工具处理；记录分派决定，不要将这些工作纳入本技能。

错误处理

• 场景文件的 frontmatter 无法解析（缺少分隔符、字段未知、值嵌套）：先修复，并在执行任何后续步骤前报告修复内容——每个步骤都依赖可加载的跟踪文件。
• 两个文件用不同的 slug 描述同一个行为或症状（合并并行 QA 分支后常见）：在任何后续步骤基于重复文件进行规划前，先执行步骤 1 的合并。
• 分支周期的差异中没有用户可见的改动： 明确说明并停止；没有内容可供实际体验测试。不要为了填满周期而编造场景。
• 无法创建 <qa-docs-path>（权限不足、检出为只读）：指出错误并停止——绝不要改用临时目录。