qa-skills 3.0.0

package/skills/qa-spec-writer/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: qa-spec-writer
+description: Transform requirements into detailed technical specifications with acceptance criteria, boundary conditions, and edge cases.
+output_dir: docs/specs
+dependencies:
+  recommended:
+    - qa-requirements-generator
+---
+
+# QA Spec Writer
+
+## Purpose
+
+Create detailed technical specifications from requirements documents. Transform high-level requirements into test-ready specifications with acceptance criteria, boundary conditions, edge cases, and business rules.
+
+## Trigger Phrases
+
+- "Write technical spec from requirements" / "Create spec from [requirements doc]"
+- "Transform requirements into specifications"
+- "Add acceptance criteria to [feature/spec]"
+- "Define boundary conditions and edge cases"
+- "Technical specification with Given/When/Then"
+- "Spec with error handling and validation rules"
+- "Decompose requirement into spec" / "State transitions for [feature]"
+
+## Workflow
+
+1. **Input:** Read requirements document (from qa-requirements-generator or manual)
+2. **Analysis:** Decompose each requirement into specification elements
+3. **Specification:** Write detailed technical spec with:
+   - Functional behavior descriptions
+   - Input/output specifications
+   - Boundary conditions and edge cases
+   - Error handling and validation rules
+   - Business rules and constraints
+   - State transitions
+4. **Acceptance Criteria:** Formalize in Given/When/Then (Gherkin) format
+5. **Output:** Technical specification document per ISO 29148
+
+## Specification Structure
+
+For each feature/module:
+
+### Functional Specification
+```
+[SPEC-{module}-{number}]
+Title: {Feature Name}
+Requirement: [REQ-FN-xxx]
+
+Description:
+  Detailed technical behavior description
+
+Input Specifications:
+  | Field | Type | Required | Validation | Default |
+  | ----- | ---- | -------- | ---------- | ------- |
+
+Output Specifications:
+  | Condition | Output | Status Code |
+  | --------- | ------ | ----------- |
+
+Boundary Conditions:
+  - Min/max values
+  - Empty/null inputs
+  - Character limits
+
+Edge Cases:
+  - Concurrent access
+  - Network timeout
+  - Partial data
+
+Error Handling:
+  | Error Condition | Error Code | User Message | Recovery |
+  | --------------- | ---------- | ------------ | -------- |
+
+Business Rules:
+  - BR-001: {rule description}
+
+State Transitions:
+  {state diagram reference}
+```
+
+### Acceptance Criteria Template
+```gherkin
+Feature: {Feature Name}
+
+  Scenario: {Happy Path}
+    Given {precondition}
+    When {action}
+    Then {expected outcome}
+
+  Scenario: {Negative Case}
+    Given {precondition}
+    When {invalid action}
+    Then {error handling}
+
+  Scenario: {Boundary}
+    Given {precondition}
+    When {boundary input}
+    Then {boundary behavior}
+```
+
+## Scope
+
+**Can do (autonomous):**
+- Generate specs from requirements documents
+- Define acceptance criteria in Gherkin format
+- Identify boundary conditions and edge cases
+- Document error handling scenarios
+- Call qa-diagram-generator for state/sequence diagrams
+
+**Cannot do (requires confirmation):**
+- Change requirement scope or priority
+- Make architectural decisions
+- Define new business rules not in requirements
+
+**Will not do (out of scope):**
+- Write test code
+- Modify production code
+- Deploy systems
+
+## Embedding: Diagram Generator
+When visualization is needed, reference qa-diagram-generator:
+- State machines → `references/state-diagram.md`
+- API flows → `references/sequence.md`
+- Decision logic → `references/flowchart.md`
+
+## Quality Checklist
+- [ ] Every spec traces to a requirement ID
+- [ ] All inputs have validation rules defined
+- [ ] Boundary conditions identified for numeric/string fields
+- [ ] Negative scenarios documented
+- [ ] Error handling specified for each failure mode
+- [ ] Acceptance criteria are in Given/When/Then format
+- [ ] No implementation details leaked into specs
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| Specs too vague | Requirements lack detail | Run qa-requirements-generator first |
+| Missing edge cases | Only happy path analyzed | Use systematic techniques: EP, BVA, decision tables |
+| Acceptance criteria not testable | Using subjective language | Replace with measurable criteria |
+| Specs conflict with each other | Requirements have contradictions | Flag for stakeholder resolution |

