qaa-agent 1.0.0 → 1.2.0

package/workflows/qa-from-ticket.md

@@ -0,0 +1,474 @@
+<purpose>
+Generate test cases and test files from a ticket (GitHub Issue, Jira, Linear, plain text, or file). Extracts acceptance criteria, user stories, and edge cases from the ticket content, scans the dev repo for related source files, generates a traceability matrix mapping acceptance criteria to test cases, then spawns the executor and validator agents to produce and verify test files. Use this workflow to ensure every acceptance criterion has corresponding test coverage before a feature ships.
+</purpose>
+
+<required_reading>
+- `CLAUDE.md` -- QA automation standards, test spec rules, naming conventions, quality gates, testing pyramid
+- `agents/qaa-scanner.md` -- Scanner agent definition (repo scanning for related source files)
+- `agents/qaa-executor.md` -- Executor agent definition (test file generation)
+- `agents/qaa-validator.md` -- Validator agent definition (4-layer validation)
+- `templates/test-inventory.md` -- TEST_INVENTORY.md format contract (test case structure)
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+## Step 1: Parse Ticket Source
+
+Parse `$ARGUMENTS` to determine the ticket source type and content.
+
+**Supported argument formats:**
+
+| Format | Example | Detection |
+|--------|---------|-----------|
+| GitHub Issue URL | `https://github.com/org/repo/issues/123` | Starts with `https://github.com` and contains `/issues/` |
+| GitHub Issue shorthand | `org/repo#123` or `#123` | Contains `#` followed by digits |
+| Jira URL | `https://company.atlassian.net/browse/PROJ-123` | Contains `.atlassian.net/browse/` |
+| Linear URL | `https://linear.app/team/issue/TEAM-123` | Contains `linear.app` |
+| File path | `./tickets/feature-spec.md` | Path exists on disk |
+| Plain text | `"As a user I want to..."` | None of the above patterns match |
+
+**Parsing logic:**
+
+```bash
+TICKET_SOURCE="$ARGUMENTS"
+TICKET_TYPE=""
+TICKET_CONTENT=""
+
+# Detect source type from the argument pattern
+if matches GitHub URL or shorthand:
+  TICKET_TYPE="github"
+elif matches Jira URL:
+  TICKET_TYPE="jira"
+elif matches Linear URL:
+  TICKET_TYPE="linear"
+elif file exists at path:
+  TICKET_TYPE="file"
+else:
+  TICKET_TYPE="text"
+```
+
+**If no arguments provided:**
+
+Print error and STOP:
+```
+Error: No ticket source provided.
+Usage: /qa-from-ticket <source>
+
+Supported sources:
+  GitHub:  https://github.com/org/repo/issues/123  or  #123
+  Jira:    https://company.atlassian.net/browse/PROJ-123
+  Linear:  https://linear.app/team/issue/TEAM-123
+  File:    ./path/to/ticket.md
+  Text:    "As a user I want to log in so that I can access my dashboard"
+```
+</step>
+
+<step name="fetch_ticket_content">
+## Step 2: Fetch Ticket Content
+
+Retrieve the ticket content based on the source type.
+
+**GitHub Issue:**
+
+```bash
+# For full URL: extract owner, repo, issue number
+# For shorthand #123: use current repo context
+gh issue view {issue_number} --repo {owner/repo} --json title,body,labels,assignees,milestone
+```
+
+Extract from JSON response:
+- `title` -- Issue title
+- `body` -- Issue body (markdown)
+- `labels` -- Issue labels (may indicate priority)
+- `milestone` -- Milestone (may indicate release target)
+
+**Jira / Linear URL:**
+
+```bash
+# Use WebFetch to retrieve the ticket page content
+# Extract structured content from the response
+```
+
+If WebFetch fails or authentication is required:
+
+```
+CHECKPOINT:
+type: human-action
+blocking: "Cannot access ticket URL -- authentication required"
+details: "Attempted to fetch: {TICKET_SOURCE}. Received authentication error."
+awaiting: "Provide ticket content as plain text or a file path instead. Or authenticate with the service."
+```
+
+**File path:**
+
+```bash
+# Read the file content directly
+TICKET_CONTENT=$(cat "{TICKET_SOURCE}")
+```
+
+If the file is empty or unreadable, print error: `"Error: Cannot read ticket file: {path}"` and STOP.
+
+**Plain text:**
+
+```bash
+TICKET_CONTENT="${TICKET_SOURCE}"
+```
+
+**Print ticket summary:**
+
+```
+Ticket Source: {TICKET_TYPE}
+Title: {extracted title or first line}
+Content Length: {character count}
+```
+</step>
+
+<step name="extract_acceptance_criteria">
+## Step 3: Extract Acceptance Criteria
+
+Parse the ticket content to identify testable acceptance criteria, user stories, edge cases, and priority.
+
+**Extraction targets:**
+
+| Target | What to Look For | Example |
+|--------|-----------------|---------|
+| Title | Issue title or first heading | "Add password reset flow" |
+| User Story | "As a [role], I want to [action], so that [benefit]" pattern | "As a user, I want to reset my password via email" |
+| Acceptance Criteria | Bullet lists after "Acceptance Criteria", "AC:", "Given/When/Then" patterns | "Given a valid email, When I request reset, Then I receive a reset link" |
+| Edge Cases | Items mentioning: invalid, expired, duplicate, empty, boundary, error, timeout | "Handle expired reset tokens gracefully" |
+| Priority | Labels, priority fields, or keywords: critical, blocker, P0, P1, P2 | "Priority: P0" |
+| Affected Components | File paths, module names, feature areas mentioned | "Auth module", "src/services/auth.service.ts" |
+
+**Structured extraction output:**
+
+```
+TICKET_TITLE: "{title}"
+TICKET_PRIORITY: "{P0|P1|P2}"
+
+ACCEPTANCE_CRITERIA:
+  AC-1: "{criterion text}"
+  AC-2: "{criterion text}"
+  ...
+
+USER_STORIES:
+  US-1: "{story text}"
+  ...
+
+EDGE_CASES:
+  EC-1: "{edge case description}"
+  EC-2: "{edge case description}"
+  ...
+
+KEYWORDS: ["{keyword1}", "{keyword2}", ...]
+```
+
+**If no acceptance criteria can be extracted:**
+
+```
+CHECKPOINT:
+type: human-action
+blocking: "Cannot extract acceptance criteria from ticket"
+details: "Ticket content does not contain recognizable acceptance criteria, Given/When/Then patterns, or bullet-pointed requirements. Raw content: {first 500 chars}"
+awaiting: "Provide acceptance criteria explicitly as a numbered list, or reformat the ticket."
+```
+</step>
+
+<step name="scan_related_source">
+## Step 4: Scan Dev Repo for Related Source Files
+
+Search the dev repo for source files related to the ticket's feature area.
+
+**Search strategy (using keywords from step 3):**
+
+1. **File name search:** Glob for files matching keywords from the ticket
+   - Keywords: module names, feature areas, component names mentioned in the ticket
+   - Patterns: `**/*{keyword}*.*` for each keyword
+
+2. **Content search:** Grep for function names, route paths, class names mentioned in the ticket
+   - Search for acceptance-criteria-related terms: endpoints, function names, component names
+   - Grep patterns: route paths (e.g., `/api/v1/password-reset`), handler names (e.g., `resetPassword`)
+
+3. **Directory search:** Check for feature-organized directories matching the ticket's domain
+   - Directories: `src/services/{feature}*`, `src/controllers/{feature}*`, `src/routes/{feature}*`
+
+**Build related files list:**
+
+```
+RELATED_FILES:
+  - path: "src/services/auth.service.ts"
+    relevance: "Contains resetPassword function referenced in AC-1"
+  - path: "src/routes/auth.routes.ts"
+    relevance: "Contains /api/v1/password-reset endpoint from AC-2"
+  - path: "src/controllers/auth.controller.ts"
+    relevance: "Controller handling password reset requests"
+  ...
+```
+
+**If no related files found:**
+
+Print warning but continue:
+```
+Warning: No source files found matching ticket keywords.
+Keywords searched: {keywords}
+Generating test cases based on ticket content only (no source-level analysis).
+```
+</step>
+
+<step name="generate_test_cases">
+## Step 5: Generate Test Cases with Traceability Matrix
+
+Map each acceptance criterion to one or more test cases, following CLAUDE.md test spec rules.
+
+**Test case generation rules:**
+
+1. **One or more test cases per acceptance criterion** -- Each AC must have at least one test case. Complex ACs may produce multiple test cases (happy path + error cases).
+
+2. **One test case per edge case** -- Each extracted edge case becomes a dedicated test case.
+
+3. **Follow naming convention:**
+   - Unit tests: `UT-{MODULE}-{NNN}` (for logic-level ACs)
+   - API tests: `API-{RESOURCE}-{NNN}` (for endpoint-level ACs)
+   - Integration tests: `INT-{MODULE}-{NNN}` (for cross-module ACs)
+   - E2E tests: `E2E-{FLOW}-{NNN}` (for user-journey ACs)
+
+4. **Follow CLAUDE.md Test Spec Rules:**
+   - Every test case MUST have: unique ID, exact target, concrete inputs, explicit expected outcome, priority
+   - Expected outcomes must be concrete (no "works correctly", "handles properly")
+   - Concrete inputs with actual values (no "valid data")
+
+5. **Pyramid level assignment:**
+   - Pure function or service logic -> Unit test
+   - API endpoint behavior -> API test
+   - Cross-module interaction -> Integration test
+   - Full user journey described in ticket -> E2E test
+
+**Write TEST_CASES_FROM_TICKET.md:**
+
+```markdown
+# Test Cases from Ticket
+
+## Ticket Info
+
+| Field | Value |
+|-------|-------|
+| Source | {TICKET_SOURCE} |
+| Title | {TICKET_TITLE} |
+| Priority | {TICKET_PRIORITY} |
+| Acceptance Criteria | {AC_COUNT} |
+| Edge Cases | {EC_COUNT} |
+| Test Cases Generated | {TOTAL_TEST_CASES} |
+
+## Traceability Matrix
+
+| Acceptance Criterion | Test Case ID | Pyramid Level | Priority |
+|---------------------|--------------|---------------|----------|
+| AC-1: {text} | UT-AUTH-001 | Unit | P0 |
+| AC-1: {text} | API-AUTH-001 | API | P0 |
+| AC-2: {text} | E2E-RESET-001 | E2E | P0 |
+| EC-1: {text} | UT-AUTH-002 | Unit | P1 |
+| ... | ... | ... | ... |
+
+## Test Cases
+
+### Unit Tests
+
+#### UT-{MODULE}-{NNN}: {description}
+
+| Field | Value |
+|-------|-------|
+| test_id | UT-{MODULE}-{NNN} |
+| target | {file_path}:{function_name} |
+| what_to_validate | {behavior description} |
+| concrete_inputs | {actual input values} |
+| mocks_needed | {dependencies to mock or "None (pure function)"} |
+| expected_outcome | {exact return value, error message, or state change} |
+| priority | {P0|P1|P2} |
+| traces_to | AC-{N} or EC-{N} |
+
+[... repeat for all unit tests ...]
+
+### API Tests
+
+[... same structure with API-specific fields ...]
+
+### Integration Tests
+
+[... same structure with integration-specific fields ...]
+
+### E2E Smoke Tests
+
+[... same structure with E2E-specific fields ...]
+```
+
+**Set output directory:**
+
+```bash
+OUTPUT_DIR=".qa-output"
+mkdir -p "${OUTPUT_DIR}"
+```
+
+Write to `{OUTPUT_DIR}/TEST_CASES_FROM_TICKET.md`.
+</step>
+
+<step name="generate_test_files">
+## Step 6: Spawn Executor Agent
+
+Build a synthetic generation plan from the test cases and spawn the executor to write test files.
+
+**Build generation plan:**
+
+Group test cases by feature (from ticket domain) and create task entries following the same structure the executor expects:
+
+```markdown
+# Generation Plan (from ticket)
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total tasks | {N} |
+| Total files | {N} |
+| Feature groups | {N} |
+| Test cases covered | {N} |
+| Framework | {detected from project} |
+| File extension | {ext from project} |
+
+## Tasks
+
+### Task: {feature}-unit
+| Field | Value |
+|-------|-------|
+| task_id | {feature}-unit |
+| feature_group | {feature} |
+| files_to_create | tests/unit/{feature}.unit.spec.{ext} |
+| test_case_ids | UT-{MODULE}-001, UT-{MODULE}-002, ... |
+| depends_on | none |
+| estimated_complexity | {LOW|MEDIUM|HIGH} |
+
+[... additional tasks for API, E2E, POM, fixtures ...]
+```
+
+Write to `{OUTPUT_DIR}/GENERATION_PLAN_TICKET.md`.
+
+**Spawn executor:**
+
+```
+Task(
+  prompt="
+    <objective>Generate test files from ticket-derived test cases</objective>
+    <execution_context>@agents/qaa-executor.md</execution_context>
+    <files_to_read>
+    - {OUTPUT_DIR}/GENERATION_PLAN_TICKET.md
+    - {OUTPUT_DIR}/TEST_CASES_FROM_TICKET.md
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    output_base: {test output directory}
+    </parameters>
+  "
+)
+```
+
+**Handle executor return:**
+
+Extract: `files_created`, `total_files`, `commit_count`, `test_case_count`.
+</step>
+
+<step name="validate_generated_tests">
+## Step 7: Spawn Validator Agent
+
+Validate the generated test files against CLAUDE.md standards.
+
+```
+Task(
+  prompt="
+    <objective>Validate generated test files across 4 layers</objective>
+    <execution_context>@agents/qaa-validator.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - {OUTPUT_DIR}/GENERATION_PLAN_TICKET.md
+    </files_to_read>
+    <parameters>
+    output_path: {OUTPUT_DIR}/VALIDATION_REPORT.md
+    </parameters>
+  "
+)
+```
+
+**Handle validator return:**
+
+Extract: `overall_status`, `confidence`, `issues_found`, `issues_fixed`, `unresolved_count`.
+</step>
+
+<step name="print_summary">
+## Step 8: Print Summary
+
+Print a comprehensive summary showing traceability from ticket to tests.
+
+```
+=== Test Generation from Ticket Complete ===
+
+Ticket: {TICKET_TITLE}
+Source: {TICKET_TYPE} ({TICKET_SOURCE})
+
+Acceptance Criteria Coverage:
+  Total ACs:   {AC_COUNT}
+  Covered:     {COVERED_COUNT}
+  Uncovered:   {UNCOVERED_COUNT}
+
+Edge Cases:
+  Extracted:   {EC_COUNT}
+  With tests:  {EC_TESTED_COUNT}
+
+Test Cases Generated:
+  Unit Tests:        {unit_count}
+  Integration Tests: {integration_count}
+  API Tests:         {api_count}
+  E2E Tests:         {e2e_count}
+  --------------------------
+  Total:             {total_count}
+
+Files Created: {file_count}
+
+Validation:
+  Status:     {PASS|PASS_WITH_WARNINGS|FAIL}
+  Confidence: {HIGH|MEDIUM|LOW}
+
+Artifacts:
+  - {OUTPUT_DIR}/TEST_CASES_FROM_TICKET.md  (traceability matrix)
+  - {OUTPUT_DIR}/GENERATION_PLAN_TICKET.md  (generation plan)
+  - {OUTPUT_DIR}/VALIDATION_REPORT.md       (validation results)
+  - {test file paths...}                    (generated test files)
+===========================================
+```
+</step>
+
+</process>
+
+<output>
+This workflow generates tests mapped 1:1 to ticket acceptance criteria.
+
+**Artifacts produced:**
+
+| Artifact | When Produced | Description |
+|----------|---------------|-------------|
+| TEST_CASES_FROM_TICKET.md | Always | Test cases with traceability matrix mapping ACs to test IDs |
+| GENERATION_PLAN_TICKET.md | Always | Synthetic generation plan for the executor agent |
+| Test files (unit, API, E2E, POM, fixtures) | Always | Actual test code following CLAUDE.md standards |
+| VALIDATION_REPORT.md | Always | 4-layer validation of generated test files |
+
+**Traceability guarantee:** Every acceptance criterion in the ticket maps to at least one test case. The traceability matrix in TEST_CASES_FROM_TICKET.md documents this mapping with `traces_to` fields.
+</output>
+
+<error_handling>
+| Error | Cause | Action |
+|-------|-------|--------|
+| No ticket source provided | Missing argument | Print usage help, STOP |
+| Cannot access ticket URL | Auth required or URL invalid | Checkpoint: ask user for content as text or file |
+| Cannot read ticket file | File does not exist or is empty | Print error with path, STOP |
+| No acceptance criteria found | Ticket lacks structured requirements | Checkpoint: ask user to provide ACs explicitly |
+| No related source files found | Keywords do not match any files | Warning only -- continue with ticket-only analysis |
+| Test framework not detected | No config files in project | Executor checkpoints for user to specify framework |
+| Validation FAIL | Generated tests have quality issues | Report issues in VALIDATION_REPORT.md for review |
+</error_handling>