QA Workflow

QA Workflow

"Orchestration layer for QA validation - delegate to specialized skills for each step."

Core Responsibilities

• Load proper skills and tools - Always ensure you have the right skills loaded for each task. Run tasks and subagents in parallel when possible to optimize time.
• Full validation - code quality review, type-check, lint, test, build, specifications validation
• Code quality enforcement - Check for code quality smells, anti-patterns, wrong design patterns and implementation issues
• Checkpoint tracking - Use validation-state.json to verify all steps complete before proceeding
• Bug reporting - Structured bug reports with evidence
• Specifications validation - Check implementation vs design specifications

Standard Message Pipeline

• Read message input in this order: CLI message argument → pending-messages-qa.json → inbox diagnostics
• Never delete queue files (messages/*) or pending transaction files (pending-messages-*.json)
• Watchdog owns delivery and cleanup lifecycle
• Signal lifecycle using status_update:
  • working when validation starts
  • awaiting_pm / awaiting_gd when blocked
  • ready / waiting / idle when available for next delivery

Agent Startup Protocol

PRE-REQUISITE: You should already have loaded the shared-worktree skill and be in the correct worktree directory before starting this workflow!

On each QA agent spawn, follow these steps EXACTLY in order:

STEP 0: INITIALIZE VALIDATION STATE (MANDATORY - First action)

Before any validation work begins:

1. Create .claude/session/validation-state.json if it doesn't exist
2. Initialize with task information:

   {
     "taskId": "{taskId from validation_request}",
     "startedAt": "{ISO-8601 timestamp}",
     "checkpoints": {
       "codeReview": null,
       "typeCheck": null,
       "lint": null,
       "test": null,
       "build": null,
       "codeRefactor": false
     }
   }
   

3. PROCEED to Step 1

STEP 1: SEND STATUS UPDATE (MANDATORY)

Send status_update to watchdog with status: "working" and current task details.

STEP 2: CODE QUALITY PRE-CHECK (MANDATORY - Unskippable)

BEFORE running any automated checks:

1. Load qa-code-review skill
2. Identify changed files from the validation request
3. Run quality checks using the qa-code-review skill's grep patterns
4. Update checkpoint: validation-state.json → checkpoints.codeReview = "PASS" or "FAIL"
5. IF "FAIL": Create bug report, STOP validation, report to PM
6. IF "PASS": Proceed to Step 3

STEP 3: AUTOMATED CHECKS (MANDATORY)

Follow the qa-validation-workflow skill guidelines:

1. Load qa-validation-workflow skill
2. Execute in sequence:
   • Type Check → Update checkpoint
   • Lint → Update checkpoint
   • Test → Update checkpoint
   • Build → Update checkpoint
3. Each step MUST update its checkpoint in validation-state.json before proceeding
4. IF any check FAILS: STOP validation, create bug report, report to PM

STEP 4: CODE REFACTOR GATE (MANDATORY - Enforced Checkpoint)

BEFORE proceeding to specification validation:

1. READ validation-state.json
2. VERIFY checkpoints.codeRefactor == true
3. IF false:
   • READ validation_request.payload.files for list of created/modified files
   • INVOKE code-refactor subagent using Task tool:

   Task tool → subagent_type: "code-refactor", model: "sonnet"
   Prompt: "Review and refactor these files using codebase-cleanup-refactor-clean skill:
   Files to review: {files.create} + {files.modify}
   Context: QA validation for task {taskId}
   Focus on: code quality, clean code principles, SOLID patterns, anti-patterns, maintainability"
   ``` WAIT for code-refactor subagent completion
   - **READ** code-refactor output to verify completion
   - **UPDATE** checkpoint: `checkpoints.codeRefactor = true`
   - **IF changes were made:** Re-execute Step 3 (re-validation loop)
   - **IF re-validation FAILS:** Report bug, DO NOT proceed
   - **ONLY** proceed to Step 5 after code-refactor checkpoint is true
   

   • WAIT for code-refactor subagent completion
   • READ code-refactor output to verify completion
   • UPDATE checkpoint: checkpoints.codeRefactor = true
   • IF changes were made: Re-execute Step 3 (re-validation loop)
   • IF re-validation FAILS: Report bug, DO NOT proceed
4. ONLY proceed to Step 5 after code-refactor checkpoint is true

STEP 5: SPECIFICATION VALIDATION

After all automated checks pass and code-refactor completes:

1. READ prd.json for the task's acceptance criteria
2. READ relevant GDD documents for design specifications
3. VERIFY each acceptance criterion is met in implementation
4. DOCUMENT results:
   • Which criteria passed
   • Any gaps between implementation and design
   • Visual/behavioral verification notes

STEP 6: FINAL DECISION GATE (MANDATORY)

BEFORE committing or reporting:

1. READ ALL checkpoints from validation-state.json
2. VERIFY all checkpoints:
   • codeReview: "PASS"
   • typeCheck: "PASS"
   • lint: "PASS"
   • test: "PASS"
   • build: "PASS"
   • codeRefactor: true
3. DECISION:
   • IF any checkpoint = "FAIL": Status = "FAILED", create bug_report using qa-reporting-bug-reporting skill
   • IF all checkpoints PASS: Status = "PASSED", prepare for commit
4. NEVER proceed to Step 7 without completing Steps 0-6

STEP 7: COMMIT & REPORT (Only after passing all gates)

ONLY execute after Steps 0-6 complete successfully:

1. UPDATE validation-state.json with finalStatus: "PASSED" or "FAILED"
2. COMMIT all changes to current branch with [ralph] [qa] {taskId}: Validation {status}
3. IF PASSED: Merge to main and push
4. IF FAILED: DO NOT merge (no push)
5. SEND message to PM with validation results:
   • Overall status
   • Checkpoint results summary
   • Bug report (if failed)
   • Observations and notes
6. RUN server cleanup using shared-lifecycle skill
7. SEND final status_update to watchdog with status: "ready"
8. EXIT

If Blocked

If validation cannot proceed due to missing information:

1. UPDATE prd.json task state with blocker details
2. UPDATE state: state.status = "awaiting_pm" or "awaiting_gd"
3. SET state.lastSeen = "{ISO_TIMESTAMP}"
4. SEND message to PM or Game Designer with details
5. SEND status_update to watchdog with blocked status
6. EXIT and wait for response

Re-Validation Loop

CRITICAL: If code-refactor makes changes, you MUST re-run automated checks:

1. Reset checkpoints: typeCheck, lint, test, build → null
2. Re-execute Step 3 (Automated Checks)
3. Verify all checkpoints pass again
4. Only proceed to Step 5 after re-validation passes

Important Reminders

• NEVER skip Step 2 (code quality pre-check) - catches issues automated tools miss
• NEVER skip Step 4 (code-refactor gate) - enforced by checkpoint verification
• ALWAYS update checkpoints after each step - validation-state.json is source of truth
• STOP immediately on any FAIL - do not continue validation
• RE-VALIDATE after refactor - automated checks must pass again
• READ validation_request payload for file lists - needed for code-refactor invocation

State Transitions

Exit Conditions

BEFORE exiting, you MUST verify:

1. ✅ All checkpoints updated in validation-state.json
2. ✅ Code-refactor completed (checkpoints.codeRefactor == true)
3. ✅ Decision made based on ALL checkpoints
4. ✅ Bug report created if validation failed
5. ✅ Commit made with [ralph] [qa] prefix
6. ✅ Message sent to PM with results
7. ✅ Status update sent to watchdog (ready/idle)
8. ✅ Server cleanup run using shared-lifecycle skill

Converted and distributed by TomeVault — claim your Tome and manage your conversions.