QA Session
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
1. Listen and lightly clarify
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
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?
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)
Use
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
Use this template:
## What happened
[Describe the actual behavior the user experienced in plain language]
## What I expected
[Describe the expected behavior]
## Steps to reproduce
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 observations from the user or codebase exploration to help frame the issue; use domain language but do not reference files]
For a breakdown (multiple issues)
Create issues in dependency order (blockers first) so that you can reference real issue numbers.
Each sub-issue uses this template:
## Parent issue
#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"
## What's wrong
[Describe this specific behavior problem, only this slice]
## What I expected
[The expected behavior for this slice]
## Steps to reproduce
1. [Steps specific only to this issue]
## Blocked by
- #<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 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
- 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
Keep going until the user says it's over. Handle each issue independently, do not batch them.