Run an interactive QA session. The user describes what they're running into. You clarify, explore the codebase for context, and file durable, user-centered GitHub issues using the project's domain language.
For each problem the user raises
1. Listen and lightly clarify
Let the user describe the problem in their own words. Ask at most2-3 brief clarifying questions, focused on:
- What they expected vs. what happened
- Steps to reproduce (if not obvious)
- Whether it's consistent or intermittent
Don't over-ask. If the description is clear enough to file, proceed.
2. Explore the codebase in the background
While talking with the user, launch an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal isn't to find a fix—it's to:
- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
- Understand what the feature is supposed to do
- Identify the user-facing behavior boundary
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 does it need splitting?
Before filing, decide whether this is asingle issue or needs to besplitinto multiple issues.
Split when:
- The fix involves multiple independent areas (e.g. "form validation error AND missing success message AND broken redirect")
- There are clearly separable concerns that different people could work on in parallel
- What the user describes has multiple distinct failure modes or symptoms
Keep as a single issue when:
- One behavior in one place is wrong
- All symptoms stem from the same underlying behavior
4. File the GitHub issue
Use gh issue create to create the issue. Don't ask the user to review first—just file it and share the URL.
Issues must bedurable—they should still make sense after a major refactor. Write from the user's perspective.
For a single issue
Use this template:
## 发生了什么
[用通俗语言描述用户经历的实际行为]
## 我的预期
[描述预期的行为]
## 重现步骤
1. [开发人员可以遵循的具体编号步骤]
2. [使用代码库中的领域术语，而不是内部模块名称]
3. [包括相关的输入、标志或配置]
## 附加上下文
[来自用户或代码库探索的任何额外观察，有助于框定问题——例如"这仅在使用 Docker 层时发生，而不是文件系统层"——使用领域语言但不要引用文件]
For splits (multiple issues)
Create issues in dependency order (blockers first) so you can reference real issue numbers.
Use this template for each child issue:
## 父 issue
#<父 issue 编号>（如果你创建了跟踪 issue）或"在 QA 会话期间报告"
## 什么问题
[描述这个特定的行为问题——仅这一部分，不是整个报告]
## 我的预期
[此特定部分的预期行为]
## 重现步骤
1. [专门针对此 issue 的步骤]
## 阻塞于
- #<issue 编号>（如果在解决另一个 issue 之前无法修复此 issue）
或"无——可以立即开始"（如果没有阻塞项）。
## 附加上下文
[与此部分相关的任何额外观察]
When creating splits:
- Prefer multiple thin issues over a few thick issues—each should be independently fixable and verifiable
- Flag blocking relationships honestly—if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None—can start immediately"
- Create issues in dependency orderso you can reference real issue numbers in "Blocked by"
- Maximize parallelism— the goal is that multiple people (or agents) can work on different issues simultaneously
Rules for all issue bodies
- No file paths or line numbers— these go stale
- Use the project's domain language(if one exists, check UBIQUITOUS_LANGUAGE.md)
- Describe behavior, not code— "the sync service cannot apply the patch" rather than "applyPatch() throws an exception on line 42"
- Reproduction steps are required— if you cannot determine them, ask the user
- Keep it concise— a developer should be able to read the issue in 30 seconds
After submitting, print all issue URLs (summarizing the blocking relationships) and 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.