> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# QA Agent (Quinn)

> Test Architect & Quality Advisor - Comprehensive Quality Assurance

## Overview

**Quinn the Guardian** is your test architect with quality advisory authority. The QA agent provides thorough quality assessment through test architecture review, risk analysis, and advisory gates—without blocking progress.

<Card title="When to Use @qa" icon="lightbulb">
  * Reviewing completed stories before merge
  * Running quality gate decisions
  * Designing comprehensive test strategies
  * Validating non-functional requirements
  * Creating automated test suites
</Card>

## Agent Profile

| Attribute     | Value                                             |
| ------------- | ------------------------------------------------- |
| **Name**      | Quinn                                             |
| **Archetype** | Guardian ♍ (Virgo)                                |
| **Role**      | Test Architect with Quality Advisory Authority    |
| **Style**     | Comprehensive, systematic, advisory, educational  |
| **Focus**     | Test architecture, risk assessment, quality gates |

## Key Responsibilities

<AccordionGroup>
  <Accordion title="Quality Review">
    * Comprehensive story review with gate decision
    * CodeRabbit automated scanning (CRITICAL/HIGH/MEDIUM/LOW)
    * Requirements traceability mapping (Given-When-Then)
    * NFR validation (security, performance, reliability)
    * Testability assessment (controllability, observability)
  </Accordion>

  <Accordion title="Test Strategy">
    * Design comprehensive test scenarios
    * Map requirements to tests using Given-When-Then
    * Create test suites for stories (Authority: QA owns test suites)
    * Risk-based testing (probability × impact)
    * Validate test coverage and gaps
  </Accordion>

  <Accordion title="Quality Gates">
    * PASS: All criteria met, ready to merge
    * CONCERNS: Issues noted but not blocking
    * FAIL: Critical issues require fixing
    * WAIVED: Issues accepted with documented risk
  </Accordion>

  <Accordion title="Enhanced Validation (Auto-Claude)">
    * Library validation via Context7
    * 8-point security checklist
    * Database migration validation
    * Evidence-based QA requirements
    * False positive detection for bug fixes
    * Browser console error detection
  </Accordion>

  <Accordion title="Story File Permissions">
    **ONLY update QA Results section**

    **DO NOT modify:** Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Testing, Dev Agent Record, Change Log
  </Accordion>
</AccordionGroup>

## Available Commands

### Code Review & Analysis

<CardGroup cols={2}>
  <Card title="*code-review" icon="magnifying-glass-chart">
    **Run automated review**

    ```bash theme={null}
    *code-review uncommitted
    *code-review committed
    ```

    Executes CodeRabbit scan on specified scope
  </Card>

  <Card title="*review" icon="clipboard-check">
    **Comprehensive story review**

    ```bash theme={null}
    *review story-1.2.3
    ```

    Full quality analysis with gate decision
  </Card>

  <Card title="*review-build" icon="gears">
    **10-phase structured QA review**

    ```bash theme={null}
    *review-build story-1.2.3
    ```

    Epic 6: Outputs `qa_report.md`
  </Card>
</CardGroup>

### Quality Gates

<CardGroup cols={2}>
  <Card title="*gate" icon="door-open">
    **Execute quality gate decision**

    ```bash theme={null}
    *gate story-1.2.3
    ```

    Creates gate decision: PASS/CONCERNS/FAIL/WAIVED
  </Card>

  <Card title="*nfr-assess" icon="shield-halved">
    **Validate non-functional requirements**

    ```bash theme={null}
    *nfr-assess story-1.2.3
    ```

    Security, performance, reliability validation
  </Card>

  <Card title="*risk-profile" icon="triangle-exclamation">
    **Generate risk assessment matrix**

    ```bash theme={null}
    *risk-profile story-1.2.3
    ```

    Probability × Impact analysis
  </Card>

  <Card title="*create-fix-request" icon="wrench">
    **Generate QA\_FIX\_REQUEST.md**

    ```bash theme={null}
    *create-fix-request story-1.2.3
    ```

    Creates fix request for @dev with issues
  </Card>
</CardGroup>

### Enhanced Validation

