/qa-planning

name: qa-planning
description: Generate QA Contract with numbered Gherkin scenarios (G#N) and acceptance criteria (AC#N)

QA Planning Skill

Generate the **QA Contract** - exhaustive Gherkin BDD scenarios (G#N) for all data sources and acceptance criteria (AC#N) for frontend. This contract is consumed by Plan Mode and verified by qa-commit skill.

When to Use

• During Ask mode Phase 2 (CONVERGE) for any feature work
• Before implementation to define testable acceptance criteria
• When documenting expected behavior for QA team

Output: QA Contract

The QA Contract is the primary artifact, consisting of:

• **G#1, G#2, ...** - Numbered Gherkin scenarios (backend/data)
• **AC#1, AC#2, ...** - Numbered acceptance criteria (frontend)

These IDs are referenced in Plan Mode's Commit Plan (Satisfies field) and verified by qa-commit skill.

Instructions

Phase 0: Identify ALL Data Sources (CRITICAL)

**STOP. Before writing any Gherkin, exhaustively map ALL data sources for the feature.**

Categorize each data source:

| Category | Description | Gherkin Type | |----------|-------------|--------------| | **Runtime API** | Fetched at request time from server | API scenarios (G#N) | | **Build-time Static** | Generated during build, served as static files | Build script scenarios (G#N) | | **Database** | Direct DB queries (Hasura, Postgres) | Query scenarios (G#N) | | **External API** | Third-party services | Integration scenarios (G#N) | | **Middleware** | Request routing, auth, transforms | Routing scenarios (G#N) |

**Data Source Inventory Template:**

## Data Source Inventory

### Runtime APIs
| Endpoint | Method | Auth | Resource | Status |
|----------|--------|------|----------|--------|
| `/v1/resource` | GET | Yes | Resource | Existing |
| `/public/resource` | GET | No | Resource | New |

### Build-time Static
| Output Path | Source | Generator | Content |
|-------------|--------|-----------|---------|
| `/components.json` | Codebase | Build script | Component metadata |
| `/charts/[slug].json` | Codebase | Build script | Chart config + examples |

### Database Queries
| Query | Source | Auth | Purpose |
|-------|--------|------|---------|
| `connectors` | Hasura | Yes | List connectors |

### Middleware
| Route | Behavior | Auth |
|-------|----------|------|
| `developers.*` | Rewrite to public routes | Skip |

### External APIs
| Service | Endpoint | Purpose |
|---------|----------|---------|
| (none for this feature) | | |

**Validation:** Count total data sources. If < 3 for a non-trivial feature, you likely missed something. Re-examine the feature scope.

Phase 2: Define Pre-conditions Matrix (Given)

For each service, treat it as a **black box**. Based on the contract interface or data model, list all pre-condition parameters:

### [Method] [Path] Pre-conditions

| Parameter | Type | Source | Possible Values |
|-----------|------|--------|-----------------|
| `Authorization` | header | request | valid_token, invalid_token, expired_token, missing |
| `id` | path | URL | existing_uuid, non_existing_uuid, malformed, deleted |
| `status` | query | URL | enum values from data model |
| `[field]` | body | JSON | valid, null, empty, wrong_type, too_long |

**Sources:**

• **header**: Authorization, Content-Type, custom headers
• **path**: URL parameters (`:id`, `:slug`)
• **query**: Query string filters, pagination
• **body**: Request payload fields

Phase 3: Map When (Method + Path)

Each scenario has exactly ONE action:

When [METHOD] [/path/to/resource]

Examples:

• `When GET /v1/connectors`
• `When POST /v1/connectors`
• `When GET /v1/connectors/{id}`
• `When DELETE /v1/connectors/{id}`

Phase 4: Define Then (Response Contract)

Specify expected response object. Response varies based on pre-conditions:

Then status [code]
And response.[field] is [type]
And response.[field] equals [value]
And response.[field] in [array of valid values]
And response does NOT include [sensitive_field]

**Response Schema Template:**

// Success response
{
  data: {
    type: string,
    id: UUID,
    attributes: { ... }
  },
  meta?: { count: number }
}

// Error response
{
  error: {
    code: "NOT_FOUND" | "UNAUTHORIZED" | "VALIDATION_ERROR",
    message: string
  }
}

Phase 5: Write Gherkin Scenarios (G#N)

For each method+path, write scenarios covering all pre-condition combinations:

Feature: [Resource] API

  @G#1
  Scenario: G#1.1 - [Method] [path] - happy path
    Given Authorization header is "Bearer valid_token"
    And [pre-condition 1]
    And [pre-condition 2]
    When [METHOD] [/path]
    Then status 200
    And response.data.id is UUID
    And response.data.attributes.[field] is [type]

  @G#2
  Scenario: G#1.2 - [Method] [path] - missing auth
    Given no Authorization header
    When [METHOD] [/path]
    Then status 401
    And response.error.code equals "UNAUTHORIZED"

  @G#3
  Scenario: G#1.3 - [Method] [path] - not found
    Given Authorization header is "Bearer valid_token"
    And id is "non_existing_uuid"
    When [METHOD] [/path/{id}]
    Then status 404
    And response.error.code equals "NOT_FOUND"

**Numbering Convention:**

• `G#N` = Feature-level ID (G#1, G#2...)
• `G#N.M` = Scenario within feature (G#1.1, G#1.2...)
• Use `@G#N` tag for traceability

**Coverage Matrix per Endpoint:**

| Method | Required Scenarios | |--------|-------------------| | GET (list) | Valid, filtered, paginated, empty, unauthorized | | GET (detail) | Found, not found, deleted, unauthorized, malformed ID | | POST | Valid, each validation error, conflict, unauthorized | | PUT/PATCH | Valid, partial, not found, conflict, unauthorized | | DELETE | Success, not found, unauthorized, cascade |

Phase 6: Build-time Static Scenarios (G#N)

For build-time generated data, write scenarios verifying the build script:

**Pre-conditions for Build Scripts:**

| Parameter | Type | Possible Values