qa

name	qa
description	运行交互式 QA session：用户通过对话报告 bugs 或 issues，agent 随后创建 GitHub issues；同时在后台探索 codebase，获取上下文和 domain language。适用于用户希望报告 bugs、开展 QA、通过对话创建 issues，或提到“QA session”的场景。

QA Session

运行一场交互式 QA session。用户描述遇到的问题；你负责澄清、探索 codebase 以获取上下文，并创建经得住时间和重构、以用户为中心、使用项目 domain language 的 GitHub issues。

对用户提出的每个 issue

1. 倾听并进行少量澄清

让用户用自己的话描述问题。最多提出 2–3 个简短澄清问题，重点关注：

• 预期结果与实际结果
• 复现步骤（尚不清楚时）
• 问题稳定发生还是偶尔发生

不要过度访谈。现有描述已经足以创建 issue 时，直接继续。

2. 在后台探索 codebase

与用户对话的同时，在后台启动一个 Agent（subagent_type=Explore），理解相关区域。探索的目标是补足以下上下文：

• 学习该区域使用的 domain language（检查 UBIQUITOUS_LANGUAGE.md）
• 理解该功能原本应有的行为
• 找出用户可观察的 behavior boundary

这些上下文有助于写出更好的 issue；issue 正文中不得引用具体文件、行号或内部实现细节。

3. 评估范围：单个 issue 还是需要拆分？

创建前，判断当前问题应作为单个 issue，还是拆成多个 issues。

出现以下情况时拆分：

• 修复跨越多个互相独立的区域（例如“form validation 错误、success message 缺失、redirect 失效”）
• 存在可以由不同人员并行处理的独立关注点
• 用户描述了多种彼此独立的 failure modes 或 symptoms

出现以下情况时保留为单个 issue：

• 某处只有一个 behavior 出错
• 全部 symptoms 来自同一个根本 behavior

4. 创建 GitHub issue(s)

使用 gh issue create 创建 issues。无需先请用户审阅；直接创建并分享 URLs。

Issues 必须具有持久性，即使 codebase 经历大规模重构，内容仍然成立。使用用户视角进行描述。

单个 issue

使用以下模板：

## 发生了什么

[用直白语言描述用户实际遇到的行为]

## 预期行为

[描述期望发生的行为]

## 复现步骤

1. [开发者可以照着执行的具体编号步骤]
2. [使用 codebase 中的 domain terms，不要使用内部 module names]
3. [包含相关 inputs、flags 或 configuration]

## 补充上下文

[来自用户或 codebase 探索的额外观察，用于帮助界定问题。例如：“仅使用 Docker layer 时发生，filesystem layer 不会发生。”使用 domain language，不要引用文件]

拆分为多个 issues

按依赖顺序创建 issues（blockers 优先），以便引用真实 issue numbers。

每个 sub-issue 使用以下模板：

## Parent issue

#<parent-issue-number>（创建了 tracking issue 时）或“Reported during QA session”

## 问题

[描述这一项具体 behavior 问题，只写当前 slice，不要重述完整报告]

## 预期行为

[当前 slice 的期望行为]

## 复现步骤

1. [只与当前 issue 相关的步骤]

## Blocked by

- #<issue-number>（当前 issue 必须等待另一项解决时）

没有 blockers 时填写“None — can start immediately”。

## 补充上下文

[只与当前 slice 相关的额外观察]

拆分时：

• 优先创建多个薄 issue，少建厚 issue——每一项都应能够独立修复和验证
• 如实标记 blocking relationships——issue B 确实必须等到 issue A 修复后才能测试时，明确写出；相互独立时，两项都标记为 “None — can start immediately”
• 按依赖顺序创建 issues，确保 “Blocked by” 能够引用真实 issue numbers
• 尽量提高并行度——让多个人或 agents 可以同时领取不同 issues

所有 issue 正文都必须遵守的规则

• 不写文件路径和行号——它们会过时
• 使用项目的 domain language（存在 UBIQUITOUS_LANGUAGE.md 时先检查）
• 描述 behaviors，不描述 code——写“sync service 无法应用 patch”，不要写“applyPatch() 在第 42 行抛错”
• 复现步骤不可缺少——无法确定时向用户询问
• 保持简洁——开发者应能在 30 秒内读完

创建后，输出所有 issue URLs，概述 blocking relationships，并询问：“下一个 issue，还是已经完成？”

5. 继续 session

持续进行，直到用户表示结束。每个 issue 独立处理，不要批量积压后再统一创建。