| name | agf-writing-qa-report |
| description | Use when qa-engineer (or miniapp-qa-engineer) is about to publish an E2E or UAT report. Provides the report skeleton, evidence-quality bar, verdict criteria, and hand-off rules. SIT is now dev-owned and lives in progress/<role>.md (see agf-running-sit-tests skill) — this skill does NOT cover SIT reports. |
Writing a QA Report (E2E / UAT)
Use this skill when:
- E2E execution is complete and a report needs publishing
- UAT business sign-off needs to be captured
- A bug-fix E2E re-verification needs recording (always appended as
## Re-run [N] — [date] to the existing [feature]-e2e-[YYYY-MM-DD].md; never a new file — see "File path & naming" below)
Pair with:
agf-running-sit-tests skill — SIT 由 dev 自跑，本 skill 不覆盖 SIT 报告（SIT 证据已在 progress/<role>.md 的 **SIT 证据** 段，归档随 docs/qa/<feature>-process-log.md 走）- UAT 用例文档
docs/qa/[feature]-uat-cases-[date].md（模板 docs/qa/uat-cases-_TEMPLATE.md，gate SSOT 见 testing.md「UAT 用例文档」节）— UAT 执行前生成 + 用户审核 status: Approved；执行证据回填用例文档（证据 SSOT），UAT 报告引用用例 ID，不重复粘贴证据
- This skill — covers the E2E / UAT artifact (report file) format
File path & naming
docs/qa/[feature-kebab-case]-[stage]-[YYYY-MM-DD].md — Stage ∈ {e2e, uat}. Examples:
docs/qa/oauth-login-e2e-2026-05-13.mddocs/qa/oauth-login-uat-2026-05-15.md
One report per stage per feature. Re-runs after defect fix → append a new ## Re-run [N] — [date] section to the same file, do not create a new file.
Required sections (in order)
---
# frontmatter 是 verdict 数据的唯一 SSOT（agf-verdict.py 解析；validate-verdict hook 校客观底线、agf-matrix.sh fan-in 都读这里）
feature: [feature-slug]
date: YYYY-MM-DD
tester: qa-engineer
stage: E2E # E2E | UAT
report_verdict: Promote # Promote | Conditional promote | Block
critical_defect_count: 0 # 客观底线事实（>0 时 report_verdict 必须为 Block）
p0_pass2_total: 0 # P0 用例数（需 pass²）
p0_pass2_ok: 0 # 连续 2 次都过的 P0 数
uat_signoff_verdict: N/A # approve | request changes | N/A（仅 UAT 阶段有值；不推导）
---
# QA Report — [Feature] — [E2E|UAT]
- **Date**: YYYY-MM-DD
- **Stage**: E2E / UAT
- **Tester**: qa-engineer ([model name]) / 业务方姓名（UAT）
- **Branch**: [branch + commit hash]
- **Environment**: local docker-compose / staging / pre-prod
- **需求入口**: docs/changes/[change]/tasks.md（AC↔scenario 映射，ADR-012；旧 feature fallback docs/prd/[feature]-[date].md）
- **Code review (含 SIT Audit)**: docs/reviews/[feature]-[date].md
## Summary
- Total AC: N
- Passed: M
- Failed: K
- Blocked: J
- 界面渲染核查（仅 UAT 且含界面 feature）: N/N 界面真渲染 + 截图 + 读图四查通过（矩阵 SSOT 在用例文档）
- **Verdict**: ✅ Promote to next stage / ❌ Block / ⚠️ Conditional promote
## Pre-conditions Checked
- [ ] 单元测试 + lint + typecheck 全绿
- [ ] code-reviewer 报告已存在且 verdict ≠ Block（含 SIT Audit = ✅ / ⚠️）
- [ ] AC 来源可访问（`docs/changes/<change>/tasks.md`；旧 feature fallback PRD）
- [ ] 环境就绪（DB 起来 / 迁移已 apply / 服务已启动）
- [ ] **（仅 UAT）用例文档已审核**：`docs/qa/[feature]-uat-cases-[date].md` 存在且 frontmatter `status: Approved`（MAJOR / MINOR 强制；PATCH 级 hotfix 由 PL 豁免时在报告注明理由）
任何一条没勾 → 不该开始测；先 SendMessage product-lead 解决先决条件。
## AC Results
### AC-1 (P0): [verbatim AC text from tasks.md（fallback PRD）]
- **Priority**: P0 / P1 / P2（来自 `docs/changes/<change>/tasks.md` 的 AC 优先级标注；旧 feature 来自 PRD §4 Priority；P0 必须跑 2 次，P1/P2 跑 1 次即可）
- **Setup**: [起始状态]
- **Action**: [触发步骤]
- **Expected**: [复制 AC 原文]
- **Actual (run 1)**:
HTTP/1.1 200 OK
Content-Type: application/json
{"id": 42, "status": "created"}
- **Actual (run 2)** [P0 必填；P1/P2 可空]:
HTTP/1.1 200 OK
...
- **Reliability**: `pass^1 = 1/1` 或 `pass^2 = 2/2`（P0）— 两次不一致 = `⚠️ Flaky`，按 fail 处理
- **Verdict**: ✅ Pass / ❌ Fail / ⚠️ Blocked / ⚠️ Flaky
(每个 AC 都要单独一节，**禁止合并写 'all passed'**。**为什么 P0 要跑 2 次**：业界实证（τ-bench）pass@1 高 ≠ pass^k 高，单次过的 P0 case 偶发问题会逃逸到生产。)
## Defects Found
| ID | Severity | Title | Repro steps | Suspected file |
|---|---|---|---|---|
| DEF-1 | High | ... | 1. ... 2. ... | backend/app/foo |
Severity 标准:
- **Critical**: 阻断核心流程，无 workaround
- **High**: 阻断核心流程但有 workaround；或非核心流程的数据/安全问题
- **Medium**: 边缘场景失败，不阻断核心流程
- **Low**: 体验/文案/兼容性
## Cross-stage Notes
- E2E → UAT: 给业务方的操作手册 / 数据准备说明 / 已知 P2 defect 列表
## Cost (this QA session)
- Tokens consumed: [from `/usage`]
- Estimated cost: [CNY]
- 同 feature 累计（E2E + UAT 总和）：[CNY]
## Hand-off
✅ Promote → SendMessage product-lead 进下一阶段
❌ Block → SendMessage product-lead 列 critical defect，重新派回 dev
⚠️ Conditional → 列 P2 defect 单独建 issue，allow 进下一阶段
Verdict 决策树（不能凭感觉）
任一 P0 AC = Fail → ❌ Block
所有 P0 + P1 AC = Pass → ✅ Promote
P0 全 Pass，P1 部分 Fail → ⚠️ Conditional（P1 失败必须建跟踪 issue）
有 P0 = Blocked（环境问题） → ⚠️ Block + 升级 product-lead
客观底线硬校验（frontmatter，退出时 hook 拦）
report_verdict 的定性选择（Promote vs Conditional）不套公式，但两条客观底线由 validate-verdict.sh（委托 agf-verdict.py，ADR-010）退出时重算、违反即 exit 2 打回——填 frontmatter 前自查：
critical_defect_count > 0 → report_verdict 必须为 Block（有 critical defect 却 Promote/Conditional = 不可能组合）。p0_pass2_ok < p0_pass2_total（P0 未全部 pass²）→ report_verdict 不得为 Promote（P0 没连过 2 次不准晋级）。
这两条只拦"客观不可能组合"，不强定 Promote/Conditional 档；极保守 fail-open（缺字段 / 坏 yaml 一律放行 + WARN）。uat_signoff_verdict 仅结构化记录、不推导。
Evidence 质量条
每条 Pass 的 Actual 段必须有可验证产物之一：
- HTTP 调用：
curl -i 完整响应头 + body（敏感字段可遮）
- DB 状态：
SELECT 前后对比
- UI：截图（命名规则：
evidence/AC-N-[step].png）
- 日志：相关行（带时间戳）
- 文件落盘：
ls -la + 内容 head
禁止只写"Passed, looks correct"——这种 Pass 不可信，等同没测。
UAT 含用户可见界面的用例额外强制（SSOT：testing.md「UAT 界面渲染核查」节）：
- 截图必选且必须来自 chrome-devtools 真渲染（小程序 / Apple 轨用对应模拟器；命名
evidence/UAT-[case]-[界面slug].png），落盘后必须用 Read 读回做视觉分析（对照 design spec + index.html 原型），在用例文档「界面渲染核查矩阵」回填四查结论（导航 / 裁切 / 控件可点 / 视觉达标）
- curl /
SELECT 输出只能作补充——纯 API / DB 断言不构成 Pass；矩阵任一行缺截图或缺读图结论（"已截图" ≠ "已核查"）= 该界面未测，本报告不得发布
反模式
（"合并写 all passed" / "无 evidence 的 Pass" / "Defect 不写 Repro" 已由下文「完成前的验证」checklist 反向守门，此处不重列。）
- ❌ 跑 E2E 时同时改代码（移动靶）— 必须 freeze 分支再跑
- ❌ 用生产 API key 跑 E2E — 必须用专用测试 key + 每日花费上限
- ❌ 用本 skill 写 SIT 报告 — SIT 已 dev 自跑，证据落
progress/<role>.md，不再有独立 SIT 报告
- ❌ UAT 用 API 断言代替界面渲染 — 接口 200 ≠ 界面可用（导航缺失 / 裁切 / 控件点不动全漏检）；含界面用例必须真渲染 + 截图 + 读图四查，"时间紧 / E2E 已截过图 / 后端数据对了"都不是豁免理由
- ❌ 截图存档但不读图 — 截图必须用 Read 读回、以视觉能力对照 design spec 给"视觉达标"结论；UIUX 是用户对产品最直接的感受，"功能对了但界面糙"不是可交付状态，"已截图"不等于"已核查"
完成前的验证
任一不行 → 不要 publish，回去补。
Hand-off 触发
报告落盘后立即（不等用户问）：
- SendMessage product-lead，附 verdict + report path + 1 句话总结
- 如 verdict = Block：列 top-3 critical defect 在消息正文
- 如 verdict = ⚠️ Conditional：把 P2 defect 通过
TaskCreate 单独开 follow-up task（由 product-lead 派发）
