Run an interactive QA session. The user describes the problem they encountered. You clarify, explore the codebase for context, then submit GitHub issues that stand the test of time, are user-centered, and use the project's domain language.
For each issue the user raises
1. Listen and clarify appropriately
Let the user describe the problem in their own words. Askat most 2-3 brief clarifying questions, focused on:
- What they expected vs. what actually happened
- Reproduction steps (if not obvious)
- Whether it happens consistently or intermittently
Don't over-question. If the description is already clear enough to submit, move on.
2. Explore the codebase in the background
While conversing with the user, launch an Agent in the background (subagent_type=Explore) to understand the relevant domain. The goal is not to find the fix—rather to:
- Understand the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
- Understand what the feature is supposed to do
- Identify the boundaries of user-visible behavior
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 multiple?
Before submitting, determine whether this is asingle issue or needsto be split into multiple issues。
Split when:
- The fix spans multiple independent domains (e.g., "form validation is wrong AND the success message is missing AND the redirect is broken")
- There are clearly separable concerns that different people could work on in parallel
- The user described multiple distinct failure modes or symptoms
Keep it a single issue when:
- It's one behavior in one place that's broken
- All symptoms are caused by the same root-cause behavior
4. Submit the GitHub issue
Use gh issue create to create the issue. Don't have the user review it first—just submit and share the link.
Issues must beable to stand the test of time—they should still make sense even after a major refactor. Write from the user's perspective.
For a single issue
Use the following template:
## 发生了什么
[用通俗语言描述用户实际体验到的行为]
## 我期望什么
[描述期望的行为]
## 复现步骤
1. [开发者可以照着做的具体、编号的步骤]
2. [使用代码库的领域术语，而非内部模块名]
3. [包含相关的输入、标志或配置]
## 补充上下文
[来自用户或代码库探索的任何额外观察，有助于框定 issue——例如"这只在使用 Docker 层时发生，使用文件系统层时不会"——使用领域语言但不要引用文件]
For the split case (multiple issues)
Create the issues in dependency order (blockers first) so you can reference the real issue numbers.
Use the following template for each sub-issue:
## 父 issue
#<父 issue 编号>（如果你创建了一个跟踪 issue）或"在 QA 环节中报告"
## 哪里出了问题
[描述这个具体的行为问题——只是这一块，不是整个报告]
## 我期望什么
[这一块具体期望的行为]
## 复现步骤
1. [仅针对本 issue 的步骤]
## 被阻塞于
- #<issue 编号>（如果本 issue 在另一个解决之前无法修复）
或"无——可以立即开始"如果没有阻塞项。
## 补充上下文
[与本块相关的任何额外观察]
When splitting:
- Err on the side of more—favor multiple small issues over a few large issues—each should be independently fixable and verifiable
- Mark blocking relationships honestly—if issue B truly cannot be tested until issue A is fixed, say so. If they're independent, mark both "None—can start immediately"
- Create issues in dependency order, so you can reference the real issue numbers in "blocked by"
- Maximize parallelism— The goal is for multiple people (or agents) to be able to claim different issues at the same time
Rules for all issue bodies
- Do not include file paths or line numbers— these things quickly become outdated
- Use the project's domain language(check UBIQUITOUS_LANGUAGE.md if it exists)
- Describe behavior, not code— "the sync service failed to apply the patch" rather than "applyPatch() threw an exception on line 42"
- Reproduction steps are mandatory— if you cannot determine them, ask the user
- Keep it concise— a developer should be able to read an issue in 30 seconds
After submitting, print all issue URLs (with a summary of blocking relationships) and ask: "Next issue, or stop here?"
5. Continue loop
Keep going until the user says done. Each issue is independent — do not batch them.