qa-skills 3.0.0

package/skills/qa-requirements-generator/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: qa-requirements-generator
+description: Extract and normalize requirements from any source (URL, Figma, code, description) into structured specifications per ISO 29148.
+output_dir: docs/requirements
+dependencies:
+  recommended:
+    - qa-discovery-interview
+---
+
+# QA Requirements Generator
+
+## Purpose
+Extract and normalize requirements from any source into structured specification documents following ISO/IEC/IEEE 29148 standards.
+
+## Sub-Modes (Input Sources)
+
+### `from-url`
+Navigate a live application via Playwright MCP, collect user flows, page structure, form fields, navigation paths, and generate requirements from observed behavior.
+
+**Steps:**
+1. Use Playwright MCP to navigate the provided URL
+2. Capture accessibility snapshots of each page
+3. Identify user flows, forms, buttons, navigation elements
+4. Extract validation rules, error messages, API endpoints
+5. Generate requirements from observed functionality
+
+### `from-figma`
+Analyze Figma exports or UI screenshots via vision capabilities.
+
+**Steps:**
+1. Accept image paths (screenshots, Figma exports, mockups)
+2. Analyze UI elements: fields, buttons, tables, modals, forms
+3. Infer functional requirements from visual design
+4. Map user interactions from layout and component relationships
+
+### `from-code`
+Analyze repository structure, components, API routes, models, and database schemas.
+
+**Steps:**
+1. Scan project structure (components, routes, models, services)
+2. Extract API endpoints and their signatures
+3. Identify data models and relationships
+4. Derive requirements from existing implementation
+
+### `from-description`
+Transform text descriptions from PM/developer/stakeholder into structured requirements.
+
+**Steps:**
+1. Parse natural language input
+2. Identify actors, actions, and outcomes
+3. Decompose into atomic requirements
+4. Add acceptance criteria (Given/When/Then)
+
+### `full-audit`
+Combine all sources for comprehensive requirement extraction.
+
+## Output Format
+
+Requirements document following ISO 29148 SRS structure. See `references/iso-29148-structure.md` for full section descriptions.
+
+### Document Structure
+```
+1. Introduction
+   1.1 Purpose
+   1.2 Scope
+   1.3 Definitions
+2. Overall Description
+   2.1 Product Perspective
+   2.2 User Classes and Characteristics
+   2.3 Operating Environment
+3. Functional Requirements
+   [REQ-FN-001] ...
+4. Non-Functional Requirements
+   [REQ-NFR-001] ...
+5. External Interface Requirements
+6. Constraints
+7. Dependencies
+```
+
+### Requirement Format
+Each requirement MUST include:
+- **ID:** `[REQ-{type}-{number}]` (e.g., REQ-FN-001)
+- **Title:** Short descriptive title
+- **Description:** Clear, unambiguous statement
+- **Priority:** Critical / High / Medium / Low
+- **Acceptance Criteria:** Given/When/Then format
+- **Source:** URL / Figma / Code / Description
+- **Dependencies:** Links to related requirements
+- **Status:** Draft / Reviewed / Approved
+
+### User Story Format
+```
+As a [user role]
+I want to [action]
+So that [benefit]
+
+Acceptance Criteria:
+Given [precondition]
+When [action]
+Then [expected outcome]
+```
+
+## Scope
+
+**Can do (autonomous):**
+- Generate requirements from any supported input source
+- Create user stories with acceptance criteria
+- Assign requirement IDs and priorities
+- Build dependency graphs between requirements
+- Call qa-diagram-generator for flow diagrams
+
+**Cannot do (requires confirmation):**
+- Modify existing approved requirements
+- Change requirement priorities set by stakeholders
+- Delete requirements from registry
+
+**Will not do (out of scope):**
+- Implement features described in requirements
+- Deploy or modify production systems
+- Make business decisions about scope
+
+## MCP Tools Used
+- **Playwright MCP:** For `from-url` mode (navigate, screenshot, accessibility snapshot)
+- **Sequential Thinking MCP:** For complex requirement decomposition
+- **Filesystem MCP:** For reading codebase in `from-code` mode
+
+## Embedding: Diagram Generator
+When visualization is needed, reference qa-diagram-generator:
+- User flows → `references/flowchart.md`
+- API interactions → `references/sequence.md`
+- Data models → `references/er-diagram.md`
+
+## Requirement Patterns
+See `references/requirement-patterns.md` for templates: CRUD, auth, search/filter, notifications, file upload, pagination, error handling.
+
+## Quality Checklist
+- [ ] Every requirement has a unique ID
+- [ ] No ambiguous language (avoid: "should", "may", "might")
+- [ ] All requirements are testable (measurable acceptance criteria)
+- [ ] Dependencies are explicitly linked
+- [ ] Priority is assigned based on business value
+- [ ] Traceability links to source material
+- [ ] No duplicate or conflicting requirements
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| Empty requirements from URL | Page requires authentication | Provide login credentials, use Playwright to authenticate first |
+| Vague requirements generated | Input description too brief | Ask for more detail, use multiple sub-modes |
+| Missing non-functional requirements | Only functional analysis done | Run qa-nfr-analyst separately or use full-audit mode |
+| Duplicate requirements | Multiple sources overlap | Run deduplication pass, merge by intent |

