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