package/skills/qa-spec-writer/references/gherkin-guide.md

@@ -0,0 +1,253 @@
+# Gherkin Syntax Guide
+
+Gherkin is a Business Readable, Domain Specific Language for behavior descriptions. It uses keywords to structure scenarios in Given/When/Then format.
+
+---
+
+## Core Keywords
+
+| Keyword | Purpose |
+| ------- | ------- |
+| `Feature` | High-level description of a capability |
+| `Scenario` | Concrete example of behavior |
+| `Scenario Outline` | Template for data-driven scenarios |
+| `Given` | Precondition / initial context |
+| `When` | Action / event |
+| `Then` | Expected outcome / observable result |
+| `And` | Continuation of previous step (Given/When/Then) |
+| `But` | Contrast to previous step |
+| `Background` | Steps run before every scenario in the feature |
+| `Examples` | Data table for Scenario Outline |
+
+---
+
+## Happy Path Scenarios
+
+Describe the primary success flow with clear preconditions and outcomes.
+
+```gherkin
+Feature: User Registration
+
+  Scenario: New user successfully registers
+    Given the user is on the registration page
+    And no account exists for "user@example.com"
+    When the user enters valid registration details
+    And the user submits the form
+    Then the account is created
+    And a confirmation email is sent
+    And the user is redirected to the dashboard
+```
+
+**Guidelines:**
+- One primary action in `When`
+- Outcomes should be observable and verifiable
+- Avoid implementation details (e.g., "clicks the Submit button" vs "submits the form")
+
+---
+
+## Negative Scenarios
+
+Describe invalid inputs, unauthorized access, or error conditions.
+
+```gherkin
+Feature: User Login
+
+  Scenario: Login fails with invalid password
+    Given a user account exists with email "user@example.com"
+    When the user enters email "user@example.com" and wrong password
+    And the user submits the login form
+    Then the user remains on the login page
+    And "Invalid email or password" is displayed
+    And the failed attempt is logged
+
+  Scenario: Login fails when account is locked
+    Given the user account is locked due to 5 failed attempts
+    When the user attempts to login with correct credentials
+    Then "Account locked. Try again in 15 minutes" is displayed
+    And the user cannot log in
+```
+
+**Guidelines:**
+- Specify the exact error message or behavior
+- Include security considerations (e.g., generic messages to avoid enumeration)
+- Document recovery path if applicable
+
+---
+
+## Boundary Scenarios
+
+Test limits: min, max, empty, null, and transition points.
+
+```gherkin
+Feature: Product Search
+
+  Scenario: Search with empty query returns all products
+    Given the catalog has 100 products
+    When the user searches with an empty query
+    Then all 100 products are returned
+    And results are paginated with 20 per page
+
+  Scenario: Search with maximum length query
+    Given the search supports up to 200 characters
+    When the user searches with a 200-character query
+    Then the search executes successfully
+    And results matching the query are returned
+
+  Scenario: Pagination at last page
+    Given there are 45 products (3 pages of 20)
+    When the user navigates to page 3
+    Then 5 products are displayed
+    And "Page 3 of 3" is shown
+    And the "Next" button is disabled
+```
+
+**Guidelines:**
+- Use exact boundary values (0, 1, max, max+1)
+- Specify behavior for empty and null explicitly
+- Include off-by-one cases (e.g., last page)
+
+---
+
+## Data-Driven Scenarios (Scenario Outline)
+
+Use `Scenario Outline` with `Examples` to run the same scenario with different data.
+
+```gherkin
+Feature: Password Validation
+
+  Scenario Outline: Password fails validation rules
+    Given the user is on the registration form
+    When the user enters password "<password>"
+    And the user submits the form
+    Then "Password must <rule>" is displayed
+    And the form is not submitted
+
+    Examples:
+      | password   | rule                          |
+      | short      | be at least 8 characters      |
+      | noNumbers1 | contain at least one number   |
+      | NOUPPERCASE| contain at least one uppercase|
+      | nolower1   | contain at least one lowercase|
+```
+
+**Guidelines:**
+- Use `<placeholder>` in steps, define in Examples table
+- One scenario outline per logical variation
+- Keep Examples readable; split into multiple outlines if needed
+
+---
+
+## Background
+
+Use `Background` for steps shared by all scenarios in the feature.
+
+```gherkin
+Feature: Shopping Cart
+
+  Background:
+    Given the user is logged in
+    And the user has an empty cart
+
+  Scenario: Add item to cart
+    When the user adds "Widget A" to the cart
+    Then the cart contains 1 item
+    And "Widget A" is in the cart
+
+  Scenario: Remove item from cart
+    Given the cart contains "Widget A"
+    When the user removes "Widget A" from the cart
+    Then the cart is empty
+```
+
+**Guidelines:**
+- Keep Background short (2–4 steps)
+- Use for setup, not for scenario-specific context
+- If Background grows large, consider a separate feature or hooks
+
+---
+
+## Step Best Practices
+
+### Do
+- Use third person: "the user", "the system"
+- Make steps declarative: "the cart contains 2 items" vs "the user added 2 items"
+- One concept per step
+- Use domain language, not UI language
+- Make outcomes verifiable: "is displayed", "returns 200", "is saved"
+
+### Don't
+- Don't use "should" or "would" — use definitive "is", "returns", "displays"
+- Don't chain multiple actions in one step
+- Don't reference implementation (clicks, API calls) unless the feature is about that
+- Don't use subjective criteria: "user-friendly" → "displays within 2 seconds"
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+| ----------- | ------- | --- |
+| Imperative steps | "Click Submit, then click Confirm" | "Submits the form", "Confirms the action" |
+| Vague outcomes | "Then it works" | "Then the order status is 'confirmed'" |
+| Implementation details | "Then the database has a new row" | "Then the order appears in order history" |
+| Too many steps | 15+ steps per scenario | Split into smaller scenarios |
+| Duplicate scenarios | Same scenario, different feature | Use tags or Background |
+| Test data in steps | "user with id 12345" | "a user", use tables for specific data |
+
+---
+
+## Tags (Optional)
+
+Use tags for filtering and organization:
+
+```gherkin
+@smoke @critical
+Scenario: User can login
+
+@regression @slow
+Scenario: Bulk import 10000 records
+
+@wip
+Scenario: New checkout flow (in progress)
+```
+
+---
+
+## Full Example
+
+```gherkin
+Feature: Order Placement
+  As a customer
+  I want to place an order
+  So that I can purchase products
+
+  Background:
+    Given the user is logged in
+    And the user has items in the cart
+
+  Scenario: Successful order placement
+    Given the user has a valid shipping address
+    And the user has a valid payment method
+    When the user completes checkout
+    Then the order is created with status "pending"
+    And a confirmation email is sent
+    And the cart is emptied
+
+  Scenario: Order fails with invalid payment
+    Given the user has an expired payment method
+    When the user attempts checkout
+    Then "Payment failed" is displayed
+    And the order is not created
+    And the cart retains the items
+
+  Scenario Outline: Order respects quantity limits
+    Given the product "<product>" has max quantity <max>
+    When the user sets quantity to <quantity>
+    Then <result>
+
+    Examples:
+      | product | max | quantity | result                    |
+      | Widget  | 10  | 5        | quantity is accepted      |
+      | Widget  | 10  | 10       | quantity is accepted      |
+      | Widget  | 10  | 11       | "Max 10 per order" shown  |
+```

