Qa Report

---
name: qa-report
description: Generate comprehensive test plans, test cases, regression test suites, automation annotations, and bug reports for QA engineers. Includes Figma MCP integration for design validation. Use when planning QA before execution, documenting test strategies, marking which flows require E2E follow-up, or creating structured bug reports. Do not use for executing tests against a live repository or running verification gates — use qa-execution for that.
trigger: explicit
argument-hint: "[qa-output-path]"
---

# QA Test Planner

Plan and document QA deliverables — test plans, test cases, regression suites, Figma validations, and bug reports — in a structured format compatible with `qa-execution` execution.

## Required Inputs

- **qa-output-path** (optional): Directory where all QA artifacts are stored. When provided, create the directory if it does not exist. When omitted, use the current working directory. This path must match the same argument passed to `qa-execution` when both skills are used together.

## Shared Output Structure

All artifacts follow this directory layout, shared with `qa-execution`:

```
<qa-output-path>/qa/
├── test-plans/          # Test plan documents
├── test-cases/          # Individual test case files (TC-*.md)
├── issues/              # Bug reports (BUG-*.md)
├── screenshots/         # Visual evidence and Figma comparisons
└── verification-report.md  # Generated by qa-execution
```

## Procedures

**Step 1: Resolve Output Directory**

1. If the user provided a `qa-output-path` argument, use that path.
2. Otherwise, default to the current working directory.
3. Create the `qa/` subdirectory under the resolved path, then create `qa/test-plans/`, `qa/test-cases/`, `qa/issues/`, and `qa/screenshots/` if they do not exist.

**Step 2: Identify the Deliverable Type**

Parse the user request to determine which deliverable to generate:

| Request Pattern | Deliverable | Output Path |
|-----------------|-------------|-------------|
| "Create test plan for..." | Test Plan | `test-plans/` |
| "Generate test cases for..." | Test Cases | `test-cases/` |
| "Build regression suite..." | Regression Suite | `test-plans/` |
| "Compare with Figma..." | Figma Validation | `test-cases/` (TC-UI-*) |
| "Document bug..." | Bug Report | `issues/` |

**Step 3: Generate Test Plans**

1. Read `references/test_case_templates.md` for the test plan structure.
2. Generate a test plan document with these mandatory sections:
   - Executive summary with objectives and key risks.
   - Scope definition (in-scope and out-of-scope).
   - Test strategy and approach.
   - Automation strategy covering which flows should become E2E, which remain manual-only, and which are blocked by environment gaps.
   - Environment requirements (OS, browsers, devices).
   - Entry criteria (what must be true before testing begins).
   - Exit criteria (what must be true before testing ends, including pass-rate thresholds and automation follow-up expectations for critical flows).
   - Risk assessment table (Risk, Probability, Impact, Mitigation).
   - Timeline and deliverables.
3. Write the plan to `<qa-output-path>/qa/test-plans/<feature-slug>-test-plan.md`.

**Step 4: Generate Test Cases**

1. Read `references/test_case_templates.md` to select the appropriate template variant (Functional, UI, Integration, Regression, Security, Performance).
2. Assign each test case an ID following the naming scheme:

   | Type | Prefix | Example |
   |------|--------|---------|
   | Functional | TC-FUNC- | TC-FUNC-001 |
   | UI/Visual | TC-UI- | TC-UI-045 |
   | Integration | TC-INT- | TC-INT-012 |
   | Regression | TC-REG- | TC-REG-089 |
   | Security | TC-SEC- | TC-SEC-005 |
   | Performance | TC-PERF- | TC-PERF-023 |
   | Smoke | SMOKE- | SMOKE-001 |

3. Each test case must include:
   - **Priority:** P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low).
   - **Objective:** What is being validated and why.
   - **Preconditions:** Setup requirements and test data.
   - **Test Steps:** Numbered actions with an `**Expected:**` result for each.
   - **Edge Cases:** Boundary values, null inputs, special characters.
   - **Automation Target:** `E2E`, `Integration`, or `Manual-only`.
   - **Automation Status:** `Existing`, `Missing`, `Blocked`, or `N/A`.
   - **Automation Command/Spec:** Existing spec path or command when known.
   - **Automation Notes:** Why the case should be automated, remain manual, or is blocked.
4. Write each test case to `<qa-output-path>/qa/test-cases/<TC-ID>.md`.
5. When generating test cases interactively, execute `scripts/generate_test_cases.sh <qa-output-path>/test-cases`.

**Step 5: Build Regression Suites**

1. Read `references/regression_testing.md` for suite structure and execution strategy.
2. Classify tests into tiers:

   | Suite | Duration | Frequency | Coverage |
   |-------|----------|-----------|----------|
   | Smoke | 15-30 min | Daily/per-build | Critical paths only |
   | Targeted | 30-60 min | Per change | Affected areas |
   | Full | 2-4 hours | Weekly/Release | Comprehensive |
   | Sanity | 10-15 min | After hotfix | Quick validation |

3. Prioritize test cases using the shared priority scale:
   - **P0:** Business-critical, security, revenue-impacting — must run always.
   - **P1:** Major features, common flows — run weekly or more.
   - **P2:** Minor features, edge cases — run at releases.
