qa-to-engineering-brief

QA to Engineering Brief

Overview

Use this skill when a bug report is too vague for a builder but too real to ignore.

The output is not a diagnosis essay. It is a brief a builder can execute and a reviewer can verify.

When to Use

• User reports something broken.
• Screenshot shows confusing UI state.
• QA notes are scattered across chat.
• A bug seems intermittent.
• A failing workflow needs reproduction steps.
• You need to turn panic into an engineering slice.

Brief Structure

# [Short bug title]

## User-visible problem
[What the user experienced]

## Expected behaviour
[What should happen]

## Actual behaviour
[What happened]

## Evidence
[Screenshots, logs, run IDs, URLs, files, timestamps]

## Reproduction steps
1.
2.
3.

## Scope
In:
Out:

## Suspected area
[Files, services, components, data path]

## Severity
HIGH / MEDIUM / LOW with rationale

## Acceptance criteria
- [ ] Behaviour fixed
- [ ] Regression test added
- [ ] Runtime/browser/API proof captured

## Required verification
[Exact tests and smoke checks]

## Owner / role
[Builder or triage owner]

Severity Guide

HIGH:

• data loss;
• security or permission breach;
• payment/money/account impact;
• production feature structurally inert;
• user cannot complete core workflow.

MEDIUM:

• important workflow degraded;
• no regression test catches plausible failure;
• misleading user-facing state;
• recoverable but costly failure.

LOW:

• minor UX issue with no workflow break;
• copy/visual defect;
• small edge case with clear workaround.

Evidence Rules

• Screenshots need a timestamp or context.
• Logs need file/source and relevant lines.
• User quotes are evidence of perception, not root cause.
• Reproduction steps must be concrete enough for another agent.
• If you cannot reproduce, say what was tried and what remains unknown.

Anti-patterns

• "It feels broken" with no expected behaviour.
• Starting with suspected code before user impact.
• Filing a giant omnibus bug.
• Severity based on emotion instead of regression impact.
• Acceptance criteria that say "fix it".