Initial commit

skills/workflow-generator/templates/qa-template.md

@@ -0,0 +1,685 @@
+---
+description: Comprehensive quality assurance and validation for Elixir projects
+argument-hint: [optional-plan-name]
+allowed-tools: Read, Grep, Glob, Task, Bash, TodoWrite, Write
+---
+
+# QA
+
+Systematically validate Elixir implementation against quality standards and success criteria.
+
+**Project Type**: {{PROJECT_TYPE}}
+
+## Purpose
+
+Validate completed work through automated checks, code review, and comprehensive quality analysis to ensure implementation meets standards.
+
+## Steps to Execute:
+
+### Step 1: Determine Scope
+
+**If plan name provided:**
+- Locate plan file: `{{DOCS_LOCATION}}/plans/*[plan-name]*.md`
+- Read plan completely
+- Extract success criteria
+- Validate implementation against that plan
+
+**If no plan provided:**
+- General Elixir project health check
+- Run all quality tools
+- Review recent changes
+- Provide overall quality assessment
+
+### Step 2: Initial Discovery
+
+**Read implementation plan** (if validating against plan):
+```bash
+find {{DOCS_LOCATION}}/plans -name "*[plan-name]*.md" -type f
+```
+
+**Gather git evidence:**
+```bash
+# See what changed
+git status
+git diff --stat
+git log --oneline -10
+
+# If validating a specific branch
+git diff main...HEAD --stat
+```
+
+**Create validation plan** using TodoWrite:
+```
+1. [in_progress] Gather context and plan
+2. [pending] Run automated quality checks
+3. [pending] Spawn validation agents
+4. [pending] Check manual criteria
+5. [pending] Generate validation report
+6. [pending] Offer fix plan generation if critical issues found
+```
+
+### Step 3: Run Automated Quality Checks
+
+Run all automated checks in parallel using separate Bash commands:
+
+**Compilation Check:**
+```bash
+mix clean && mix compile --warnings-as-errors
+```
+
+**Test Suite:**
+```bash
+{{TEST_COMMAND}}
+```
+
+**Format Validation:**
+```bash
+mix format --check-formatted
+```
+
+{{QUALITY_TOOL_COMMANDS}}
+
+**Capture results** from each check:
+- Exit code (0 = pass, non-zero = fail)
+- Output messages
+- Any warnings or errors
+
+Mark this step complete in TodoWrite.
+
+### Step 4: Spawn Validation Agents
+
+**Agent Strategy**:
+
+This template uses `subagent_type="general-purpose"` agents since generated QA commands
+are project-agnostic. For token-efficient specialized validation, consider defining:
+
+- **finder**: Fast file location without reading (token-efficient for discovery)
+- **analyzer**: Deep code analysis with file reading (for technical tracing)
+
+For standard Elixir projects, general-purpose agents provide flexibility.
+
+Use Task tool to spawn parallel validation agents:
+
+**Agent 1: Code Review** (subagent_type="general-purpose"):
+```
+Review the Elixir code changes for:
+- Module organization and naming conventions
+- Function documentation (@moduledoc, @doc)
+- Pattern matching best practices
+- Error handling (tuple returns, with blocks)
+- Code clarity and readability
+- Adherence to Elixir idioms
+
+Focus on:
+- Context boundaries (if Phoenix)
+- Ecto query patterns
+- GenServer/Agent usage
+- Supervisor tree organization
+
+Note: This agent will both locate and read files. For token-efficient workflows,
+consider splitting into a finder (locate) + analyzer (read) pattern.
+
+Provide file:line references for all observations.
+Document current implementation (not suggestions for improvement).
+```
+
+**Agent 2: Test Coverage** (subagent_type="general-purpose"):
+```
+Find and analyze test coverage for the implementation:
+
+First, locate test files:
+- Find all test files related to changes
+- Identify test directory structure
+
+Then, analyze coverage:
+- Check if all public functions have tests
+- Verify both success and error cases are tested
+- Check for edge case coverage
+- Identify any untested code paths
+
+ExUnit-specific:
+- describe blocks usage
+- test naming conventions
+- setup/teardown patterns
+- assertion quality
+
+Note: This agent combines finding and reading. For token-efficient workflows,
+first use finder to locate test files, then use analyzer to read and evaluate them.
+
+Provide file:line references.
+Document what is tested, not what should be tested.
+```
+
+**Agent 3: Documentation Review** (subagent_type="general-purpose"):
+```
+Find and review documentation completeness:
+
+First, locate documentation:
+- README files
+- Module documentation files
+- Inline documentation
+
+Then, analyze quality:
+- @moduledoc present and descriptive
+- @doc on all public functions
+- @typedoc on public types
+- Inline documentation for complex logic
+- README updates if needed
+
+Check for:
+- Code examples in docs
+- Clear explanations
+- Accurate descriptions
+
+Note: This agent combines finding and reading. For token-efficient workflows,
+first use finder to locate docs, then use analyzer to evaluate quality.
+
+Provide file:line references.
+Document current documentation state.
+```
+
+**Wait for all agents** to complete before proceeding.
+
+Mark this step complete in TodoWrite.
+
+### Step 5: Verify Success Criteria
+
+**If validating against plan:**
+
+**Read success criteria** from plan:
+- Automated verification section
+- Manual verification section
+
+**Check automated criteria:**
+- Match each criterion against actual checks
+- Confirm all automated checks passed
+- Note any that failed
+
+**Check manual criteria:**
+- Review each manual criterion
+- Assess whether it's met (check implementation)
+- Document status for each
+
+**If general health check:**
+
+**Automated Health Indicators:**
+- Compilation succeeds
+- All tests pass
+- Format check passes
+- Quality tools pass (if configured)
+
+**Manual Health Indicators:**
+- Recent changes are logical
+- Code follows project patterns
+- No obvious bugs or issues
+- Documentation is adequate
+
+Mark this step complete in TodoWrite.
+
+### Step 6: Elixir-Specific Quality Checks
+
+**Module Organization:**
+- Are modules properly namespaced?
+- Is module structure clear (use, import, alias at top)?
+- Are public vs private functions clearly separated?
+
+**Pattern Matching:**
+- Are function heads used effectively?
+- Is pattern matching preferred over conditionals?
+- Are guard clauses used appropriately?
+
+**Error Handling:**
+- Are tuple returns used ({:ok, result}/{:error, reason})?
+- Are with blocks used for complex error flows?
+- Are errors propagated correctly?
+
+**Phoenix-Specific** (if {{PROJECT_TYPE}} is Phoenix):
+- Are contexts properly bounded?
+- Do controllers delegate to contexts?
+- Are LiveViews structured correctly (mount, handle_event, render)?
+- Are routes organized logically?
+
+**Ecto-Specific:**
+- Are schemas properly defined?
+- Are changesets comprehensive (validations, constraints)?
+- Are queries composable and efficient?
+- Are transactions used where needed?
+
+**Process-Based** (GenServer, Agent, Task):
+- Is supervision tree correct?
+- Are processes named appropriately?
+- Is message passing clear?
+- Are process lifecycles managed?
+
+Mark this step complete in TodoWrite.
+
+### Step 7: Generate Validation Report
+
+**Compile all findings:**
+- Automated check results
+- Agent findings (code review, tests, docs)
+- Success criteria status
+- Elixir-specific observations
+
+**Create validation report structure:**
+
+```markdown
+---
+date: [ISO timestamp]
+validator: [Git user name]
+commit: [Current commit hash]
+branch: [Current branch name]
+plan: [Plan name if applicable]
+status: [PASS / PASS_WITH_WARNINGS / FAIL]
+tags: [qa, validation, elixir, {{PROJECT_TYPE_TAGS}}]
+---
+
+# QA Report: [Plan Name or "General Health Check"]
+
+**Date**: [Current date and time]
+**Validator**: [Git user name]
+**Commit**: [Current commit hash]
+**Branch**: [Current branch]
+**Project Type**: {{PROJECT_TYPE}}
+
+## Executive Summary
+
+**Overall Status**: ✅ PASS / ⚠️ PASS WITH WARNINGS / ❌ FAIL
+
+**Quick Stats:**
+- Compilation: ✅/❌
+- Tests: [N] passed, [N] failed
+{{QUALITY_TOOLS_RESULTS_SUMMARY}}
+- Code Review: [N] observations
+- Test Coverage: [Assessment]
+- Documentation: [Assessment]
+
+## Automated Verification Results
+
+### Compilation
+```
+[Output from mix compile]
+```
+**Status**: ✅ Success / ❌ Failed
+**Issues**: [List any warnings or errors]
+
+### Test Suite
+```
+[Output from test command]
+```
+**Status**: ✅ All passed / ❌ [N] failed
+**Failed Tests**:
+- [test name] - [reason]
+
+### Code Formatting
+```
+[Output from mix format --check-formatted]
+```
+**Status**: ✅ Formatted / ❌ Needs formatting
+
+{{QUALITY_TOOLS_DETAILED_RESULTS}}
+
+## Agent Validation Results
+
+### Code Review Findings
+
+[Findings from code review agent]
+
+**Observations** ([N] total):
+1. [file:line] - [Observation about current implementation]
+2. [file:line] - [Observation]
+
+### Test Coverage Analysis
+
+[Findings from test coverage agent]
+
+**Coverage Assessment**:
+- Public functions tested: [N]/[M]
+- Edge cases covered: [Assessment]
+- Untested paths: [List if any]
+
+### Documentation Review
+
+[Findings from documentation agent]
+
+**Documentation Status**:
+- Modules documented: [N]/[M]
+- Public functions documented: [N]/[M]
+- Quality assessment: [Good/Adequate/Needs Work]
+
+## Success Criteria Validation
+
+[If validating against plan, list each criterion]
+
+**Automated Criteria**:
+- [x] Compilation succeeds
+- [x] {{TEST_COMMAND}} passes
+{{SUCCESS_CRITERIA_CHECKLIST}}
+
+**Manual Criteria**:
+- [x] Feature works as expected
+- [ ] Edge cases handled [Status]
+- [x] Documentation updated
+
+## Elixir-Specific Observations
+
+**Module Organization**: [Assessment]
+**Pattern Matching**: [Assessment]
+**Error Handling**: [Assessment]
+{{PROJECT_TYPE_SPECIFIC_OBSERVATIONS}}
+
+## Issues Found
+
+[If any issues, list them by severity]
+
+### Critical Issues (Must Fix)
+[None or list]
+
+### Warnings (Should Fix)
+[None or list]
+
+### Recommendations (Consider)
+[None or list]
+
+## Overall Assessment
+
+[IF PASS]
+✅ **IMPLEMENTATION VALIDATED**
+
+All quality checks passed:
+- Automated verification: Complete
+- Code review: No issues
+- Tests: All passing
+- Documentation: Adequate
+
+Implementation meets quality standards and is ready for merge/deploy.
+
+[IF PASS WITH WARNINGS]
+⚠️ **PASS WITH WARNINGS**
+
+Core functionality validated but some areas need attention:
+- [List warning areas]
+
+Address warnings before merge or create follow-up tasks.
+
+[IF FAIL]
+❌ **VALIDATION FAILED**
+
+Critical issues prevent approval:
+- [List critical issues]
+
+Fix these issues and re-run QA: `/qa "[plan-name]"`
+
+## Next Steps
+
+[IF PASS]
+- Merge to main branch
+- Deploy (if applicable)
+- Close related tickets
+
+[IF PASS WITH WARNINGS]
+- Address warnings
+- Re-run QA or accept warnings and proceed
+- Document accepted warnings
+
+[IF FAIL]
+- Fix critical issues
+- Address failing tests
+- Re-run: `/qa "[plan-name]"`
+```
+
+Save report to: `{{DOCS_LOCATION}}/qa-reports/YYYY-MM-DD-[plan-name]-qa.md`
+
+Mark this step complete in TodoWrite.
+
+### Step 8: Present Results
+
+**Show concise summary to user:**
+
+```markdown
+# QA Validation Complete
+
+**Plan**: [Plan name or "General Health Check"]
+**Status**: ✅ PASS / ⚠️ PASS WITH WARNINGS / ❌ FAIL
+
+## Results Summary
+
+**Automated Checks**:
+- Compilation: ✅
+- Tests: ✅ [N] passed
+{{QUALITY_TOOLS_SUMMARY_DISPLAY}}
+
+**Code Quality**:
+- Code Review: [N] observations
+- Test Coverage: [Good/Adequate/Needs Work]
+- Documentation: [Good/Adequate/Needs Work]
+
+**Detailed Report**: `{{DOCS_LOCATION}}/qa-reports/YYYY-MM-DD-[plan-name]-qa.md`
+
+[IF FAIL]
+**Critical Issues**:
+1. [Issue with file:line]
+2. [Issue with file:line]
+
+Fix these and re-run: `/qa "[plan-name]"`
+
+[IF PASS]
+**Ready to merge!** ✅
+```
+
+### Step 9: Offer Fix Plan Generation (Conditional)
+
+**Only execute this step if overall status is ❌ FAIL**
+
+If QA detected critical issues:
+
+**9.1 Count Critical Issues**
+
+Count issues from validation report that are marked as ❌ CRITICAL or blocking.
+
+**9.2 Prompt User for Fix Plan Generation**
+
+Use AskUserQuestion tool:
+```
+Question: "QA detected [N] critical issues. Generate a fix plan to address them?"
+Header: "Fix Plan"
+Options (multiSelect: false):
+  Option 1:
+    Label: "Yes, generate fix plan"
+    Description: "Create a detailed plan to address all critical issues using /plan command"
+  Option 2:
+    Label: "No, I'll fix manually"
+    Description: "Exit QA and fix issues manually, then re-run /qa"
+```
+
+**9.3 If User Selects "Yes, generate fix plan":**
+
+**9.3.1 Extract QA Report Filename**
+
+Get the most recent QA report generated in Step 7:
+```bash
+ls -t {{DOCS_LOCATION}}/qa-reports/*-qa.md 2>/dev/null | head -1
+```
+
+Store filename in variable: QA_REPORT_PATH
+
+**9.3.2 Invoke Plan Command**
+
+Use SlashCommand tool:
+```
+Command: /plan "Fix critical issues from QA report: [QA_REPORT_PATH]"
+```
+
+Wait for plan generation to complete.
+
+**9.3.3 Extract Plan Filename**
+
+Parse the output from /plan command to find the generated plan filename.
+Typical format: `{{DOCS_LOCATION}}/plans/plan-YYYY-MM-DD-fix-*.md`
+
+Store plan name without path/extension in variable: FIX_PLAN_NAME
+
+Report to user:
+```
+Fix plan created at: [PLAN_FILENAME]
+```
+
+**9.3.4 Prompt User for Plan Execution**
+
+Use AskUserQuestion tool:
+```
+Question: "Fix plan created. Execute the fix plan now?"
+Header: "Execute Plan"
+Options (multiSelect: false):
+  Option 1:
+    Label: "Yes, execute fix plan"
+    Description: "Run /implement to apply fixes, then re-run /qa for validation"
+  Option 2:
+    Label: "No, I'll review first"
+    Description: "Exit and review the plan manually before implementing"
+```
+
+**9.3.5 If User Selects "Yes, execute fix plan":**
+
+Use SlashCommand tool:
+```
+Command: /implement "[FIX_PLAN_NAME]"
+```
+
+Wait for implementation to complete.
+
+Report:
+```
+Fix implementation complete. Re-running QA for validation...
+```
+
+Use SlashCommand tool:
+```
+Command: /qa
+```
+
+Wait for QA to complete.
+
+Report:
+```
+Fix cycle complete. Check QA results above.
+```
+
+**9.3.6 If User Selects "No, I'll review first":**
+
+Report:
+```
+Fix plan saved at: [PLAN_FILENAME]
+
+When ready to implement:
+  /implement "[FIX_PLAN_NAME]"
+
+After implementing, re-run QA:
+  /qa
+```
+
+**9.4 If User Selects "No, I'll fix manually":**
+
+Report:
+```
+Manual fixes required.
+
+Critical issues documented in: [QA_REPORT_PATH]
+
+After fixing, re-run QA:
+  /qa
+```
+
+**9.5 If QA Status is NOT ❌ FAIL:**
+
+Skip this step entirely (no fix plan offer needed).
+
+## Quality Tool Integration
+
+{{QUALITY_TOOL_INTEGRATION_GUIDE}}
+
+## Important Guidelines
+
+### Automated vs Manual
+
+**Automated Verification:**
+- Must be runnable via command
+- Exit code determines pass/fail
+- Repeatable and consistent
+
+**Manual Verification:**
+- Requires human judgment
+- UI/UX quality
+- Business logic correctness
+- Edge case appropriateness
+
+### Thoroughness
+
+**Be comprehensive:**
+- Run all configured quality tools
+- Spawn all validation agents
+- Check all success criteria
+- Document all findings
+
+**Be objective:**
+- Report what you find
+- Don't minimize issues
+- Don't over-report non-issues
+- Focus on facts
+
+### Validation Philosophy
+
+**Not a rubber stamp:**
+- Real validation, not formality
+- Find real issues
+- Assess true quality
+
+**Not overly strict:**
+- Focus on significant issues
+- Warnings vs failures
+- Practical quality bar
+
+## Edge Cases
+
+### If Plan Doesn't Exist
+
+User provides plan name but file not found:
+- Search {{DOCS_LOCATION}}/plans/
+- List available plans
+- Ask user to clarify or choose
+
+### If No Changes Detected
+
+Running QA but no git changes:
+- Note in report
+- Run general health check anyway
+- Report clean state
+
+### If Tests Have Pre-Existing Failures
+
+Tests failing before this implementation:
+- Document which tests are pre-existing
+- Focus on new failures
+- Note technical debt in report
+
+### If Quality Tools Not Installed
+
+If Credo, Dialyzer, etc. not in mix.exs:
+- Note in report
+- Skip that tool
+- Don't fail validation for missing optional tools
+
+## Example Session
+
+**User**: `/qa "user-authentication"`
+
+**Process**:
+1. Find plan: `{{DOCS_LOCATION}}/plans/2025-01-23-user-authentication.md`
+2. Read success criteria from plan
+3. Run automated checks (compile, test, format, Credo, Dialyzer)
+4. Spawn 3 validation agents (code review, test coverage, docs)
+5. Wait for agents to complete
+6. Verify success criteria
+7. Check Elixir-specific patterns
+8. Generate comprehensive report
+9. Present summary: "✅ PASS - All 12 success criteria met"