Run an interactive QA session. The user describes the problem they encountered. You clarify, explore the codebase for context, then file persistent, user-centered GitHub Issues that use the project's domain language.
For each issue raised by the user
1. Listen and clarify moderately
Let the user describe the problem in their own words. Ask at most 2-3 brief clarifying questions, focusing on:
- The difference between the result they expected and the result that actually occurred
- Reproduction steps (if not obvious)
- Whether the problem reproduces consistently or intermittently
Don't over-inquire. If the description is clear enough to file an Issue, move on to the next step.
2. Explore the codebase in the background
While talking with the user, launch an Agent in the background (subagent_type=Explore) to understand the relevant area. The goal is not to find a fix, but to:
- Learn the domain language used in that area (see UBIQUITOUS_LANGUAGE.md)
- Understand what the feature is supposed to do
- Identify user-visible behavior boundaries
This context helps you write a better Issue—but the Issue itself should not reference specific file paths, line numbers, or internal implementation details.
3. Assess scope: a single Issue or split into multiple?
Before filing, determine whether this isa single Issue or needs to besplit into multiple Issue。
When splitting is needed:
- The fix involves multiple independent areas (for example, "form validation is wrong, the success message doesn't show, and the redirect is broken too")
- There are clearly separable concerns that different people can work on in parallel
- The problem described by the user includes multiple distinct failure modes or symptoms
When to keep it as a single Issue:
- It is the same behavior going wrong in the same place
- All symptoms are caused by the same root cause
4. File the GitHub Issue
Use gh issue create to create the Issue.Do nothave the user review it first—file it directly and share the URL.
The Issue must bepersistent—it should still make sense even after a major refactor. Write it from the user's perspective.
Single Issue
Use the following template:
## 发生了什么
[用通俗的语言描述用户实际遇到的行为]
## 我期望的结果
[描述期望的行为]
## 复现步骤
1. [开发者可以遵循的具体、编号步骤]
2. [使用代码库中的领域术语，而不是内部模块名]
3. [包含相关的输入、标志或配置]
## 附加上下文
[来自用户或代码库探索的任何额外观察，有助于界定问题——例如"仅在使用 Docker layer 时发生，使用 filesystem layer 时不会"——使用领域语言，但不要引用文件"]
Split into multiple Issues
Create the Issues in dependency order (blockers first) so that you can reference real Issue numbers.
Use the following template for each sub-Issue:
## 父 Issue
#<父 Issue 编号>（如果你创建了跟踪 Issue）或"在 QA 会话期间报告"
## 问题描述
[描述这个具体的行为问题——仅限这一部分，不是整个报告]
## 我期望的结果
[针对这一部分的期望行为]
## 复现步骤
1. [仅针对此 Issue 的步骤]
## 被阻塞者
- #<Issue 编号>（如果此 Issue 需要先解决另一个 Issue 才能修复）
如果没有阻塞者，填写"无——可以立即开始"。
## 附加上下文
[与此部分相关的任何额外观察]
When creating split Issues:
- Prefer many thin ones over few thick ones—each Issue should be independently fixable and verifiable
- Mark blocking relationships truthfully—if Issue B truly needs Issue A to be fixed before it can be tested, state that truthfully. If they are independent of each other, mark both as "None—can start immediately"
- Create the Issues in dependency order——This way you can reference the real Issue number in the "blocked by"
- Maximize parallelism——The goal is to let multiple people (or multiple Agents) work on different Issues simultaneously
Rules for all Issue bodies
- Do not include file paths or line numbers——these will become outdated
- Use the project's domain language(check UBIQUITOUS_LANGUAGE.md if it exists)
- Describe behavior, not code——"the sync service cannot apply the patch" rather than "applyPatch() throws an exception at line 42"
- Reproduction steps are mandatory——if you cannot determine them, ask the user
- Keep it concise——developers should be able to finish reading the Issue within 30 seconds
After submitting, print all Issue URLs (and summarize the blocking relationships), then ask: "Next Issue, or are we done?"
5. Continue the session
Continue until the user says they are done. Each Issue is independent——do not batch them.