<CardGroup cols={2}>
  <Card title="*validate-libraries" icon="books">
    **Context7 library validation**

    ```bash theme={null}
    *validate-libraries story-1.2.3
    ```

    Validate third-party library usage
  </Card>

  <Card title="*security-check" icon="lock">
    **8-point security scan**

    ```bash theme={null}
    *security-check story-1.2.3
    ```

    Comprehensive security vulnerability scan
  </Card>

  <Card title="*validate-migrations" icon="database">
    **Database migration validation**

    ```bash theme={null}
    *validate-migrations story-1.2.3
    ```

    Validate schema changes for safety
  </Card>

  <Card title="*evidence-check" icon="clipboard-list">
    **Evidence-based QA verification**

    ```bash theme={null}
    *evidence-check story-1.2.3
    ```

    Verify evidence requirements met
  </Card>

  <Card title="*false-positive-check" icon="bug">
    **Critical thinking for bug fixes**

    ```bash theme={null}
    *false-positive-check story-1.2.3
    ```

    Detect false positive bug claims
  </Card>

  <Card title="*console-check" icon="terminal">
    **Browser console error detection**

    ```bash theme={null}
    *console-check story-1.2.3
    ```

    Scan browser console for errors
  </Card>
</CardGroup>

### Test Strategy

<CardGroup cols={2}>
  <Card title="*test-design" icon="flask">
    **Create comprehensive test scenarios**

    ```bash theme={null}
    *test-design story-1.2.3
    ```

    Design test strategy and scenarios
  </Card>

  <Card title="*trace" icon="diagram-project">
    **Map requirements to tests**

    ```bash theme={null}
    *trace story-1.2.3
    ```

    Given-When-Then traceability mapping
  </Card>

  <Card title="*create-suite" icon="list-check">
    **Create test suite for story**

    ```bash theme={null}
    *create-suite story-1.2.3
    ```

    Authority: QA owns test suites
  </Card>

  <Card title="*critique-spec" icon="comment-dots">
    **Review and critique specification**

    ```bash theme={null}
    *critique-spec story-1.2.3
    ```

    Assess spec completeness and clarity
  </Card>
</CardGroup>

### Backlog Management

<CardGroup cols={3}>
  <Card title="*backlog-add" icon="plus">
    ```bash theme={null}
    *backlog-add story-1.2.3 tech-debt HIGH "Refactor auth"
    ```
  </Card>

  <Card title="*backlog-update" icon="pen">
    ```bash theme={null}
    *backlog-update item-123 resolved
    ```
  </Card>

  <Card title="*backlog-review" icon="list">
    ```bash theme={null}
    *backlog-review
    ```

    Generate backlog review for sprint
  </Card>
</CardGroup>

## Quality Review Workflow

### Standard Review Process

```mermaid theme={null}
graph TD
    A[@dev marks Ready for Review] --> B[*review story-1.2.3]
    B --> C[CodeRabbit scan automatically runs]
    C --> D{CRITICAL issues?}
    D -->|Yes| E[Self-Healing: Auto-fix attempts]
    E --> F{Fixed after 3 iterations?}
    F -->|No| G[FAIL gate decision]
    F -->|Yes| H[Manual analysis]
    D -->|No| H
    H --> I[Check acceptance criteria]
    I --> J[Validate test coverage]
    J --> K[NFR assessment]
    K --> L{Gate decision}
    L -->|PASS| M[Approve - ready to merge]
    L -->|CONCERNS| N[Document concerns, allow merge]
    L -->|FAIL| O[Create fix request for @dev]
    L -->|WAIVED| P[Document risk, allow merge]
```

### CodeRabbit Self-Healing

```yaml theme={null}
Full Self-Healing Loop (Story 6.3.3):
  trigger: review_start
  max_iterations: 3
  timeout_minutes: 30
  severity_filter: [CRITICAL, HIGH]
  
  WHILE iteration < 3:
    1. Run: CodeRabbit --base main
    2. Filter: CRITICAL and HIGH issues
    
    IF no CRITICAL/HIGH issues:
      - Create tech debt for MEDIUM issues
      - Log: "✅ QA passed"
      - BREAK
    
    IF CRITICAL or HIGH issues:
      - Auto-fix each CRITICAL issue
      - Auto-fix each HIGH issue
      - iteration++
      - CONTINUE
  
  IF iteration == 3 AND issues remain:
    - Generate detailed QA gate report
    - Set gate decision: FAIL
    - HALT - require human intervention
```

## Gate Decision Matrix

