---
name: scorpio-qa-rework
description: Review QA findings, classify issues, and generate rework tasks for scorpio-execute. Use after scorpio-qa-final produces a QA report to decide what needs fixing and what can be deferred.
---

# QA Rework Task Generator

A structured methodology for reviewing QA findings and converting them into actionable rework tasks. This skill acts as the product/quality decision-maker — determining what must be fixed, what can be deferred, and what is acceptable.

## Prerequisites

Before triaging, you need:
- QA report(s) from **scorpio-qa-final**
- Original task specification(s) for context
- Access to the task index for dependency management

If no QA report exists, use **scorpio-qa-final** first.

## Triage Process

```
Step 1: Review      → Read QA report and original task spec
Step 2: Classify    → Categorize each finding
Step 3: Decide      → Accept, rework, or defer each item
Step 4: Generate    → Create rework tasks for scorpio-execute
Step 5: Update      → Update task index and QA report with decisions
```

## Step 1: Review

Read the QA report alongside the original task spec:

- Understand each finding in context of the original requirements
- Verify findings are legitimate (not false positives)
- Check if any findings are duplicates or stem from the same root issue
- Note which acceptance criteria passed and which failed

## Step 2: Classify Each Finding

| Classification | Criteria | Action |
|---------------|----------|--------|
| **Must Fix** | Critical/High severity, or acceptance criterion failed | Generate rework task |
| **Should Fix** | Medium severity, clear quality improvement | Generate rework task (lower priority) |
| **Defer** | Low severity, cosmetic, or beyond original task scope | Log for future work |
| **Won't Fix** | Not a real issue, acceptable trade-off, or by design | Document rationale and close |
| **Investigate** | Unclear root cause, needs more information | Generate spike task |

## Step 3: Decision Framework

### Must Fix — No Debate

These always require rework tasks:
- Any failed acceptance criterion
- Critical severity findings (security vulnerabilities, data loss, crashes)
- High severity findings that break user-facing functionality
- Quality gate failures (lint, typecheck, tests, build)

### Judgment Call — Consider Context

Weigh these factors for Medium severity findings:
- **Project phase**: Pre-launch is stricter than post-launch iteration
- **User impact**: Visible to end users vs. internal/developer-facing
- **Workaround exists**: Can users accomplish the task another way?
- **Systemic vs. isolated**: One-off issue vs. pattern that will spread
- **Fix cost**: Quick fix vs. requires architectural change

### Defer — Don't Block

These should not generate rework tasks:
- Low severity cosmetic issues (minor alignment, color shade)
- Improvements beyond the original task scope
- Findings that require architectural changes outside the feature
- Style preferences that don't violate project conventions

### Won't Fix — Document Why

Always document the rationale:
```markdown
**Finding**: CR-005 — Variable naming could be more descriptive
**Decision**: Won't Fix
**Rationale**: Follows existing codebase convention in this module. Renaming would
create inconsistency with adjacent code. Would require a separate refactor task.
```

### Decision Template

```markdown
## Triage Decisions

| Finding | Severity | Classification | Rationale |
|---------|----------|---------------|-----------|
| CR-001 | Critical | Must Fix | Security: unvalidated user input |
| CR-002 | Medium | Defer | Cosmetic naming, not blocking |
| UI-001 | High | Must Fix | Submit button non-functional, AC-2 fails |
| UI-002 | Low | Won't Fix | Minor alignment, within acceptable range |
| CR-003 | Medium | Should Fix | Missing error message for edge case |
```

## Step 4: Generate Rework Tasks

### Rework Task Format

Generate tasks compatible with **scorpio-execute**:

```markdown
## REWORK-[ORIGINAL-TASK-ID]-[N] [Fix Title]

**Type**: Bug
**Priority**: [Mapped from finding severity]
**Estimate**: [Based on fix complexity]
**Dependencies**: None (original task already complete)

**Original Task**: [TASK-ID]
**QA Report**: [path to QA report]
**QA Finding(s)**: [FINDING-ID(s)]

### Description
[What needs to be fixed and why, referencing the QA finding]

### Root Cause
[From the QA finding — file location, code snippet, explanation]

### Fix Approach
[Specific steps to resolve the issue]

### Files to Modify
- `path/to/file.ts:line` - [what to change]

### Acceptance Criteria
- [ ] [Original failing AC] now passes
- [ ] [Specific fix verified — describe the expected behavior]
- [ ] No regression in existing functionality
- [ ] Quality gates pass (lint, typecheck, tests, build)

### Technical Notes
- Original implementation: [reference to changed files]
- QA report: [path to QA report]
- Watch out for: [any gotchas from the QA finding]
```

### Priority Mapping

| Finding Severity | Rework Priority |
|-----------------|-----------------|
| Critical | P0 — Fix immediately |
| High | P1 — Fix before next QA pass |
| Medium (Must Fix) | P2 — Fix in current cycle |
| Medium (Should Fix) | P3 — Fix if time permits |

### Grouping Related Fixes

If multiple findings stem from the same root issue, combine into one rework task:

```markdown
## REWORK-UI-002-1 Fix form validation and error handling

**QA Finding(s)**: CR-003, UI-001, UI-004

### Description
All three findings stem from missing input validation in the form submit handler.
The handler assumes all fields are present and valid, causing a crash when fields
are empty (CR-003), no error message for the user (UI-001), and incorrect state
after failed submission (UI-004).
```

### Estimate Guidelines for Rework

| Fix Type | Typical Estimate |
|----------|-----------------|
| Missing null/validation check | XS |
| Error message or UI state fix | S |
| Logic error in business code | S-M |
| Security vulnerability patch | M |
| Missing test coverage | S |
| Architectural or design issue | L (consider deferring) |

