apply-qa-fixes

Installation

SKILL.md

Apply QA Fixes

Systematically consume QA quality gate outputs and apply prioritized fixes for issues identified during quality review.

Purpose

After Quinn's quality review creates a quality gate with CONCERNS or FAIL status, this skill enables James to systematically consume the findings and apply fixes in a deterministic, prioritized manner.

Core Principles:

Deterministic prioritization - Always same priority order (high severity → NFR failures → coverage gaps)
Minimal changes - Fix exactly what's in the gate, don't over-engineer
Validation loop - Always run tests after fixes, iterate until clean
Observability - Track all fixes applied, tests added, coverage improvement

Integration:

Input: Quality gate YAML + assessment reports from Quinn
Processing: Parse findings → Build fix plan → Apply fixes → Validate
Output: Fixed code + updated task file + telemetry

When to Use This Skill

This skill should be used when:

Quality gate status is CONCERNS or FAIL
Quinn has identified specific issues requiring fixes
Task is in Review status with completed implementation

This skill should NOT be used when:

Quality gate is PASS (no fixes needed)
Quality gate is WAIVED (intentionally accepted)
Task implementation is incomplete
Issues require architectural changes (escalate to user)

Prerequisites

Task file exists at .claude/tasks/{task-id}.md
Quality gate exists at .claude/quality/gates/{task-id}-gate-{date}.yaml
Assessment reports exist in .claude/quality/assessments/
bmad-commands skill available
Tests can be executed

Workflow

Step 0: Load Configuration and Quality Gate

Purpose: Load project configuration, locate task file, find latest quality gate, verify readiness.

Actions:

Load Configuration:

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path .claude/config.yaml \
  --output json

Parse configuration to extract:

Quality directory paths
Test framework
Coverage thresholds

Load Task File:
```
python .claude/skills/bmad-commands/scripts/read_file.py \
  --path .claude/tasks/{task_id}.md \
  --output json
```
Verify task is ready for fixes:
- Status is "Review" or "InProgress"
- Implementation Record section exists
- Quality Review section exists (from Quinn)
Locate Latest Quality Gate:

Search .claude/quality/gates/ for latest gate file:
- Pattern: {task-id}-gate-{date}.yaml
- Select most recent by date
- Verify gate status is CONCERNS or FAIL
Load Quality Gate:
```
python .claude/skills/bmad-commands/scripts/read_file.py \
  --path .claude/quality/gates/{gate_file} \
  --output json
```
Parse gate YAML structure:
- decision - Gate status (PASS/CONCERNS/FAIL/WAIVED)
- overall_score - Quality score (0-100)
- dimensions - Quality dimension scores
- top_issues - High/medium/low severity issues
- nfr_validation - NFR assessment results
- trace - Traceability gaps
- test_design - Test coverage gaps
- action_items - Recommended actions

Halt if:

Configuration missing
Task file not found
Quality gate not found
Gate status is PASS or WAIVED (no fixes needed)

See: references/templates.md for gate schema and configuration format

Step 1: Parse QA Findings

Purpose: Extract all issues from quality gate and assessment reports.

Actions:

Parse Top Issues from Gate:

From gate.yaml:
```
top_issues:
  - id: "SEC-001"
    category: "security"
    severity: "high"
    description: "Missing input validation on user endpoint"
    location: "src/api/user.ts:45"
    recommendation: "Add Joi validation schema"
```
Categorize by severity:
- High severity - Security vulnerabilities, data loss risks, critical bugs
- Medium severity - Performance issues, reliability concerns, code quality
- Low severity - Minor improvements, style issues, warnings

Parse NFR Failures:

From gate.nfr_validation:

nfr_validation:
  security:
    status: "FAIL"
    score: 45
    concerns:
      - "Missing SQL parameterization (src/db/queries.ts:23)"
      - "No rate limiting on API endpoints"

Extract:

FAIL statuses (must fix)
CONCERNS (should fix)
Specific locations and recommendations

Parse Test Coverage Gaps:

From gate.test_design.coverage_gaps:

coverage_gaps:
  - ac_id: "AC2"
    description: "User authentication flow"
    missing_tests:
      - "Should reject invalid credentials"
      - "Should handle expired tokens"

