qa

QA Session

Run an interactive QA session. The user describes the problem they encountered. You clarify, explore the codebase for context, and file a durable, user-centered GitHub issue using the project's domain language.

Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.

For each issue the user raises

1. Listen and clarify lightly

Let the user describe the problem in their own words. Ask at most 2-3 brief clarifying questions, focusing on:

Let the user describe the problem in their own words. Ask at most 2-3 short clarifying questions focused on:

• What they expected vs what actually happened

  What they expected vs what actually happened

• Steps to reproduce (if not already obvious)

  Steps to reproduce (if not obvious)

• Whether it happens consistently or intermittently

  Whether it's consistent or intermittent

Don't over-interview. If the description is clear enough to file, move on.

Do NOT over-interview. If the description is clear enough to file, move on.

2. Explore the codebase in the background

While talking with the user, launch an Agent (subagent_type=Explore) in the background to learn about the relevant area. The goal is not to find a fix — it is to:

While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:

• Learn the domain language used in that area (see UBIQUITOUS_LANGUAGE.md)

  Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)

• Understand what the feature is supposed to do

  Understand what the feature is supposed to do

• Determine the boundaries of user-facing behavior

  Identify the user-facing behavior boundary

This context helps you write a better issue — but the issue itself should not reference specific files, line numbers, or internal implementation details.

This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.

3. Assess scope: single issue or split?

Before filing, determine whether this is asingle issueor needs to besplitinto multiple issues.

Before filing, decide whether this is a single issue or needs to be broken down into multiple issues.

Split when:

Break down when:

• The fix involves multiple independent areas (e.g., "form validation is wrong and the success message is missing and the redirect is broken")

  The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")

• There are clearly separable concerns that different people can work on in parallel

  There are clearly separable concerns that different people could work on in parallel

• The user described a problem with multiple different failure modes or symptoms

  The user describes something that has multiple distinct failure modes or symptoms

Keep as a single issue when:

Keep as a single issue when:

• It is one behavior in one place that is wrong

  It's one behavior that's wrong in one place

• All symptoms are caused by the same underlying behavior

  The symptoms are all caused by the same root behavior

4. File the GitHub issue

Use gh issue create to create the issue. Don't ask the user to review first — file it and share the URL.

Create issues with gh issue create. Do NOT ask the user to review first — just file and share URLs.

The issue must bedurable — it should still make sense even after a large-scale refactor. Write it from the user's perspective.

Issues must be durable — they should still make sense after major refactors. Write from the user's perspective.

Single issue template

Use this template:

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. [Concrete, numbered steps a developer can follow]
2. [Use domain terms from the codebase, not internal module names]
3. [Include relevant inputs, flags, or configuration]

## Additional context

[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]

Split case (multiple issues)

Create the issues in dependency order (create blockers first) so that you can reference real issue numbers.

Create issues in dependency order (blockers first) so you can reference real issue numbers.

Use this template for each sub-issue:

Use this template for each sub-issue:

## Parent issue

#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"

## What's wrong

[Describe this specific behavior problem — just this slice, not the whole report]

## What I expected

[Expected behavior for this specific slice]

## Steps to reproduce

1. [Steps specific to THIS issue]

## Blocked by

- #<issue-number> (if this issue can't be fixed until another is resolved)

Or "None — can start immediately" if no blockers.

## Additional context

[Any extra observations relevant to this slice]

When creating a split:

When creating a breakdown:

• Prefer multiple thin issues over a few thick issues — each should be independently fixable and verifiable

  Prefer many thin issues over few thick ones — 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 are independent, mark them all as "None — can start immediately"

  Mark 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 the issues in dependency order, so you can reference the real issue number in "Blocked by"

  Create issues in dependency order so 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

  Maximize parallelism — the goal is that multiple people (or agents) can grab different issues simultaneously

Rules for all issue bodies

• Do not include file paths or line numbers — these will become outdated

  No file paths or line numbers — these go stale

• Use the project's domain language(check UBIQUITOUS_LANGUAGE.md if it exists)

  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"

  Describe behaviors, not code — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"

• Reproduction steps are required — if they cannot be determined, ask the user

  Reproduction steps are mandatory — if you can't determine them, ask the user

• Keep it concise — a developer should be able to read the issue within 30 seconds

  Keep it concise — a developer should be able to read the issue in 30 seconds

After submitting, print all issue URLs (with a summary of blocking relationships) and ask: "Next question, or are we done?"

After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"

5. Continue the session

Continue until the user says to stop. Each issue is independent — do not batch them.

Keep going until the user says they're done. Each issue is independent — don't batch them.