Run an interactive QA session. The user describes the problems they encountered. You are responsible for clarifying, exploring the codebase for context, and creating durable, user-focused GitHub issues that use the project's domain language.
For each issue the user raises
1. Listen and lightly clarify
Have the user describe the problem in their own words. Ask at most 2-3 short clarifying questions, focused on:
- What they expected, and what actually happened
- Steps to reproduce (if not obvious)
- Whether it reproduces reliably or is intermittent
Don't over-interview. If the description is clear enough, file directly.
2. Explore the codebase in the background
While conversing with the user, start 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 (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 issues themselves should not reference specific files, line numbers, or internal implementation details.
3. Assess scope: single issue or breakdown?
Before filing, determine whether this is asingle issue, or whether it needs to besplit into multiple issues。
Conditions for splitting:
- 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 described multiple distinct failure modes or symptoms
Conditions for keeping it a single issue:
- One behavior in one place is wrong
- The symptoms all come from the same root behavior
4. File the GitHub issue(s)
Use gh issue create to create issues. Don't ask the user to review first; file directly and share the URLs.
Issues must be durable, i.e. still meaningful after major refactors. Write from the user's perspective.
For a single issue
Use this template:
## 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)
Create issues in dependency order (blockers first), so that you can reference real issue numbers.
Use this template for each 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 相关的额外观察]
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 before it can be tested, say so. If independent, write "None — can start immediately" for both
- Create issues in dependency order, so that real issue numbers can be referenced in "Blocked by"
- Maximize parallelism — the goal is to let multiple people (or agents) pick up different issues simultaneously
Rules for all issue bodies
- No file paths or line numbers — they will go stale
- Use the project's domain language(if it exists, check UBIQUITOUS_LANGUAGE.md)
- Describe behaviors, not code — write "the sync service fails to apply the patch", not "applyPatch() throws on line 42"
- Reproduction steps are mandatory — if you can't determine it, ask the user
- Keep it concise — a developer should be able to read the issue in 30 seconds
After filing, print all issue URLs (and summarize the blocking relationships), then ask: "Next issue, or are we done?"
5. Continue the session
Keep going until the user says to stop. Handle each issue independently; don't batch.