package/skills/qa-requirements-generator/references/iso-29148-structure.md

@@ -0,0 +1,153 @@
+# ISO/IEC/IEEE 29148 SRS Structure Reference
+
+ISO/IEC/IEEE 29148 defines the structure and content of Software Requirements Specifications (SRS). Use this reference when generating requirements documents.
+
+## Document Sections
+
+### 1. Introduction
+
+#### 1.1 Purpose
+Identifies the product and describes the purpose of the SRS document.
+
+**Example:**
+> This Software Requirements Specification defines the functional and non-functional requirements for the Customer Portal application. It serves as the authoritative source for development, testing, and validation activities.
+
+#### 1.2 Scope
+Describes the product scope, major functions, and exclusions.
+
+**Example:**
+> The Customer Portal enables authenticated users to manage their profile, view order history, and submit support tickets. Out of scope: payment processing (handled by external gateway), mobile native apps.
+
+#### 1.3 Definitions, Acronyms, and Abbreviations
+Glossary of terms used in the document.
+
+**Example:**
+> - **User:** An authenticated individual with access to the system
+> - **Session:** A period of authenticated interaction bounded by login and logout
+> - **API:** Application Programming Interface
+
+---
+
+### 2. Overall Description
+
+#### 2.1 Product Perspective
+Describes the product in context: interfaces to other systems, hardware, software, users.
+
+**Example:**
+> The Customer Portal integrates with the Order Management System (OMS) via REST API, authenticates against Microsoft Entra ID, and runs in a containerized environment on Azure.
+
+#### 2.2 User Classes and Characteristics
+Identifies user roles and their characteristics.
+
+**Example:**
+> - **End User:** General customer; requires simple, guided workflows
+> - **Support Agent:** Internal staff; requires bulk operations and search
+> - **Administrator:** System config; requires audit trails and role management
+
+#### 2.3 Operating Environment
+Hardware, software, and network constraints.
+
+**Example:**
+> - Browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
+> - Resolution: 1280×720 minimum
+> - Network: HTTPS required; offline mode not supported
+
+---
+
+### 3. Functional Requirements
+
+Each requirement follows the format:
+
+```
+[REQ-FN-XXX] Title
+Description: [Clear, unambiguous statement]
+Priority: Critical | High | Medium | Low
+Acceptance Criteria:
+  Given [precondition]
+  When [action]
+  Then [expected outcome]
+Source: [URL | Figma | Code | Description]
+Dependencies: [REQ-FN-YYY, ...]
+Status: Draft | Reviewed | Approved
+```
+
+**Numbering:** Use sequential numbering (001, 002, ...) within each type.
+
+---
+
+### 4. Non-Functional Requirements
+
+Categories per ISO 25010:
+
+| Category | Examples |
+|----------|----------|
+| Performance | Response time, throughput, resource usage |
+| Security | Authentication, authorization, data protection |
+| Usability | Learnability, accessibility (WCAG) |
+| Reliability | Availability, fault tolerance |
+| Maintainability | Modularity, testability |
+| Portability | Platform independence |
+
+**Format:** `[REQ-NFR-XXX]` with same structure as functional requirements.
+
+---
+
+### 5. External Interface Requirements
+
+#### 5.1 User Interfaces
+Screens, layouts, interaction patterns.
+
+#### 5.2 Hardware Interfaces
+Devices, sensors, peripherals.
+
+#### 5.3 Software Interfaces
+APIs, databases, third-party services.
+
+#### 5.4 Communication Interfaces
+Protocols, formats, ports.
+
+---
+
+### 6. Constraints
+
+Regulatory, technical, or business constraints.
+
+**Example:**
+> - GDPR: Personal data must be deletable within 30 days of request
+> - PCI-DSS: No storage of full card numbers
+> - Must support RTL languages for future localization
+
+---
+
+### 7. Dependencies
+
+External systems, libraries, or conditions the product depends on.
+
+**Example:**
+> - OMS API v2.1 or later
+> - Entra ID tenant configuration
+> - CDN for static assets
+
+---
+
+## Requirement Quality Attributes (ISO 29148)
+
+| Attribute | Description |
+|-----------|-------------|
+| Complete | No missing information |
+| Correct | Accurately reflects stakeholder needs |
+| Unambiguous | Single interpretation |
+| Verifiable | Can be tested or demonstrated |
+| Consistent | No conflicts with other requirements |
+| Traceable | Links to source and downstream artifacts |
+| Modifiable | Structured for change management |
+
+---
+
+## Requirement Writing Rules
+
+1. **Use "shall"** for mandatory requirements (not "should", "may", "might")
+2. **One requirement per statement** — avoid compound sentences
+3. **Avoid vague terms** — "user-friendly", "fast", "robust" need quantification
+4. **Include measurable criteria** — "within 2 seconds", "99.9% uptime"
+5. **Link to source** — traceability for each requirement