Parse Traceability Gaps:

From gate.trace.ac_gaps:

ac_gaps:
  - ac_id: "AC4"
    description: "Secure password storage"
    coverage: "partial"
    missing: ["bcrypt hashing not implemented"]

Outputs:

high_severity_issues[] - List of high severity issues with locations
medium_severity_issues[] - List of medium severity issues
low_severity_issues[] - List of low severity issues
nfr_failures[] - NFR FAIL statuses with fixes needed
nfr_concerns[] - NFR CONCERNS with recommended fixes
coverage_gaps[] - Test scenarios to add
trace_gaps[] - Uncovered acceptance criteria

See: references/templates.md for full gate schema and parsing examples

Step 2: Build Fix Plan (Priority Order)

Purpose: Create deterministic, prioritized fix plan ensuring critical issues addressed first.

Priority Rules:

Priority 1: High Severity Issues (security, data loss, critical bugs)
Priority 2: NFR Failures (status = FAIL)
Priority 3: Test Coverage Gaps (P0 scenarios from test-design)
Priority 4: NFR Concerns (status = CONCERNS)
Priority 5: Traceability Gaps (uncovered ACs)
Priority 6: Medium Severity Issues
Priority 7: Low Severity Issues

Within Same Priority:

Security > Performance > Reliability > Maintainability
Alphabetical by issue ID

Actions:

Build Priority List:

fix_plan = [
  // Priority 1: High severity
  { priority: 1, issue_id: "SEC-001", type: "security", ... },
  { priority: 1, issue_id: "SEC-002", type: "security", ... },

  // Priority 2: NFR failures
  { priority: 2, issue_id: "NFR-SEC-001", type: "nfr_fail", ... },

  // Priority 3: Coverage gaps
  { priority: 3, issue_id: "TEST-001", type: "coverage_gap", ac_id: "AC2", ... },

  // ... continue for all priorities
]

Calculate Impact:

For each fix, estimate:
- Files to modify
- Diff lines expected
- Tests to add
- Total effort
Check Guardrails:

Verify fix plan doesn't exceed James's guardrails:
- Max 10 files per fix session
- Max 800 diff lines
- If exceeded, split into multiple fix sessions or escalate

Present Fix Plan to User:

=== Fix Plan ===

Total Issues: 15

Priority 1 (High Severity): 3 issues
- SEC-001: Missing input validation (src/api/user.ts)
- SEC-002: SQL injection risk (src/db/queries.ts)
- PERF-001: N+1 query issue (src/services/data.ts)

Priority 2 (NFR Failures): 2 issues
- NFR-SEC-001: No rate limiting
- NFR-REL-001: Missing error logging

Priority 3 (Coverage Gaps): 5 tests to add
- AC2: User authentication flow (2 tests)
- AC4: Secure password storage (3 tests)

Estimated Impact:
- Files to modify: 8
- Tests to add: 5
- Expected diff: ~600 lines

Proceed with fixes? (y/n)

Outputs:

fix_plan[] - Ordered list of fixes to apply
estimated_impact{} - Files, lines, tests
guardrail_check{} - Pass/fail status

See: references/priority-rules.md for detailed priority logic and references/examples.md for fix plan examples

Step 3: Apply Fixes

Purpose: Apply fixes from plan using bmad-commands primitives and Claude Code tools.

Actions:

For each fix in fix_plan (in priority order):

Load Affected Files:

Use Claude Code Read tool to load files needing modification:
```
Read: src/api/user.ts
Read: tests/api/user.test.ts
```
Apply Code Fix:

