agf-writing-qa-report

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.md
• docs/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 是用户对产品最直接的感受，"功能对了但界面糙"不是可交付状态，"已截图"不等于"已核查"

完成前的验证

• 每条 AC 都有 Setup / Action / Expected / Actual / Verdict 五段？
• 每个 Pass 都有可验证 evidence？
• Defects 表每行都有 Repro steps + Suspected file？
• Cost 一节填了实际数字（不是 TBD）？
• Verdict 由决策树推出（不是凭感觉）？
• 交互控件全覆盖（含前端的 feature）：页面每个可交互控件都点击/输入过 + 断言了可观测后果（DOM/网络/路由/状态），非"截图看着有按钮"（见 testing.md 前后端对接强制覆盖项 ③）？
• （仅 UAT）界面渲染核查矩阵：每个用户可见界面已真渲染 + 截图 + 读图四查（导航 / 裁切 / 控件可点 / 视觉达标），每张截图都被 Read 读回分析过，无"待执行"残留、无以纯 API 断言代替（见 testing.md「UAT 界面渲染核查」节）？
• Hand-off SendMessage 已发出？

任一不行 → 不要 publish，回去补。

Hand-off 触发

报告落盘后立即（不等用户问）：

1. SendMessage product-lead，附 verdict + report path + 1 句话总结
2. 如 verdict = Block：列 top-3 critical defect 在消息正文
3. 如 verdict = ⚠️ Conditional：把 P2 defect 通过 TaskCreate 单独开 follow-up task（由 product-lead 派发）