## Step 5: Update Artifacts

### Update Task Index

Add rework tasks to the task index:

```markdown
## Rework Tasks (QA Cycle [N])

| ID | Task | Priority | Depends | Source Finding |
|----|------|----------|---------|----------------|
| REWORK-CORE-001-1 | Fix null check in save handler | P0 | - | QA-CORE-001 CR-001 |
| REWORK-UI-002-1 | Fix form validation | P1 | - | QA-UI-002 UI-001 |
```

### Update QA Report

Append triage decisions to the original QA report:

```markdown
## Triage Results

**Triaged by**: QA PM
**Date**: [date]

| Finding | Decision | Rework Task |
|---------|----------|-------------|
| CR-001 | Must Fix | REWORK-CORE-001-1 |
| CR-002 | Defer | — (logged for v2) |
| UI-001 | Must Fix | REWORK-UI-002-1 |
| UI-002 | Won't Fix | — (acceptable, see rationale) |

**Next action**: Execute rework tasks via scorpio-execute
```

## Rework Loop Management

### The QA Cycle

```
scorpio-execute (implement)
    → scorpio-qa-final (review)
        → scorpio-qa-rework (triage)
            → scorpio-execute (rework)
                → scorpio-qa-final (re-review, scoped)
                    → scorpio-qa-rework (verify)
                        → APPROVE or escalate
```

### Preventing Infinite Loops

Track QA cycles per task:

```markdown
### QA Cycle History

| Cycle | Date | Result | Rework Tasks Generated |
|-------|------|--------|------------------------|
| 1 | [date] | FAIL | REWORK-001-1, REWORK-001-2 |
| 2 | [date] | PASS WITH NOTES | None (deferred items only) |
```

**Rules:**
- **Max 3 QA cycles** per task — after 3, escalate to the user for a decision
- Rework re-QA is **scoped to the rework changes only** (don't re-review the entire original task)
- Deferred items from prior cycles don't count as failures in subsequent cycles
- If the same finding recurs after rework, escalate severity by one level

### Re-QA Scope

When scorpio-qa-final re-reviews after rework:

1. Verify the specific finding is resolved
2. Check for regressions in directly related functionality
3. Don't repeat the full QA pass — focus on rework changes
4. Use a lighter report format:

```markdown
## Re-QA Report: REWORK-CORE-001-1

### Original Finding: CR-001
**Status**: RESOLVED
**Evidence**: [how it was verified]

### Regression Check
**Status**: NO REGRESSIONS
**Checked**: [what was verified]

### Result: PASS
```

## Triage Summary Format

After triaging all findings from a QA session, produce a summary:

```markdown
# QA Triage Summary

## Overview
- **Tasks reviewed**: [N]
- **Total findings**: [N]
- **Must Fix**: [N] → [N] rework tasks generated
- **Should Fix**: [N] → [N] rework tasks generated
- **Deferred**: [N]
- **Won't Fix**: [N]

## Rework Required

| Rework Task | Priority | Original Task | Findings Addressed |
|-------------|----------|---------------|--------------------|
| REWORK-001-1 | P0 | CORE-001 | CR-001 |
| REWORK-002-1 | P1 | UI-002 | UI-001, CR-003 |

## Deferred Items

| Finding | Reason | Revisit When |
|---------|--------|--------------|
| CR-002 | Cosmetic naming | v2 planning |
| UI-003 | Minor alignment | Design system refresh |

## Next Action
[Execute rework tasks via scorpio-execute | All tasks approved — ready to ship]
```

## Rework File Organization

```
docs/
├── tasks/
│   ├── TASK-INDEX.md
│   ├── CORE-001.md
│   ├── rework/
│   │   ├── REWORK-CORE-001-1.md
│   │   └── REWORK-UI-002-1.md
│   ├── done/
│   │   ├── CORE-001.md
│   │   └── REWORK-CORE-001-1.md
│   └── qa-reports/
│       ├── QA-CORE-001.md
│       ├── QA-UI-002.md
│       └── REQA-REWORK-CORE-001-1.md
```

## What NOT To Do

- Do not classify Critical findings as "Defer" or "Won't Fix"
- Do not generate vague rework tasks ("Fix the issues found in QA")
- Do not skip documenting rationale for Won't Fix decisions
- Do not allow infinite QA cycles without escalation (max 3)
- Do not expand rework task scope beyond the original finding
- Do not block shipping solely on Low-severity cosmetic issues
- Do not make code changes during triage — fixes go through scorpio-execute
- Do not ignore patterns across findings (3 similar issues = systemic problem)

## Skill Chain

This skill completes the QA feedback loop in all three workflows:

### Project Planning Workflow
```
scorpio-project-intake → scorpio-project-artifacts → scorpio-task-plan → scorpio-execute → scorpio-qa-final → scorpio-qa-rework → (rework loop)
```

### Feature Development Workflow
```
scorpio-feature-intake → scorpio-feature-plan → scorpio-execute → scorpio-qa-final → scorpio-qa-rework → (rework loop)
```

### Bug Fixing Workflow
```
scorpio-bug-intake → scorpio-bug-investigate → scorpio-execute → scorpio-qa-final → scorpio-qa-rework → (rework loop)
```

## Next Steps

After generating rework tasks:
1. Use **scorpio-execute** to execute each rework task
2. Use **scorpio-qa-final** to re-QA the rework (scoped to changes)
3. Return to **scorpio-qa-rework** to verify fixes
4. Once all tasks pass: approve and ship