/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" 已由下文「完成