/qa-session

name: qa-session
description: "Interactive QA: user reports bugs conversationally, agent files GitHub issues. Triggers: QA session, report bug, file issue, conversational QA, bug intake."
user-invocable: true
effort: high
argument-hint: "[area to QA or first bug report]"
allowed-tools: Read, Grep, Glob, Bash, Agent

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

| Decision | When | |----------|------| | **Single issue** | One behavior wrong in one place | | **Breakdown** | Multiple independent areas, separable concerns, distinct failure modes |

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