package/skills/qa-requirements-generator/references/requirement-patterns.md

@@ -0,0 +1,278 @@
+# Common Requirement Patterns
+
+Reusable requirement templates for recurring functionality. Adapt IDs, entity names, and specifics to the project.
+
+---
+
+## CRUD Operations
+
+### Create
+
+```
+[REQ-FN-XXX] Create [Entity]
+Description: The system shall allow [user role] to create a new [entity] by providing [required fields].
+Priority: High
+Acceptance Criteria:
+  Given [user] is authenticated with [create] permission
+  When [user] submits the [entity] form with valid [fields]
+  Then the system shall persist the [entity] and return a confirmation
+  And the system shall assign a unique identifier to the new [entity]
+  And the system shall validate [field] according to [rules]
+Source: [Code | Description]
+Dependencies: [REQ-FN-AUTH]
+Status: Draft
+```
+
+### Read (Single)
+
+```
+[REQ-FN-XXX] View [Entity] Details
+Description: The system shall allow [user role] to view details of an existing [entity] by [entity] ID.
+Priority: High
+Acceptance Criteria:
+  Given [user] is authenticated and has access to [entity]
+  When [user] requests [entity] with ID [id]
+  Then the system shall return [entity] details if authorized
+  And the system shall return 404 if [entity] does not exist
+  And the system shall return 403 if [user] lacks permission
+Source: [Code | Description]
+Dependencies: [REQ-FN-AUTH]
+Status: Draft
+```
+
+### Update
+
+```
+[REQ-FN-XXX] Update [Entity]
+Description: The system shall allow [user role] to update an existing [entity] by modifying [editable fields].
+Priority: High
+Acceptance Criteria:
+  Given [user] is authenticated with [update] permission
+  When [user] submits changes to [entity] [id]
+  Then the system shall validate and persist the changes
+  And the system shall preserve [immutable fields]
+  And the system shall record the modification timestamp and actor
+Source: [Code | Description]
+Dependencies: [REQ-FN-READ]
+Status: Draft
+```
+
+### Delete
+
+```
+[REQ-FN-XXX] Delete [Entity]
+Description: The system shall allow [user role] to delete an [entity] when [conditions].
+Priority: Medium
+Acceptance Criteria:
+  Given [user] is authenticated with [delete] permission
+  When [user] requests deletion of [entity] [id]
+  Then the system shall perform [soft|hard] delete
+  And the system shall [cascade|prevent] deletion if [entity] has [dependencies]
+  And the system shall require confirmation for [destructive] operations
+Source: [Code | Description]
+Dependencies: [REQ-FN-READ]
+Status: Draft
+```
+
+---
+
+## Authentication / Authorization
+
+### Login
+
+```
+[REQ-FN-XXX] User Login
+Description: The system shall authenticate users via [method: password | SSO | MFA].
+Priority: Critical
+Acceptance Criteria:
+  Given a user with valid credentials
+  When the user submits login credentials
+  Then the system shall validate credentials against [identity provider]
+  And the system shall create a session with [token type] valid for [duration]
+  And the system shall return an error for invalid credentials without revealing which field failed
+  And the system shall enforce [lockout policy] after [N] failed attempts
+Source: [Code | Description]
+Dependencies: []
+Status: Draft
+```
+
+### Logout
+
+```
+[REQ-FN-XXX] User Logout
+Description: The system shall allow authenticated users to terminate their session.
+Priority: High
+Acceptance Criteria:
+  Given an authenticated user
+  When the user initiates logout
+  Then the system shall invalidate the session/token
+  And the system shall redirect the user to [login | home] page
+  And the system shall clear client-side session data
+Source: [Code | Description]
+Dependencies: [REQ-FN-LOGIN]
+Status: Draft
+```
+
+### Role-Based Access
+
+```
+[REQ-FN-XXX] Role-Based Access Control
+Description: The system shall enforce access to [resources] based on user roles [list roles].
+Priority: Critical
+Acceptance Criteria:
+  Given a user with role [R]
+  When the user attempts to [action] on [resource]
+  Then the system shall allow the action if role [R] has permission
+  And the system shall return 403 Forbidden if permission is denied
+  And the system shall not expose [resource] existence when access is denied [if applicable]
+Source: [Code | Description]
+Dependencies: [REQ-FN-LOGIN]
+Status: Draft
+```
+
+---
+
+## Search / Filter
+
+```
+[REQ-FN-XXX] Search [Entities]
+Description: The system shall allow users to search [entities] by [searchable fields].
+Priority: High
+Acceptance Criteria:
+  Given [user] is authenticated
+  When [user] enters search criteria [fields] and submits
+  Then the system shall return [entities] matching [matching logic: exact | partial | fuzzy]
+  And the system shall support [AND | OR] combination of criteria
+  And the system shall return results within [time] for [volume]
+  And the system shall support [pagination | infinite scroll]
+Source: [Code | Description]
+Dependencies: [REQ-FN-READ-LIST]
+Status: Draft
+```
+
+```
+[REQ-FN-XXX] Filter [Entities] List
+Description: The system shall allow users to filter [entities] by [filterable attributes].
+Priority: Medium
+Acceptance Criteria:
+  Given a list of [entities]
+  When [user] applies filters [filter1, filter2, ...]
+  Then the system shall return only [entities] matching all active filters
+  And the system shall support [single | multi] select per filter
+  And the system shall persist filter state in [URL | session] for shareability
+Source: [Code | Description]
+Dependencies: [REQ-FN-READ-LIST]
+Status: Draft
+```
+
+---
+
+## Notifications
+
+```
+[REQ-FN-XXX] In-App Notifications
+Description: The system shall display notifications to users for [events].
+Priority: Medium
+Acceptance Criteria:
+  Given [user] is authenticated and [event] occurs
+  When the event is relevant to the user
+  Then the system shall create a notification visible in [notification center | bell icon]
+  And the system shall mark notifications as read when [user views | user dismisses]
+  And the system shall support [real-time | polled] delivery
+Source: [Code | Description]
+Dependencies: [REQ-FN-LOGIN]
+Status: Draft
+```
+
+```
+[REQ-FN-XXX] Email Notifications
+Description: The system shall send email notifications for [events] to [recipients].
+Priority: Medium
+Acceptance Criteria:
+  Given [event] occurs
+  When the event triggers an email (e.g., [welcome, password reset, order confirmation])
+  Then the system shall send an email to [recipient] within [time]
+  And the system shall include [required content]
+  And the system shall respect user notification preferences
+  And the system shall use [template] with [personalization]
+Source: [Code | Description]
+Dependencies: []
+Status: Draft
+```
+
+---
+
+## File Upload
+
+```
+[REQ-FN-XXX] File Upload
+Description: The system shall allow [user role] to upload files for [purpose].
+Priority: High
+Acceptance Criteria:
+  Given [user] is authenticated
+  When [user] selects a file for upload
+  Then the system shall accept files of type [MIME types] up to [size] MB
+  And the system shall validate [virus scan | content check] before persisting
+  And the system shall store the file in [storage] and record metadata
+  And the system shall return [progress | success | error] feedback
+  And the system shall reject files exceeding size or type limits with a clear message
+Source: [Code | Description]
+Dependencies: [REQ-FN-AUTH]
+Status: Draft
+```
+
+---
+
+## Pagination
+
+```
+[REQ-FN-XXX] Paginated List
+Description: The system shall paginate [entity] lists with configurable page size.
+Priority: Medium
+Acceptance Criteria:
+  Given a list of [entities] with [N] total items
+  When [user] requests page [P] with size [S]
+  Then the system shall return items [(P-1)*S] through [P*S - 1]
+  And the system shall include metadata: total count, page number, page size, hasNext, hasPrev
+  And the system shall support page sizes [10, 25, 50, 100]
+  And the system shall default to page size [25]
+Source: [Code | Description]
+Dependencies: [REQ-FN-READ-LIST]
+Status: Draft
+```
+
+---
+
+## Error Handling
+
+```
+[REQ-FN-XXX] User-Facing Error Messages
+Description: The system shall display clear, actionable error messages for [error types].
+Priority: High
+Acceptance Criteria:
+  Given an error occurs during [operation]
+  When the error is user-facing
+  Then the system shall display a message that [describes the problem | suggests next steps]
+  And the system shall avoid exposing [internal details | stack traces]
+  And the system shall use [localization] for error text
+  And the system shall log full error details server-side for debugging
+Source: [Code | Description]
+Dependencies: []
+Status: Draft
+```
+
+```
+[REQ-FN-XXX] Validation Error Feedback
+Description: The system shall provide field-level validation feedback for form submissions.
+Priority: High
+Acceptance Criteria:
+  Given [user] submits a form with invalid data
+  When validation fails for [field(s)]
+  Then the system shall highlight invalid fields and display error messages
+  And the system shall prevent submission until all errors are resolved
+  And the system shall support [client-side | server-side | both] validation
+  And the system shall show errors [inline | summary | both]
+Source: [Code | Description]
+Dependencies: []
+Status: Draft
+```