create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/tasks/qa-fix-issues.md

@@ -0,0 +1,692 @@
+# QA Issue Fixer Task
+
+> **Phase:** QA Fix Loop
+> **Owner Agent:** @dev
+> **Pipeline:** qa-loop
+> **Command:** `*fix-qa-issues {story-id}`
+
+---
+
+## Purpose
+
+Fix issues reported in QA review following a structured 8-phase workflow. This task is triggered when QA identifies issues that need to be addressed before the story can be approved.
+
+**CRITICAL CONSTRAINTS:**
+
+- **Minimal changes only** - Fix ONLY what's in the fix request
+- **No scope creep** - Do NOT refactor or add features
+- **Run ALL verification steps** from the fix request
+- **Commit with proper references** to issue IDs
+
+---
+
+## autoClaude
+
+```yaml
+autoClaude:
+  version: '3.0'
+  pipelinePhase: qa-fix
+
+  deterministic: true
+  elicit: false
+  composable: true
+
+  constraints:
+    minimalChanges: true
+    noScopeCreep: true
+    noRefactoring: true
+    noNewFeatures: true
+
+  recovery:
+    trackAttempts: true
+    maxRetries: 3
+    rollbackOnFailure: true
+
+  inputs:
+    - name: storyId
+      type: string
+      required: true
+      description: "Story ID (e.g., '6.4' or 'story-6.4')"
+
+    - name: fixRequestPath
+      type: file
+      path: docs/stories/{storyId}/qa/QA_FIX_REQUEST.md
+      required: true
+      description: 'Path to the QA fix request file'
+
+    - name: qaReportPath
+      type: file
+      path: docs/stories/{storyId}/qa/qa_report.md
+      required: false
+      description: 'Path to the full QA report (optional)'
+
+  outputs:
+    - name: fixResult
+      type: object
+      schema:
+        storyId: string
+        status: completed|failed|blocked
+        issuesFixed: array
+        verificationResults: array
+        commitHash: string
+
+    - name: signalReReview
+      type: boolean
+      description: 'Signal to QA that fixes are ready for re-review'
+
+  verification:
+    type: checklist
+    source: QA_FIX_REQUEST.md verification_steps
+    timeout: 300
+```
+
+---
+
+## Command Integration (@dev)
+
+```yaml
+command:
+  name: '*fix-qa-issues'
+  syntax: '*fix-qa-issues {story-id}'
+  agent: dev
+
+  examples:
+    - '*fix-qa-issues 6.4'
+    - '*fix-qa-issues story-6.4'
+
+  aliases:
+    - '*qa-fix'
+    - '*fix-qa'
+```
+
+---
+
+## The 8 Phases of QA Issue Fixing
+
+### CRITICAL RULE: No Scope Creep
+
+```yaml
+scope_enforcement:
+  description: |
+    Fix ONLY what is explicitly listed in the QA_FIX_REQUEST.md.
+    Do NOT:
+    - Refactor code "while you're in there"
+    - Add features that "would be nice"
+    - Fix issues that weren't reported
+    - Improve code style beyond what's required
+
+  on_violation:
+    action: halt
+    message: 'Scope creep detected. Only fix issues from QA_FIX_REQUEST.md'
+```
+
+---
+
+## Phase-by-Phase Execution Flow
+
+### Phase 0: Load Context
+
+```yaml
+phase_0:
+  id: '0'
+  name: 'Load Context'
+  description: 'Load QA fix request and report to understand scope'
+
+  actions:
+    - action: load_file
+      path: docs/stories/{storyId}/qa/QA_FIX_REQUEST.md
+      required: true
+      variable: fixRequest
+
+    - action: load_file
+      path: docs/stories/{storyId}/qa/qa_report.md
+      required: false
+      variable: qaReport
+      fallback: 'Use fixRequest only'
+
+    - action: load_file
+      path: docs/stories/{storyId}.md
+      required: true
+      variable: storyFile
+
+  validation:
+    check: 'QA_FIX_REQUEST.md exists and is valid markdown'
+    onFailure: halt
+
+  error_cases:
+    - condition: 'QA_FIX_REQUEST.md not found'
+      action: halt
+      message: 'No fix request found at docs/stories/{storyId}/qa/QA_FIX_REQUEST.md'
+
+  output:
+    fixRequest: object
+    qaReport: object
+    storyContext: object
+```
+
+### Phase 1: Parse Requirements
+
+```yaml
+phase_1:
+  id: '1'
+  name: 'Parse Requirements'
+  description: 'Extract list of issues and create fix checklist'
+
+  actions:
+    - action: parse_fix_request
+      from: fixRequest
+      extract:
+        - issues # List of issues to fix
+        - severity # CRITICAL, MAJOR, MINOR
+        - affectedFiles # Files that need changes
+        - verificationSteps # How to verify each fix
+
+    - action: create_checklist
+      format:
+        - issueId: string # e.g., "CRIT-1", "MAJ-2"
+        - description: string
+        - severity: string # CRITICAL|MAJOR|MINOR
+        - file: string # Affected file
+        - fixApproach: string # How to fix
+        - status: pending # pending|fixed|verified
+
+    - action: prioritize
+      order:
+        - CRITICAL # Fix first
+        - MAJOR # Fix second
+        - MINOR # Fix last
+
+  validation:
+    check: 'At least one issue extracted from fix request'
+    onFailure: halt
+
+  output:
+    issueChecklist: array
+    totalIssues: integer
+    criticalCount: integer
+    majorCount: integer
+    minorCount: integer
+```
+
+### Phase 2: Start Development
+
+```yaml
+phase_2:
+  id: '2'
+  name: 'Start Development'
+  description: 'Prepare environment for fixing'
+
+  actions:
+    - action: check_branch
+      verify: 'On correct branch for story'
+      if_not:
+        - action: checkout
+          branch: 'feat/{storyId}' # or use worktree if configured
+
+    - action: git_status
+      verify: 'Working directory clean or has only expected changes'
+
+    - action: record_state
+      save:
+        - commitBefore: '{currentCommitHash}'
+        - branchName: '{currentBranch}'
+        - timestamp: '{timestamp}'
+
+  validation:
+    check: 'On correct branch, ready to make changes'
+    onFailure: ask_user
+
+  output:
+    branch: string
+    commitBefore: string
+    environmentReady: boolean
+```
+
+### Phase 3: Fix Issues Sequentially
+
+```yaml
+phase_3:
+  id: '3'
+  name: 'Fix Issues Sequentially'
+  description: 'Address each issue in priority order'
+  criticality: CORE
+
+  constraints:
+    - "Fix ONLY what's in the issue list"
+    - 'Apply MINIMAL changes'
+    - 'Do NOT refactor surrounding code'
+    - 'Do NOT add new features'
+    - 'Do NOT fix issues not in the list'
+
+  actions:
+    - action: for_each_issue
+      in: issueChecklist
+      ordered_by: severity
+      do:
+        - action: read_file
+          path: issue.file
+
+        - action: locate_issue
+          description: issue.description
+
+        - action: apply_fix
+          approach: issue.fixApproach
+          minimal: true
+
+        - action: update_checklist
+          issueId: issue.issueId
+          status: fixed
+
+        - action: log_change
+          format: 'Fixed {issueId}: {description}'
+
+  validation:
+    check: 'All issues marked as fixed'
+    onFailure: continue_with_remaining
+
+  error_handling:
+    - condition: 'Cannot locate issue'
+      action: log_and_continue
+      message: 'Issue {issueId} could not be located - may already be fixed'
+
+    - condition: 'Fix would require major changes'
+      action: halt
+      message: 'Issue {issueId} requires scope beyond minimal fix'
+
+  output:
+    issuesFixed: array
+    issuesSkipped: array
+    filesModified: array
+```
+
+### Phase 4: Run Tests
+
+```yaml
+phase_4:
+  id: '4'
+  name: 'Run Tests'
+  description: "Execute test suite to verify fixes don't break anything"
+
+  actions:
+    - action: run_command
+      command: 'npm run lint'
+      timeout: 60000
+      required: true
+
+    - action: run_command
+      command: 'npm run test'
+      timeout: 300000
+      required: true
+
+    - action: run_command
+      command: 'npm run typecheck'
+      timeout: 60000
+      required: false # Only if TypeScript project
+
+  validation:
+    check: 'All tests pass, no lint errors'
+    onFailure: goto phase_3 # Fix and retry
+
+  retry:
+    max_attempts: 3
+    on_failure: halt
+
+  output:
+    lintPassed: boolean
+    testsPassed: boolean
+    typecheckPassed: boolean
+    testResults: object
+```
+
+### Phase 5: Self-Verification
+
+```yaml
+phase_5:
+  id: '5'
+  name: 'Self-Verification'
+  description: 'Run ALL verification steps from the fix request'
+  criticality: REQUIRED
+
+  actions:
+    - action: extract_verification_steps
+      from: fixRequest.verification_steps
+
+    - action: for_each_step
+      in: verificationSteps
+      do:
+        - action: execute_verification
+          type: step.type # command|api|browser|e2e|manual
+          command: step.command
+          expected: step.expected
+
+        - action: document_result
+          stepId: step.id
+          passed: boolean
+          actual: string
+          notes: string
+
+  verification_types:
+    command:
+      description: 'Run CLI command and check output'
+      example: 'npm run lint -- --quiet'
+
+    api:
+      description: 'Make API call and verify response'
+      example: 'curl -X GET http://localhost:3000/api/health'
+
+    browser:
+      description: 'Use playwright to verify UI'
+      example: 'Check login form renders correctly'
+
+    e2e:
+      description: 'Run end-to-end test'
+      example: "npm run test:e2e -- --grep 'auth'"
+
+    manual:
+      description: 'Document manual verification'
+      example: 'Visually confirm button alignment'
+
+  validation:
+    check: 'ALL verification steps pass'
+    onFailure: return_to_phase_3
+
+  output:
+    verificationResults: array
+    allPassed: boolean
+    failedSteps: array
+```
+
+### Phase 6: Commit Fixes
+
+```yaml
+phase_6:
+  id: '6'
+  name: 'Commit Fixes'
+  description: 'Commit changes with proper issue references'
+
+  actions:
+    - action: git_add
+      files: '{filesModified}'
+      # Only add files that were modified for fixes
+
+    - action: generate_commit_message
+      format: |
+        fix(qa): resolve {issueIds}
+
+        Issues fixed:
+        {for each issue in issuesFixed}
+        - {issue.issueId}: {issue.description}
+        {end for}
+
+        Story: {storyId}
+
+        Co-Authored-By: Claude <noreply@anthropic.com>
+
+    - action: git_commit
+      message: '{generatedCommitMessage}'
+
+  validation:
+    check: 'Commit created successfully'
+    onFailure: retry
+
+  output:
+    commitHash: string
+    commitMessage: string
+```
+
+### Phase 7: Update Plan & Signal
+
+```yaml
+phase_7:
+  id: '7'
+  name: 'Update Plan & Signal'
+  description: 'Mark issues as fixed and signal QA for re-review'
+
+  actions:
+    # Update issue status in fix request (if tracking there)
+    - action: update_fix_request
+      path: docs/stories/{storyId}/qa/QA_FIX_REQUEST.md
+      changes:
+        - Add "## Fix Results" section
+        - Mark each issue as fixed with commit reference
+        - Add timestamp
+
+    # Update story file Dev Agent Record
+    - action: update_story
+      path: docs/stories/{storyId}.md
+      section: 'Dev Agent Record'
+      add:
+        - completion_note: 'QA fixes applied: {issueIds}'
+        - reference: 'QA_FIX_REQUEST.md'
+
+    # Update plan tracker for dashboard integration
+    - action: update_plan_tracker
+      script: |
+        const { PlanTracker } = require('.aiox-core/infrastructure/scripts/plan-tracker.js');
+        const tracker = new PlanTracker({ storyId: '{storyId}' });
+        tracker.load();
+        tracker.updateStatusJson({
+          qaFixesApplied: true,
+          fixedIssues: {issuesFixed.length},
+          status: 'qa-fixes-complete'
+        });
+
+    # Signal QA for re-review
+    - action: create_signal_file
+      path: docs/stories/{storyId}/qa/READY_FOR_REREVIEW.md
+      content: |
+        # Ready for QA Re-Review
+
+        **Story:** {storyId}
+        **Fixed By:** @dev
+        **Timestamp:** {timestamp}
+        **Commit:** {commitHash}
+
+        ## Issues Fixed
+
+        {for each issue in issuesFixed}
+        - [x] {issue.issueId}: {issue.description}
+        {end for}
+
+        ## Verification Results
+
+        {for each result in verificationResults}
+        - {result.passed ? '✅' : '❌'} {result.stepId}: {result.notes}
+        {end for}
+
+        ---
+
+        **Next Step:** @qa re-review with `*review-story {storyId}`
+
+  validation:
+    check: 'All updates completed, signal file created'
+    onFailure: retry
+
+  output:
+    fixRequestUpdated: boolean
+    storyUpdated: boolean
+    planTrackerUpdated: boolean
+    signalCreated: boolean
+```
+
+---
+
+## Summary Output Format
+
+```yaml
+summary:
+  on_completion:
+    format: |
+      ## QA Fixes Complete for {storyId}
+
+      **Issues Fixed:** {issuesFixed.length}/{totalIssues}
+      **Commit:** {commitHash}
+      **Status:** Ready for QA Re-Review
+
+      ### Issues Addressed
+      {for each issue in issuesFixed}
+      - ✅ {issue.issueId} ({issue.severity}): {issue.description}
+      {end for}
+
+      ### Verification Results
+      {for each result in verificationResults}
+      - {result.passed ? '✅' : '❌'} {result.stepId}
+      {end for}
+
+      ### Next Steps
+      1. QA agent should re-review: `@qa *review-story {storyId}`
+      2. If all issues verified, story moves to "Ready for Review"
+
+      ---
+      Signal file created: docs/stories/{storyId}/qa/READY_FOR_REREVIEW.md
+```
+
+---
+
+## Error Handling
+
+```yaml
+errors:
+  - id: fix-request-not-found
+    condition: 'QA_FIX_REQUEST.md does not exist'
+    action: halt
+    message: 'No fix request found. Run QA review first.'
+    blocking: true
+
+  - id: no-issues-found
+    condition: 'Fix request has no issues listed'
+    action: halt
+    message: 'No issues to fix. Story may already be passing.'
+    blocking: false
+
+  - id: scope-creep-detected
+    condition: 'Agent attempts changes outside issue list'
+    action: halt
+    message: 'Scope creep: Only fix issues from QA_FIX_REQUEST.md'
+    blocking: true
+
+  - id: tests-failing-after-fixes
+    condition: 'Tests fail after applying fixes'
+    action: escalate
+    message: 'Fixes caused test failures. Review approach.'
+    blocking: true
+
+  - id: verification-failed
+    condition: "Verification steps don't pass"
+    action: retry_from_phase_3
+    message: 'Verification failed. Re-check fixes.'
+    max_retries: 3
+```
+
+---
+
+## Integration with QA Loop
+
+```yaml
+qa_loop_integration:
+  triggered_by:
+    - QA review identifies issues
+    - QA_FIX_REQUEST.md created
+    - @qa signals @dev
+
+  triggers_next:
+    - READY_FOR_REREVIEW.md signals @qa
+    - @qa runs re-review
+    - Loop continues until PASS or WAIVED
+
+  handoff_format:
+    from_qa_to_dev: QA_FIX_REQUEST.md
+    from_dev_to_qa: READY_FOR_REREVIEW.md
+
+  status_tracking:
+    - pending_fixes: "QA issues identified, awaiting dev"
+    - in_progress_fixes: "Dev fixing issues"
+    - fixes_complete: "Dev done, awaiting QA re-review"
+    - passed: "All issues resolved"
+```
+
+---
+
+## Examples
+
+### Example 1: Simple Fix
+
+```bash
+*fix-qa-issues 6.4
+```
+
+**Output:**
+
+```
+## QA Fixes Complete for 6.4
+
+**Issues Fixed:** 2/2
+**Commit:** abc123def
+**Status:** Ready for QA Re-Review
+
+### Issues Addressed
+- ✅ CRIT-1 (CRITICAL): Missing null check in validator
+- ✅ MAJ-1 (MAJOR): Error message not user-friendly
+
+### Verification Results
+- ✅ Run npm test
+- ✅ Check null input returns proper error
+
+### Next Steps
+1. QA agent should re-review: `@qa *review-story 6.4`
+2. If all issues verified, story moves to "Ready for Review"
+```
+
+### Example 2: Partial Fix (Some Issues Cannot Be Fixed)
+
+```bash
+*fix-qa-issues 6.5
+```
+
+**Output:**
+
+```
+## QA Fixes Partially Complete for 6.5
+
+**Issues Fixed:** 2/3
+**Commit:** def456ghi
+**Status:** Needs Manual Review
+
+### Issues Addressed
+- ✅ CRIT-1 (CRITICAL): SQL injection vulnerability
+- ✅ MAJ-1 (MAJOR): Missing input validation
+- ⚠️ MAJ-2 (MAJOR): Performance regression - requires scope expansion
+
+### Notes
+MAJ-2 requires refactoring the data layer. This exceeds minimal fix scope.
+Recommend creating separate story for performance optimization.
+
+### Next Steps
+1. Discuss MAJ-2 with @qa and @po
+2. Either expand scope or create follow-up story
+```
+
+---
+
+## Metadata
+
+```yaml
+metadata:
+  story: '6.4'
+  epic: 'Epic 6 - QA Evolution'
+  created: '2026-01-29'
+  author: '@dev (Dex)'
+  version: '1.0.0'
+  tags:
+    - qa-loop
+    - fix-issues
+    - quality-assurance
+    - development
+```
+
+## Handoff
+next_agent: @qa
+next_command: *review {story-id}
+condition: All QA_FIX_REQUEST issues resolved
+alternatives:
+  - agent: @dev, command: *run-tests, condition: Verify fixes pass before re-review