qa

Files (1)

• SKILL.md

SKILL.md (first lines)

# QA Session

Run an interactive QA session. The user describes problems they have encountered. You ask clarifying questions, 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 short clarifying questions**, focused on:

- What they expected and what actually happened
- Reproduction steps (if not obvious)
- Whether the behavior is stable or flaky

Do NOT interrogate. If the description is enough to file an issue, move on.

### 2. Explore the codebase in the background

While talking with the user, launch an agent (subagent_type=Explore) in the background to investigate the relevant area. The goal is NOT to find a fix, but to:

- Learn the domain language used in this area (check UBIQUITOUS_LANGUAGE.md)
- Understand what the feature is supposed to do
- Identify the boundary of user-facing behavior

This context helps write a higher-quality issue, but the issue itself MUST NOT reference specific files, line numbers, or internal implementation details.

### 3. Assess scope: single issue or breakdown?

Before filing, decide: is this **one issue** or should it be **broken down** into several?

Break down when:

- The fix touches multiple independent areas (e.g., "form validation is wrong AND the success message is missing AND the redirect is broken")
- There are clearly separable tasks that different people could work on in parallel
- The user describes something with several distinct failure modes or symptoms

Keep it as one issue when:

- It is a single behavior that is wrong in one place
- All symptoms stem from the same root behavior

### 4. File the GitHub issue

Create issues via `gh issue create`. Do NOT ask the user to review first — just file and share the URL.

Issues should be **durable** — they should remain meaningful after major refactors. Write from the user's point of view.

#### For a single issue

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

#### For a breakdown (multiple issues)

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

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 breaking down:

- **Prefer many thin issues over a few thick ones** — each should be independently fixable and verifiable
- **Be honest about blocking relationships** — if issue B truly cannot be tested until issue A is fixed, say so. If they are independent, mark both as "None — can start immediately"
- **Create issues in dependency order**, so you can reference real numbers in "Blocked by"
- **Maximize parallelism** — the goal is for several people (or agents) to be able to pick up different issues simultaneously

#### Rules for all issue bodies

- **No file paths or line numbers** — they go stale
- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists)
- **Describe behavior, not code** — "the sync service fails to apply the patch", not "applyPatch() throws on line 42"
- **Reproduction steps are required** — if you cannot determine them, ask the user
- **Be concise** — a developer should be able to read the issue in 30 seconds

From wachawo/claude-skills, MIT.

More from wachawo/claude-skills