QA Session

QA Session

$ARGUMENTS

Interactive QA session. User describes problems, agent clarifies, explores codebase, and files GitHub issues.

Usage

/qa-session [area to QA or first bug report]

What This Command Does

1. Listens to user's bug report
2. Clarifies with 2-3 focused questions max
3. Explores codebase in background for context and domain language
4. Assesses scope — single issue or breakdown
5. Files GitHub issues via gh issue create
6. Continues until user says done

For Each Issue

1. Listen and Lightly Clarify

Let user describe the problem. Ask at most 2-3 short questions on:

• Expected vs actual behavior
• Steps to reproduce
• Consistent or intermittent

Don't over-interview. If clear enough, move on.

2. Explore Codebase in Background

Kick off Agent (subagent_type=Explore) in background to:

• Learn domain language (check UBIQUITOUS_LANGUAGE.md)
• Understand what the feature should do
• Identify behavior boundaries

This helps write better issues — but issues must NOT reference files/lines.

3. Assess Scope

4. File GitHub Issues

Use gh issue create. Do NOT ask to review — file and share URLs.

Single issue template:

## What happened
[Actual behavior in plain language]

## What I expected
[Expected behavior]

## Steps to reproduce
1. [Concrete numbered steps]
2. [Use domain terms, not module names]

## Additional context
[Extra observations using domain language]

Breakdown template (for each sub-issue):

## Parent issue
#{parent-issue-number} or "Reported during QA session"

## What's wrong
[This specific behavior problem]

## What I expected
[Expected behavior for this slice]

## Steps to reproduce
1. [Steps specific to THIS issue]

## Blocked by
- #{issue-number} or "None — can start immediately"

5. Continue Session

After filing, share URLs and ask: "Next issue, or are we done?"

Rules

• MUST use the project's domain language from UBIQUITOUS_LANGUAGE.md — framework jargon in issues excludes non-engineering stakeholders
• MUST describe behaviors, not code — "sync service fails to apply patch" not "applyPatch() throws"
• MUST include reproduction steps — if they are not clear, ask the user rather than guess
• NEVER include file paths, line numbers, or function names in issue bodies — they go stale before triage
• NEVER over-interview. Cap clarifying questions at 2-3 per bug; more than that is signal the bug needs a QA session with a product owner, not more questions.
• CRITICAL: the developer who picks up the issue should understand it in 30 seconds. Wall-of-text reports get reopened for clarification.
• MANDATORY: when breaking one report into multiple issues, file them in dependency order so blockers have real issue numbers to reference

Gotchas

• Domain language in UBIQUITOUS_LANGUAGE.md may be out of date. If it was last updated months ago and new features have shipped, the glossary is an input hint, not a source of truth — confirm terms with the user when unsure.
• "Intermittent" reports are often environmental (one user's browser, one region's data) rather than truly random. Always ask for "how often" and "when did it start" before labeling as race condition.
• gh issue create opens $EDITOR without --body. In automation this hangs — always pass the body file or inline body.
• Users often describe the workaround as if it were the bug ("I have to refresh the page"). Drill to the underlying behavior — "what fails before the refresh?" — otherwise the fix targets the symptom.
• Independent sub-issues from one bug report can duplicate work if each gets a different developer. Mention the parent QA session in every sub-issue so reviewers notice the pattern.

When NOT to Use

• For triaging a single known bug with a proposed fix — use /triage-issue
• For creating issues from a PRD — use /prd-to-issues
• For debugging a reproducible error — use /debug
• For code review of a PR that addresses a bug — use /review
• For architecture-level problems — use /architecture-audit, not bug reports