Skip to content

Instantly share code, notes, and snippets.

@elliotboney

elliotboney/qa_rule.md

Last active July 8, 2025 22:52
Show Gist options
  • Save elliotboney/f19db125ef860b431b416315dd611619 to your computer and use it in GitHub Desktop.
Save elliotboney/f19db125ef860b431b416315dd611619 to your computer and use it in GitHub Desktop.
Download ZIP
Helps my AI code agents performing story review not mess up so bad.
Raw
qa_rule.md

MANDATORY QA VERIFICATION CHECKLIST

CRITICAL: Complete EVERY step with specific evidence. Skipping any step = INVALID REVIEW

Step 1: Story Scope Verification

  • Read the ENTIRE story file from beginning to end
  • Total number of tasks/subtasks identified: [MUST FILL EXACT NUMBER]
  • List each Acceptance Criteria by identifier/number: [LIST ALL ACs HERE]
  • For each AC, list which specific tasks address it: [CREATE MAPPING]

MANDATORY PAUSE: Before proceeding, state: "I have identified [X] total requirements to verify"

Step 2: Requirement Documentation

Create this table for EVERY requirement:

Requirement # Description (quoted from story) Expected Implementation Status
1 "[Quote exact text]" [What should exist] [FOUND/MISSING]
2 "[Quote exact text]" [What should exist] [FOUND/MISSING]

ANTI-HALLUCINATION CHECK:

  • Re-read story file - did I miss any nested requirements?
  • Are there requirements hidden in AC descriptions I didn't count?
  • Double-check my count: _____ requirements (must match Step 1)

Step 3: Implementation Verification

For EACH requirement marked as FOUND, provide:

  • File location: [Exact file name and path]
  • Evidence: [Quote specific code/content that fulfills requirement]
  • Line numbers: [If applicable]

For EACH requirement marked as MISSING:

  • Expected location: [Where this should have been implemented]
  • Impact: [What functionality is broken/incomplete]

Step 4: File Structure Verification

  • Required files per story: [LIST ALL EXPECTED FILES]
  • Actual files found: [LIST ALL ACTUAL FILES]
  • Missing files: [LIST ANY MISSING FILES]
  • Unexpected files: [LIST ANY EXTRA FILES]

Step 5: Completeness Calculation

  • Total requirements: _____ (from Step 1)
  • Successfully implemented: _____ (from Step 3)
  • Completion percentage: _____% (must be exact calculation)
  • All Acceptance Criteria addressed: YES/NO (provide evidence for each AC)
  • Missing major components (frontend/backend/database/etc.): YES/NO

MANDATORY GATE: If completeness <100%, STOP HERE and mark as INCOMPLETE

Step 6: Reverification Check

Before proceeding to quality review:

  • Re-read the original story file ONE MORE TIME
  • Ask: "What would a fresh developer notice is missing?"
  • Verify: Did any requirements get implemented differently than expected?
  • Confirm: Are there any "between the lines" requirements I missed?

Step 7: Code Quality Review (ONLY if 100% complete)

  • Architecture follows specified patterns: [YES/NO + evidence]
  • Security requirements implemented: [YES/NO + specific checks]
  • Test coverage adequate: [YES/NO + coverage details]
  • Performance considerations addressed: [YES/NO + specific measures]
  • Code follows project standards: [YES/NO + examples]

FINAL STATUS DETERMINATION

Base status on COMPLETENESS first, quality second:

✅ APPROVED: 100% complete + quality issues ≤ minor ❌ CHANGES REQUIRED (Missing Features): <100% complete (regardless of quality) ❌ CHANGES REQUIRED (Quality Issues): 100% complete + significant quality problems

REQUIRED SUMMARY:

  • Implementation completeness: ____%
  • Key missing items: [List if any]
  • Main quality concerns: [List if any]
  • Recommendation: [APPROVED/CHANGES REQUIRED + specific reasoning]

VALIDATION RULES

  • Every checkbox must be completed with specific evidence
  • Every blank (____) must be filled with actual data
  • "YES/NO" questions require supporting evidence
  • If you cannot provide specific evidence for any item, mark as "NEEDS INVESTIGATION"
  • Reviews without complete evidence are INVALID and must be restarted

EMERGENCY BRAKE

If at any point you realize you're making assumptions or can't provide specific evidence, STOP and restart the entire review process.

Raw
review-story.md

review-story

When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.

[[LLM: QA Agent executing review-story task as Senior Developer]]

Prerequisites

  • Story status must be "Review"
  • Developer has completed all tasks and updated the File List
  • All automated tests are passing

Review Process

PHASE 1: MANDATORY COMPLETENESS VERIFICATION

