Back to Details

qa

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

QA Session

QA Session

运行交互式 QA session。用户描述遇到的问题。你负责澄清、探索 codebase 获取 context，并创建 durable、user-focused 且使用项目 domain language 的 GitHub issues。
Run an interactive QA session. Users describe the problems they encounter. You are responsible for clarifying, exploring the codebase to obtain context, and creating durable, user-focused GitHub issues that use the project's domain language.

For each issue the user raises

For each issue the user raises

1. Listen and lightly clarify

1. Listen and lightly clarify

让用户用自己的话描述问题。最多问 2-3 个简短 clarifying questions，聚焦：
  • 他们期望什么，实际发生了什么
  • Steps to reproduce（如果不明显）
  • 是否稳定复现，还是 intermittent
不要过度访谈。如果描述足够清楚，可以直接 file。
Ask the user to describe the problem in their own words. Ask at most 2-3 short clarifying questions, focusing on:
  • What they expected vs. what actually happened
  • Steps to reproduce (if not obvious)
  • Whether it reproduces consistently or is intermittent
Don't over-interview. If the description is clear enough, you can file directly.

2. Explore the codebase in the background

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。
While conversing with the user, start an Agent (subagent_type=Explore) in the background to understand the relevant areas. The goal is not to find a fix, but to:
  • Learn the domain language used in this area (check UBIQUITOUS_LANGUAGE.md)
  • Understand what the feature is supposed to do
  • Identify user-facing behavior boundaries
This context helps you write better issues, but the issue itself should not reference specific files, line numbers, or internal implementation details.

3. Assess scope: single issue or breakdown?

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
Before filing, determine if this is a single issue or needs to be broken down into multiple issues.
Conditions for breakdown:
  • The fix spans multiple independent areas (e.g., "form validation is wrong AND success message is missing AND redirect is broken")
  • There are clearly separable concerns that different people can work on in parallel
  • The user describes multiple distinct failure modes or symptoms
Conditions for keeping it a single issue:
  • One behavior is wrong in one place
  • All symptoms stem from the same root behavior

4. File the GitHub issue(s)

4. File the GitHub issue(s)

使用 
gh issue create
创建 issues。不要先要求用户 review；直接 file 并分享 URLs。
Issues 必须 durable，即 major refactors 后仍有意义。从用户视角写。
Use 
gh issue create
to create issues. Do not ask the user to review first; file directly and share the URLs.
Issues must be durable, meaning they remain meaningful even after major refactors. Write from the user's perspective.

For a single issue

For a single issue

使用这个模板：
undefined
Use this template:
undefined

What happened

What happened

[用普通语言描述用户经历的实际行为]
[Describe the actual behavior the user experienced in plain language]

What I expected

What I expected

[描述期望行为]
[Describe the expected behavior]

Steps to reproduce

Steps to reproduce

  1. [developer 可执行的具体编号步骤]
  2. [使用 codebase 的 domain terms，不用 internal module names]
  3. [包含相关 inputs、flags 或 configuration]
  1. [Specific numbered steps that developers can execute]
  2. [Use the codebase's domain terms, not internal module names]
  3. [Include relevant inputs, flags, or configuration]

Additional context

Additional context

[来自用户或 codebase exploration 的额外观察，用来帮助 framing；使用 domain language，但不引用 files]
undefined
[Additional observations from the user or codebase exploration to help frame the issue; use domain language but do not reference files]
undefined

For a breakdown (multiple issues)

For a breakdown (multiple issues)

按 dependency order 创建 issues（blockers first），这样可以引用真实 issue numbers。
每个 sub-issue 使用这个模板：
undefined
Create issues in dependency order (blockers first) so that you can reference real issue numbers.
Each sub-issue uses this template:
undefined

Parent issue

Parent issue

#<parent-issue-number>（如果你创建了 tracking issue）或 "Reported during QA session"
#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"

What's wrong

What's wrong

[描述这个 specific behavior problem，只描述这个 slice]
[Describe this specific behavior problem, only this slice]

What I expected

What I expected

[这个 slice 的 expected behavior]
[The expected behavior for this slice]

Steps to reproduce

Steps to reproduce

  1. [只针对这个 issue 的步骤]
  1. [Steps specific only to this issue]

Blocked by

Blocked by

  • #<issue-number>（如果必须等另一个 issue 解决）
如果没有 blockers，写 "None — can start immediately"。
  • #<issue-number> (if you must wait for another issue to be resolved)
If there are no blockers, write "None — can start immediately".

Additional context

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
[Additional observations relevant to this slice]

When creating a breakdown:

- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
- **Mark blocking relationships honestly** — if B truly must wait for A to be tested, state it. If independent, write "None — can start immediately" for both
- **Create issues in dependency order** so that you can reference real issue numbers in the "Blocked by" section
- **Maximize parallelism** — aim to allow multiple people (or agents) to pick up different issues simultaneously

Rules for all issue bodies

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?”
  • No file paths or line numbers — they become outdated
  • Use the project's domain language (if available, check UBIQUITOUS_LANGUAGE.md)
  • Describe behaviors, not code — write "the sync service fails to apply the patch" instead of "applyPatch() throws on line 42"
  • Reproduction steps are mandatory — if unsure, ask the user
  • Keep it concise — developers should be able to read the issue in 30 seconds
After filing, print all issue URLs (and summarize blocking relationships), then ask: "Next issue, or are we done?"

5. Continue the session

5. Continue the session

持续进行，直到用户说结束。每个 issue 都独立处理，不要 batch。
Keep going until the user says it's over. Handle each issue independently, do not batch them.