Use Claude Code Edit tool to apply fix:
```
Edit: src/api/user.ts
Old: const user = await db.query(`SELECT * FROM users WHERE id = ${userId}`)
New: const user = await db.query('SELECT * FROM users WHERE id = ?', [userId])
```
Principles:
- Minimal changes (fix exactly what's specified)
- Follow project patterns (maintain consistency)
- Add comments where needed (explain security fixes)
- No over-engineering (don't refactor unrelated code)

Add Missing Tests:

Use Claude Code Write tool to add test files:

Write: tests/api/user-auth.test.ts
Content: [Test scenarios from coverage_gaps]

Use Edit tool to add tests to existing files:

Edit: tests/api/user.test.ts
Add tests for:
- Should reject invalid credentials
- Should handle expired tokens

Track Progress:

Update todo list as fixes applied:

✅ Fix 1/15: Added input validation (SEC-001)
✅ Fix 2/15: Added SQL parameterization (SEC-002)
⏳ Fix 3/15: Adding rate limiting middleware...

Error Handling:

If fix fails:

Log error with details
Skip to next fix
Report all failures at end
Allow user to review and retry

Outputs:

fixes_applied[] - List of successfully applied fixes
fixes_failed[] - List of failed fixes with errors
files_modified[] - All files changed
tests_added - Count of new tests

See: references/examples.md for fix application examples

Step 4: Validate

Purpose: Run tests and lint to verify fixes don't introduce regressions.

Actions:

Run Lint:

# Lint check (exact command depends on project)
npm run lint
# or
eslint src/

Capture output:

Errors count
Warnings count
Files with issues

Run Tests:

python .claude/skills/bmad-commands/scripts/run_tests.py \
  --path . \
  --framework auto \
  --output json

Parse results:

{
  "success": true,
  "outputs": {
    "passed": true,
    "total_tests": 45,
    "tests_passed": 45,
    "tests_failed": 0,
    "coverage_percent": 89
  }
}

Check Coverage Improvement:

Compare before/after coverage:
- Before: 82% (from quality gate)
- After: 89%
- Improvement: +7%
Iterate if Needed:

If tests fail:
- Identify failing tests
- Debug issues
- Apply additional fixes
- Re-run tests
- Maximum 3 iterations before escalating

Halt if:

Tests still failing after 3 iterations
Lint errors can't be resolved
Coverage decreased (regression)

Outputs:

lint_passed - Boolean
tests_passed - Boolean
coverage_before - Number
coverage_after - Number
coverage_improvement - Number
validation_clean - Boolean

See: references/templates.md for validation report format

Step 5: Update Task File

Purpose: Update task Implementation Record with fix details.

STRICT PERMISSIONS:

AUTHORIZED to update:

Implementation Record section (what fixed, why, how)
File List (add/modified/deleted files)
Status (only if re-review needed: InProgress → Review)

NOT AUTHORIZED to update:

Objective
Acceptance Criteria
Context
Tasks
Quality Review section (that's Quinn's territory)

Actions:

Load Current Task File:

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path .claude/tasks/{task_id}.md \
  --output json

Generate Fix Summary:

### QA Fixes Applied (2025-01-15)

**Quality Gate:** .claude/quality/gates/{task-id}-gate-{date}.yaml
**Status Before:** CONCERNS (72/100)
**Status After:** Ready for re-review

**Fixes Applied (15 total):**

**Priority 1 (High Severity):**
1. SEC-001: Added input validation (src/api/user.ts:45)
2. SEC-002: Added SQL parameterization (src/db/queries.ts:23)
3. PERF-001: Fixed N+1 query (src/services/data.ts:67)

**Priority 2 (NFR Failures):**
4. NFR-SEC-001: Added rate limiting middleware
5. NFR-REL-001: Added error logging and monitoring

**Priority 3 (Coverage Gaps):**
6-10. Added 5 missing tests for AC2, AC4

**Priority 4-7:**
11-15. Addressed medium/low severity issues

**Validation Results:**
- ✅ Lint: 0 problems
- ✅ Tests: 45/45 passed
- ✅ Coverage: 82% → 89% (+7%)

**Files Modified:**
- src/api/user.ts
- src/db/queries.ts
- src/services/data.ts
- src/middleware/rate-limit.ts (new)
- tests/api/user.test.ts
- tests/api/user-auth.test.ts (new)
- tests/db/queries.test.ts

**Next Steps:**
- Ready for Quinn re-review: @quinn *review {task-id}

Update Implementation Record:

Use Edit tool to append fix summary to Implementation Record section:
```
Edit: .claude/tasks/{task-id}.md
Section: Implementation Record
Action: Append QA fix summary
```
Update File List:

Add newly created/modified files to task file list.
Update Status (if needed):

If fixes require re-review:
- Status: Review (keep in review)
- Or Status: InProgress → Review (if was moved out of review)

Outputs:

task_updated - Boolean
fix_summary - Markdown text

See: references/templates.md for task update template

Step 6: Emit Telemetry

Purpose: Track metrics for observability and learning.

Actions:

Emit structured telemetry:

{
  "event": "skill.apply-qa-fixes.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "task_id": "task-001",
    "quality_gate": ".claude/quality/gates/task-001-gate-2025-01-15.yaml",
    "fixes_count": 15,
    "fixes_applied": {
      "high_severity": 3,
      "nfr_failures": 2,
      "coverage_gaps": 5,
      "nfr_concerns": 2,
      "medium_severity": 2,
      "low_severity": 1
    },
    "tests_added": 5,
    "coverage_before": 82,
    "coverage_after": 89,
    "coverage_improvement": 7,
    "files_modified": 7,
    "validation_passed": true,
    "duration_ms": 180000,
    "iterations": 1,
    "fixes_failed": 0
  }
}

Metrics to Track:

Fixes count by priority
Tests added
Coverage improvement
Files modified
Validation success
Duration
Iterations needed
Failed fixes

Use Cases:

Track most common QA issues
Identify patterns in fixes
Measure fix effectiveness
Monitor coverage improvement trends
Optimize fix prioritization

Execution Complete

Skill complete when:

✅ Quality gate loaded and parsed
✅ Fix plan built with deterministic prioritization
✅ All prioritized fixes applied (or documented failures)
✅ Tests added for coverage gaps
✅ Validation clean (lint + tests pass)
✅ Task file updated with fix summary
✅ Telemetry emitted

Integration with James

James Routing:

# In james-developer-v2.md

command: "*apply-qa-fixes"

routing_logic:
  - condition: "high_severity_count > 5 OR nfr_failures > 2"
    guardrails:
      max_files: 10
      max_diff_lines: 800
      require_user_confirmation: true

  - condition: "high_severity_count > 0 OR nfr_failures > 0"
    guardrails:
      max_files: 7
      max_diff_lines: 600

  - condition: "default"
    guardrails:
      max_files: 5
      max_diff_lines: 400

Usage:

# After Quinn review creates gate with CONCERNS/FAIL
@james *apply-qa-fixes task-001

# James:
# ✅ Quality gate loaded: CONCERNS (3 high, 2 medium issues)
# ✅ Fix plan created (5 fixes prioritized)
# ⏳ Applying fixes...
# ✅ All fixes applied
# ✅ Validation passed
# ✅ Task updated
#
# Ready for re-review: @quinn *review task-001

Best Practices

Always validate after fixes - Don't skip test runs
Follow priority rules strictly - Ensures consistency
Minimal changes only - Fix what's specified, no more
Document all fixes - Update Implementation Record
Track failures - Log any fixes that can't be applied
Re-review after fixes - Always have Quinn re-assess

When to Escalate

Escalate to user when:

Fixes exceed guardrails (>10 files, >800 lines)
Fixes require architectural changes
Tests fail after 3 iterations
Security concerns arise during fixes
Breaking API changes required
Conflicting fixes (can't satisfy all issues)

References

references/templates.md - Gate schema, task update template, output formats
references/priority-rules.md - Detailed priority logic and decision rules
references/examples.md - Fix application examples and usage scenarios

Part of BMAD Enhanced Development Suite - Integrates with Quinn (Quality) for complete feedback loop

Related skills

More from adolfoaranaes12/bmad-enhanced

Installs

Repository

adolfoaranaes12…enhanced

GitHub Stars

First Seen

Feb 23, 2026

Security Audits

Gen Agent Trust HubPass

SocketWarn

SnykPass

apply-qa-fixes

Apply QA Fixes

Purpose

When to Use This Skill

Prerequisites

Workflow

Step 0: Load Configuration and Quality Gate

Step 1: Parse QA Findings

Step 2: Build Fix Plan (Priority Order)

Step 3: Apply Fixes

Step 4: Validate

Step 5: Update Task File

Step 6: Emit Telemetry

Execution Complete

Integration with James

Best Practices

When to Escalate

References

More from adolfoaranaes12/bmad-enhanced

analyze-architecture

bmad-commands

create-brownfield-prd

document-project

create-prd

shard-document