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 | 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