4. Mark automation candidates explicitly:
   - Tag changed or regression-critical P0 and P1 public flows as `Automation Target: E2E` when the repository already has an E2E harness.
   - Tag bug-driven public regressions as `Automation Status: Missing` until `qa-execution` confirms the spec was added or updated.
   - Tag exploratory, visual-judgment, or unsupported flows as `Manual-only` or `Blocked` with a reason.
5. Define execution order: Smoke first (if fails, stop) → P0 → P1 → P2 → Exploratory.
6. Define pass/fail criteria:
   - **PASS:** All P0 pass, 90%+ P1 pass, no critical bugs open.
   - **FAIL:** Any P0 fails, critical bug discovered, security vulnerability, data loss.
   - **CONDITIONAL:** P1 failures with documented workarounds, fix plan in place.
7. Write the suite document to `<qa-output-path>/qa/test-plans/<suite-name>-regression.md`.

**Step 6: Validate Against Figma Designs**

Skip this step if Figma MCP is not configured.

1. Read `references/figma_validation.md` for the validation workflow.
2. Extract design specifications from Figma using MCP queries:
   - Dimensions (width, height).
   - Colors (background, text, border — exact hex values).
   - Typography (font family, size, weight, line-height, color).
   - Spacing (padding, margin).
   - Border radius, shadows.
   - Interactive states (default, hover, active, focus, disabled).
3. Generate UI test cases (TC-UI-*) that compare each property against the implementation.
4. Test responsive behavior at these standard viewports:
   - Mobile: 375px.
   - Tablet: 768px.
   - Desktop: 1280px.
5. When validation reveals discrepancies, generate a bug report following Step 7.
6. Use `agent-browser` (from the `qa-execution` companion skill) when browser-based verification is needed. The core loop is: open → snapshot → interact → re-snapshot → verify.

**Step 7: Create Bug Reports**

1. Use the unified bug report format from `assets/issue-template.md`, shared with `qa-execution`.
2. Assign a bug ID with the `BUG-` prefix (e.g., `BUG-001`).
3. Every bug report must include:
   - **Severity:** Critical | High | Medium | Low.
   - **Priority:** P0 | P1 | P2 | P3.
   - **Environment:** Build, OS, Browser, URL.
   - **Reproduction:** Exact steps to reproduce.
   - **Expected vs Actual:** Clear descriptions.
   - **Impact:** Users affected, frequency, workaround.
   - **Related:** TC-ID if discovered during test case execution, Figma URL if UI bug.
4. Write each bug report to `<qa-output-path>/qa/issues/<BUG-ID>.md`.
5. When creating bug reports interactively, execute `scripts/create_bug_report.sh <qa-output-path>/issues`.

**Step 8: Validate Completeness**

1. Verify all generated test cases have an expected result for each step.
2. Verify all bug reports have reproducible steps.
3. Verify traceability: test cases reference requirements, bugs reference test cases.
4. Verify every planned critical flow has an explicit automation annotation and that `Missing` or `Blocked` states include a reason.
5. Cross-reference against `../qa-execution/references/checklist.md` for coverage gaps when planning for later execution.

## Severity Definitions

| Level | Criteria | Examples |
|-------|----------|---------|
| Critical | System crash, data loss, security breach | Payment fails, login broken |
| High | Major feature broken, no workaround | Search not working, checkout fails |
| Medium | Feature partial, workaround exists | Filter missing option, slow load |
| Low | Cosmetic, rare edge case | Typo, minor alignment |

## Priority vs Severity Matrix

|  | Low Impact | Medium | High | Critical |
|--|-----------|--------|------|----------|
| **Rare** | P3 | P3 | P2 | P1 |
| **Sometimes** | P3 | P2 | P1 | P0 |
| **Often** | P2 | P1 | P0 | P0 |
| **Always** | P2 | P1 | P0 | P0 |

## Companion Skill: qa-execution

The `qa-report` and `qa-execution` skills share a common output directory and artifact format. The intended workflow:

1. **Plan first** with `qa-report`: generate test plans, test cases, and regression suites.
2. **Execute** with `qa-execution`: run verification gates, exercise flows end-to-end, discover bugs, and add or update E2E coverage when the repository already supports it.
3. **Document** with `qa-report`: create structured bug reports for issues found during execution.

When `qa-execution` runs after `qa-report`, it reads test cases from `<qa-output-path>/qa/test-cases/` to inform its execution matrix, automation priorities, and reporting fields, then writes bugs to `<qa-output-path>/qa/issues/` using the same unified template.

## Error Handling

- If the `qa-output-path` directory cannot be created, report the error and fall back to the current working directory.
- If Figma MCP is not configured, skip Figma validation steps and note the gap in the test plan.
- If `agent-browser` is not available for UI validation, generate test cases as documentation for manual execution and note the limitation.
- If the repository does not have a known E2E harness, mark affected cases as `Manual-only` or `Blocked` instead of inventing automation commands.
- If the user provides a feature description that is too vague to generate test cases, ask for specific requirements, user flows, or acceptance criteria before proceeding.