package/skills/qa-spec-writer/references/specification-patterns.md

@@ -0,0 +1,274 @@
+# Specification Patterns
+
+Common specification patterns for recurring feature types. Use these as templates when writing specs.
+
+---
+
+## Forms
+
+### Input Specification Pattern
+| Field | Type | Required | Validation | Default |
+| ----- | ---- | -------- | ---------- | ------- |
+| email | string | Yes | RFC 5322, max 254 chars | — |
+| password | string | Yes | Min 8, max 128, complexity rules | — |
+| phone | string | No | E.164 format if provided | null |
+
+### Boundary Conditions
+- Empty required fields → validation error before submit
+- Max length exceeded → truncation or error (specify which)
+- Special characters in text fields → escape/sanitize rules
+- Unicode/emoji support → define allowed character set
+
+### Error Handling
+| Condition | Behavior |
+| --------- | -------- |
+| Client-side validation fails | Inline message, prevent submit |
+| Server-side validation fails | 400, field-level error map |
+| Duplicate submission | Idempotency key or disable button |
+| Session expired during submit | 401, redirect to login |
+
+### Acceptance Criteria Pattern
+```gherkin
+Scenario: Valid form submission
+  Given the user has filled all required fields correctly
+  When the user submits the form
+  Then the form data is saved
+  And a success message is displayed
+  And the user is redirected to the confirmation page
+
+Scenario: Required field validation
+  Given the user is on the registration form
+  When the user leaves "email" empty and submits
+  Then "Email is required" is displayed
+  And the form is not submitted
+```
+
+---
+
+## APIs
+
+### Request/Response Specification
+| Method | Path | Auth | Request Body | Response |
+| ------ | ---- | ---- | ------------ | -------- |
+| POST | /api/v1/orders | Bearer | OrderCreateDto | 201 + Order |
+| GET | /api/v1/orders/{id} | Bearer | — | 200 + Order or 404 |
+
+### Input Specifications
+- Path params: type, format (UUID, slug), validation
+- Query params: type, allowed values, pagination (page, limit, max)
+- Headers: Content-Type, Authorization, idempotency-key
+- Body: schema reference, required vs optional
+
+### Boundary Conditions
+- Pagination: page=0, page=-1, limit=0, limit=10000
+- Empty collections vs null
+- Optional fields: omit vs null vs empty string
+- Content-Length limits
+
+### Error Handling
+| Status | Condition | Response Body |
+| ------ | --------- | ------------- |
+| 400 | Validation error | `{ "errors": [{ "field": "...", "message": "..." }] }` |
+| 401 | Missing/invalid token | `{ "error": "unauthorized" }` |
+| 404 | Resource not found | `{ "error": "not_found", "id": "..." }` |
+| 409 | Conflict (e.g., duplicate) | `{ "error": "conflict", "details": "..." }` |
+| 429 | Rate limit exceeded | Retry-After header, error body |
+
+### Acceptance Criteria Pattern
+```gherkin
+Scenario: Successful API call
+  Given a valid authentication token
+  And the resource exists
+  When the client sends a GET request to "/api/v1/orders/123"
+  Then the response status is 200
+  And the response body contains the order JSON
+
+Scenario: Unauthorized access
+  Given no authentication token
+  When the client sends a GET request to "/api/v1/orders/123"
+  Then the response status is 401
+  And the response body contains an error message
+```
+
+---
+
+## Search & Filter
+
+### Input Specification
+| Parameter | Type | Required | Validation | Default |
+| --------- | ---- | -------- | ---------- | ------- |
+| q | string | No | Max 200 chars, sanitize | "" |
+| category | enum | No | From allowed list | all |
+| sort | enum | No | field:asc\|desc | relevance |
+| page | integer | No | Min 1, max 100 | 1 |
+| limit | integer | No | Min 1, max 50 | 20 |
+
+### Boundary Conditions
+- Empty search query → return all or require non-empty (specify)
+- Invalid filter value → ignore or 400
+- No results → empty array, not null
+- Sort by non-indexed field → define performance expectations
+
+### Edge Cases
+- SQL injection / NoSQL injection in search terms
+- Very long search strings
+- Special regex characters in query
+- Unicode search (collation rules)
+- Concurrent index updates during search
+
+### Acceptance Criteria Pattern
+```gherkin
+Scenario: Search with results
+  Given the index contains matching items
+  When the user searches for "laptop"
+  Then results matching "laptop" are returned
+  And results are ordered by relevance
+  And pagination metadata is included
+
+Scenario: Search with no results
+  Given the index has no matching items
+  When the user searches for "xyznonexistent"
+  Then an empty array is returned
+  And total count is 0
+```
+
+---
+
+## Authentication
+
+### Flow Specification
+1. Login: credentials → token + refresh token
+2. Token refresh: refresh token → new access token
+3. Logout: invalidate tokens (server-side)
+4. Password reset: request → email link → new password
+
+### Input Specifications
+| Field | Validation |
+| ----- | ---------- |
+| username/email | Required, format |
+| password | Required, min length |
+| refresh_token | JWT format, not expired |
+| new_password | Complexity rules, not same as current |
+
+### Boundary Conditions
+- Lockout after N failed attempts
+- Token expiry (access vs refresh)
+- Concurrent sessions (allow or deny)
+- Password history (prevent reuse of last N)
+
+### Error Handling
+| Condition | Response |
+| --------- | -------- |
+| Invalid credentials | 401, generic message (no user enumeration) |
+| Account locked | 423, lockout duration |
+| Token expired | 401, use refresh token |
+| Refresh token expired | 401, re-login required |
+
+### Acceptance Criteria Pattern
+```gherkin
+Scenario: Successful login
+  Given valid credentials exist
+  When the user submits valid credentials
+  Then an access token is returned
+  And a refresh token is returned
+  And tokens are stored securely
+
+Scenario: Account lockout
+  Given the user has 4 failed login attempts
+  When the user attempts to login again with wrong password
+  Then the account is locked for 15 minutes
+  And "Account temporarily locked" is displayed
+```
+
+---
+
+## File Operations
+
+### Input Specification
+| Parameter | Type | Validation |
+| --------- | ---- | ---------- |
+| file | binary | Max size, allowed MIME types |
+| filename | string | Max length, allowed chars, extension |
+| overwrite | boolean | Default false |
+
+### Boundary Conditions
+- File size: 0 bytes, exactly max, over max
+- Filename: empty, path traversal (../), reserved names
+- Concurrent upload of same filename
+- Disk full during write
+- Partial upload (chunked) interruption
+
+### Error Handling
+| Condition | Behavior |
+| --------- | -------- |
+| File too large | 413, clear message with max size |
+| Invalid file type | 400, list allowed types |
+| Filename invalid | 400, sanitization rules |
+| Storage unavailable | 503, retry guidance |
+| Virus detected | 400, quarantine (if applicable) |
+
+### Acceptance Criteria Pattern
+```gherkin
+Scenario: Successful file upload
+  Given the user has selected a valid file under 10MB
+  When the user uploads the file
+  Then the file is stored with a unique ID
+  And the file metadata is returned
+  And the file is accessible at the returned URL
+
+Scenario: File size exceeded
+  Given the user has selected a file larger than 10MB
+  When the user attempts to upload
+  Then an error "File must be under 10MB" is displayed
+  And the file is not stored
+```
+
+---
+
+## Notifications
+
+### Channel Specification
+| Channel | Input | Delivery | Retry |
+| ------- | ----- | -------- | ----- |
+| Email | to, subject, body, attachments | Async | 3 attempts, exponential backoff |
+| SMS | to, message (160 chars) | Async | 2 attempts |
+| Push | device_token, payload | Async | 1 attempt |
+| In-app | user_id, message, link | Sync | N/A |
+
+### Boundary Conditions
+- Empty recipient list
+- Invalid email/phone format
+- Message length limits (SMS 160, push payload size)
+- Rate limiting per user/channel
+- Unsubscribe / opt-out handling
+
+### Edge Cases
+- Duplicate notifications (idempotency)
+- User opts out mid-send
+- Provider (email/SMS) returns temporary failure
+- Notification preferences (do not disturb, channel off)
+
+### Error Handling
+| Condition | Behavior |
+| --------- | -------- |
+| Invalid recipient | Skip, log, continue with others |
+| Provider down | Queue, retry later |
+| User unsubscribed | Do not send, update preference |
+| Rate limit hit | Queue for next window |
+
+### Acceptance Criteria Pattern
+```gherkin
+Scenario: Email notification sent
+  Given the user has enabled email notifications
+  And an event triggers a notification
+  When the notification is processed
+  Then an email is queued for delivery
+  And the email contains the correct content
+  And the notification is marked as sent
+
+Scenario: User opted out
+  Given the user has disabled email notifications
+  When an event triggers an email notification
+  Then no email is sent
+  And the notification is marked as skipped
+```