CRITICAL: Complete this systematic verification BEFORE proceeding to senior developer review

  1. Story Scope Documentation

    • Read the ENTIRE story file from beginning to end
    • Total number of tasks/subtasks identified: [MUST FILL EXACT NUMBER]
    • List each Acceptance Criteria by identifier: [LIST ALL ACs HERE]
    • List all major components mentioned (frontend/backend/database/etc.): [LIST HERE]

  2. Task List Cross-Reference

    • Compare File List against story tasks systematically
    • Create verification table for EVERY requirement:
    Task # Description (quoted from story) Expected Files/Components File List Match Status
    1 "[Quote exact text]" [What should exist] [YES/NO] [FOUND/MISSING]

    ANTI-ASSUMPTION CHECK:

    • Re-read story - did I miss any nested requirements?
    • Are there requirements in Dev Notes I didn't account for?
    • Did I check for ALL major components (don't assume partial = complete)?

  3. Implementation Evidence Requirement For EACH task marked FOUND, provide:

    • File location: [Exact file name and path]
    • Evidence: [Quote specific code/content that fulfills requirement]

    For EACH task marked MISSING:

    • Expected location: [Where this should exist]
    • Impact: [What functionality is broken/incomplete]

  4. Completeness Gate Calculation

    • Total tasks: _____ (must match Step 1)
    • Implemented tasks: _____
    • Completion percentage: _____%
    • All major components present: YES/NO (with evidence)

    MANDATORY STOP: If <100% complete, skip to QA Results and mark as INCOMPLETE

PHASE 2: SENIOR DEVELOPER REVIEW

ONLY proceed here if Phase 1 shows 100% completeness

  1. Read the Complete Story

    • Review all acceptance criteria
    • Understand the dev notes and requirements
    • Note any completion notes from the developer

  2. Verify Implementation Against Dev Notes Guidance

    • Review the "Dev Notes" section for specific technical guidance provided to the developer
    • Verify the developer's implementation follows the architectural patterns specified in Dev Notes
    • Check that file locations match the project structure guidance in Dev Notes
    • Confirm any specified libraries, frameworks, or technical approaches were used correctly
    • Validate that security considerations mentioned in Dev Notes were implemented

  3. Focus on the File List

    • Verify all files listed were actually created/modified
    • Check for any missing files that should have been updated
    • Ensure file locations align with the project structure guidance from Dev Notes

  4. Senior Developer Code Review

    • Review code with the eye of a senior developer
    • If changes form a cohesive whole, review them together
    • If changes are independent, review incrementally file by file
    • Focus on:
      • Code architecture and design patterns
      • Refactoring opportunities
      • Code duplication or inefficiencies
      • Performance optimizations
      • Security concerns
      • Best practices and patterns

  5. Active Refactoring

    • As a senior developer, you CAN and SHOULD refactor code where improvements are needed
    • When refactoring:
      • Make the changes directly in the files
      • Explain WHY you're making the change
      • Describe HOW the change improves the code
      • Ensure all tests still pass after refactoring
      • Update the File List if you modify additional files

  6. Standards Compliance Check

    • Verify adherence to docs/coding-standards.md
    • Check compliance with docs/unified-project-structure.md
    • Validate testing approach against docs/testing-strategy.md
    • Ensure all guidelines mentioned in the story are followed

  7. Acceptance Criteria Validation

    • Verify each AC is fully implemented
    • Check for any missing functionality
    • Validate edge cases are handled

  8. Test Coverage Review

    • Ensure unit tests cover edge cases
    • Add missing tests if critical coverage is lacking
    • Verify integration tests (if required) are comprehensive
    • Check that test assertions are meaningful
    • Look for missing test scenarios

  9. Documentation and Comments

    • Verify code is self-documenting where possible
    • Add comments for complex logic if missing
    • Ensure any API changes are documented

Update Story File - QA Results Section ONLY

CRITICAL: You are ONLY authorized to update the "QA Results" section of the story file. DO NOT modify any other sections.

After review and any refactoring, append your results to the story file in the QA Results section:

## QA Results

### Review Date: [Date]
### Reviewed By: Quinn (Senior Developer QA)

### COMPLETENESS VERIFICATION
**Total Tasks Identified:** [X]
**Tasks Implemented:** [Y] 
**Completion Rate:** [Y/X]%

**Task Verification Table:**
[Include the table from Phase 1 with all evidence]

**Missing Components/Tasks:**
[List any missing items with specific explanations, or "NONE" if complete]

**Major Components Check:**
- Frontend: [✓/✗] [evidence/explanation]
- Backend: [✓/✗] [evidence/explanation]  
- Database: [✓/✗] [evidence/explanation]
- [Other components as applicable]

### Code Quality Assessment
[Overall assessment of implementation quality - only if 100% complete]

### Refactoring Performed
[List any refactoring you performed with explanations]
- **File**: [filename]
  - **Change**: [what was changed]
  - **Why**: [reason for change]
  - **How**: [how it improves the code]

### Compliance Check
- Coding Standards: [✓/✗] [notes if any]
- Project Structure: [✓/✗] [notes if any]
- Testing Strategy: [✓/✗] [notes if any]
- All ACs Met: [✓/✗] [notes if any]

### Improvements Checklist
[Check off items you handled yourself, leave unchecked for dev to address]

- [x] Refactored user service for better error handling (services/user.service.ts)
- [x] Added missing edge case tests (services/user.service.test.ts)
- [ ] Consider extracting validation logic to separate validator class
- [ ] Add integration test for error scenarios
- [ ] Update API documentation for new error codes

### Security Review
[Any security concerns found and whether addressed]

### Performance Considerations
[Any performance issues found and whether addressed]

### Final Status
[✓ Approved - Ready for Done] / [✗ Changes Required - INCOMPLETE STORY] / [✗ Changes Required - See unchecked items above]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment