QA Session

运行交互式 QA session。用户描述遇到的问题。你负责澄清、探索 codebase 获取 context，并创建 durable、user-focused 且使用项目 domain language 的 GitHub issues。

For each issue the user raises

1. Listen and lightly clarify

让用户用自己的话描述问题。最多问 2-3 个简短 clarifying questions，聚焦：

• 他们期望什么，实际发生了什么
• Steps to reproduce（如果不明显）
• 是否稳定复现，还是 intermittent

不要过度访谈。如果描述足够清楚，可以直接 file。

2. Explore the codebase in the background

与用户对话时，在后台启动 Agent（subagent_type=Explore）理解相关区域。目标不是找 fix，而是：

• 学习该区域使用的 domain language（检查 UBIQUITOUS_LANGUAGE.md）
• 理解 feature 本应做什么
• 识别 user-facing behavior boundary

这些 context 帮助你写出更好的 issue，但 issue 本身不应引用具体 files、line numbers 或 internal implementation details。

3. Assess scope: single issue or breakdown?

file 前判断这是单个 issue，还是需要拆成多个 issues。

拆分条件：

• fix 跨多个 independent areas（例如 “form validation is wrong AND success message is missing AND redirect is broken”）
• 存在清晰可分离 concerns，不同人可以并行处理
• 用户描述了多个不同 failure modes 或 symptoms

保持单个 issue 的条件：

• 一个地方的一个 behavior 错了
• symptoms 都来自同一个 root behavior

4. File the GitHub issue(s)

使用 gh issue create 创建 issues。不要先要求用户 review；直接 file 并分享 URLs。

Issues 必须 durable，即 major refactors 后仍有意义。从用户视角写。

For a single issue

使用这个模板：

## What happened

[用普通语言描述用户经历的实际行为]

## What I expected

[描述期望行为]

## Steps to reproduce

1. [developer 可执行的具体编号步骤]
2. [使用 codebase 的 domain terms，不用 internal module names]
3. [包含相关 inputs、flags 或 configuration]

## Additional context

[来自用户或 codebase exploration 的额外观察，用来帮助 framing — 例如 “this only happens when using the Docker layer, not the filesystem layer” — 使用 domain language，但不引用 files]

For a breakdown (multiple issues)

按 dependency order 创建 issues（blockers first），这样可以引用真实 issue numbers。

每个 sub-issue 使用这个模板：

## Parent issue

#<parent-issue-number>（如果你创建了 tracking issue）或 "Reported during QA session"

## What's wrong

[描述这个 specific behavior problem — 只描述这个 slice，而非整个 report]

## What I expected

[这个 slice 的 expected behavior]

## Steps to reproduce

1. [只针对这个 issue 的步骤]

## Blocked by

- #<issue-number>（如果必须等另一个 issue 解决）

如果没有 blockers，写 "None — can start immediately"。

## Additional context

[与这个 slice 相关的额外观察]

创建 breakdown 时：

• Prefer many thin issues over few thick ones — 每个都应能独立 fix 和 verify
• Mark blocking relationships honestly — 如果 B 确实必须等 A 才能测试，就说明。如果独立，两个都写 “None — can start immediately”
• Create issues in dependency order，这样可以在 “Blocked by” 中引用真实 issue numbers
• Maximize parallelism — 目标是让多人（或 agents）能同时领取不同 issues

Rules for all issue bodies

• No file paths or line numbers — 它们会过时
• Use the project's domain language（如果存在，检查 UBIQUITOUS_LANGUAGE.md）
• Describe behaviors, not code — 写 “the sync service fails to apply the patch”，不要写 “applyPatch() throws on line 42”
• Reproduction steps are mandatory — 如果无法确定，询问用户
• Keep it concise — developer 应能 30 秒内读完 issue

file 后，打印所有 issue URLs（并总结 blocking relationships），然后问：“Next issue, or are we done?”

5. Continue the session

持续进行，直到用户说结束。每个 issue 都独立处理，不要 batch。