<Accordion title="PASS - Ready to Merge">
  **Criteria:**

  * All acceptance criteria met
  * No CRITICAL or HIGH CodeRabbit issues
  * Test coverage adequate
  * NFRs validated
  * No blocking security concerns

  **Action:** Approve for merge
</Accordion>

<Accordion title="CONCERNS - Merge with Notes">
  **Criteria:**

  * Acceptance criteria met
  * Minor issues or tech debt identified
  * MEDIUM severity issues
  * Non-blocking improvements needed

  **Action:** Document concerns, allow merge, create follow-up items
</Accordion>

<Accordion title="FAIL - Requires Fixing">
  **Criteria:**

  * CRITICAL CodeRabbit issues remain
  * Acceptance criteria not met
  * Failing tests
  * Security vulnerabilities
  * Major NFR violations

  **Action:** Block merge, create `QA_FIX_REQUEST.md`, send back to @dev
</Accordion>

<Accordion title="WAIVED - Documented Risk">
  **Criteria:**

  * Known issues accepted by stakeholders
  * Technical debt approved for later fix
  * Risk documented and understood

  **Action:** Document waiver reason, allow merge, create tracking issue
</Accordion>

## CodeRabbit Integration

### Severity Handling

| Severity     | Action                           | Focus                                                                  |
| ------------ | -------------------------------- | ---------------------------------------------------------------------- |
| **CRITICAL** | Block story completion           | Security vulnerabilities, data integrity risks, critical anti-patterns |
| **HIGH**     | Report in QA gate, recommend fix | Performance bottlenecks, scalability issues, major anti-patterns       |
| **MEDIUM**   | Document as technical debt       | Code maintainability, design patterns, developer experience            |
| **LOW**      | Optional improvements            | Style consistency, minor optimizations                                 |

### Commands

```bash theme={null}
# Pre-review uncommitted
wsl bash -c 'cd ${PROJECT_ROOT} && ~/.local/bin/coderabbit --prompt-only -t uncommitted'

# Story review committed (vs main)
wsl bash -c 'cd ${PROJECT_ROOT} && ~/.local/bin/coderabbit --prompt-only -t committed --base main'
```

## Git Restrictions

<Warning>
  **@qa is READ-ONLY for git operations**

  * ✅ `git status`, `git log`, `git diff` (review only)
  * ✅ `git branch -a` (list branches)
  * ❌ `git push` (ONLY @github-devops)
  * ❌ `git commit` (QA reviews, doesn't commit)
  * ❌ `gh pr create` (ONLY @github-devops)
</Warning>

**Redirect message:** "QA provides advisory review only. For git operations, use appropriate agent (@dev for commits, @github-devops for push)"

## Collaboration

### Receives work from:

* **@dev (Dex)** - Reviews code and provides feedback

### Delegates to:

* **@dev (Dex)** - Sends back via `*create-fix-request` if FAIL

### Collaborates with:

* **CodeRabbit** - Automated code review integration

## Usage Examples

<CodeGroup>
  ```bash Standard Review theme={null}
  @qa
  *review story-1.2.3
  # Full quality analysis with gate decision
  ```

  ```bash Security Check theme={null}
  @qa
  *security-check story-1.2.3
  # 8-point security vulnerability scan
  ```

  ```bash Create Fix Request theme={null}
  @qa
  *create-fix-request story-1.2.3
  # Generate QA_FIX_REQUEST.md for @dev
  ```

  ```bash Test Design theme={null}
  @qa
  *test-design story-1.2.3
  # Create comprehensive test scenarios
  ```
</CodeGroup>

## Common Pitfalls

<Warning>
  **Avoid these common mistakes:**

  * ❌ Reviewing before CodeRabbit scan completes
  * ❌ Modifying story sections outside QA Results
  * ❌ Skipping non-functional requirement checks
  * ❌ Not documenting concerns in gate file
  * ❌ Approving without verifying test coverage
</Warning>

## Related Agents

<CardGroup cols={3}>
  <Card title="@dev (Dex)" icon="code" href="/agents/dev">
    Receives feedback from @qa
  </Card>

  <Card title="@sm (River)" icon="wave" href="/agents/sm">
    May request risk profiling from @qa
  </Card>

  <Card title="CodeRabbit" icon="rabbit">
    Automated pre-review integration
  </Card>
</CardGroup>