| name | spec-driven-qa-remediation |
| description | Process QA gap files and create remediation user stories with structural anti-skip enforcement (Execute-Verify-Gate pattern at every step). Applies per-phase reference loading, checkpoint persistence, and binary CLI gate enforcement to every step of the 7-phase QA remediation process. Prevents token optimization bias through lean orchestration, fresh-context subagent delegation, and artifact verification. Use when converting QA findings into actionable development work, processing imported QA reports, or systematically addressing accumulated technical debt from gap files. Always use this skill when the user runs /review-qa-reports or mentions QA gap remediation, gap-to-story conversion, or technical debt from QA reports.
|
| allowed-tools | ["Read","Write","Edit","Glob","Grep","AskUserQuestion","Task","Skill","Bash(devforgeai-validate:*)"] |
| model | claude-opus-4-7 |
| effort | High |
Spec-Driven QA Remediation
Process QA gap files and create remediation user stories through strict 7-phase workflow with gap discovery, deduplication, prioritization, batch story creation, report generation, and technical debt integration.
Context files are THE LAW: tech-stack.md, source-tree.md, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md
If ambiguous or conflicts detected: HALT and use AskUserQuestion
Execution Model
This skill expands inline. After invocation, execute Phase State Initialization immediately. Do not wait passively, ask permission, or offer execution options.
Self-Check (if ANY box is true = VIOLATION):
IF any box checked: EXECUTION MODEL VIOLATION. Go directly to Phase State Initialization now.
Anti-Skip Enforcement Contract
This skill enforces 4 independent anti-skip layers. ALL FOUR must fail for a step to be skipped:
- Fresh-context subagent execution — Story creation runs in isolated context via spec-driven-stories skill invocation
- Binary CLI gates —
devforgeai-validate phase-check/phase-complete/phase-record --workflow=qa-remediation (compiled, cannot be forged by LLM)
- Hook enforcement — Shell scripts in
.claude/hooks/ run outside LLM control
- Step registry + artifact verification —
.claude/hooks/phase-steps-registry.json tracks every mandatory step
Execute-Verify-Record Pattern: Every mandatory step in every phase file has three parts:
- EXECUTE: The exact action to perform
- VERIFY: How to confirm the action happened (Glob, Grep, exit code, Task result)
- RECORD: CLI command to record completion (
devforgeai-validate phase-record)
Token Optimization Bias is PROHIBITED. Do not skip, compress, or shortcut any step. Every phase step exists because a previous failure proved it necessary.
Purpose
Convert QA gap findings (coverage gaps, anti-pattern violations, code quality issues, deferral problems) into actionable user stories, eliminating technical debt through structured remediation.
When to Use
- After QA validation produces gap files (
*-gaps.json)
- When importing QA reports from external projects
- When systematically addressing accumulated technical debt
- When gaps need to be converted to trackable stories
Philosophy
"Every gap tracked. Every story actionable. Every phase executed."
Parameter Extraction
Extract all parameters from $ARGUMENTS provided by the /review-qa-reports command.
Skills cannot accept runtime parameters. All information extracted from conversation context (command arguments, explicit statements, or file references).
| Argument | Variable | Default | Description |
|---|
--source | $SOURCE | local | Gap file source: local, imports, all |
--min-severity | $MIN_SEVERITY | From config | Filter threshold: CRITICAL, HIGH, MEDIUM, LOW |
--epic | $EPIC_ID | null | Associate created stories with epic |
--dry-run | $DRY_RUN | false | Preview gaps without creating stories |
--add-to-debt | $ADD_TO_DEBT | false | Auto-add deferred gaps to debt register (skip confirmation) |
--create-stories | $CREATE_STORIES | false | Auto-create remediation stories (skip confirmation) |
--blocking-only | $BLOCKING_ONLY | false | Show only blocking gaps, hide advisory |
Flag Routing Context:
$ADD_TO_DEBT=true → Phase 07 skips confirmation prompt$CREATE_STORIES=true → Phase 05 uses batch mode without prompts
Combined Flag Operation (--add-to-debt --create-stories):
When BOTH flags are present, stories are created first, then debt entries are added:
- Phase 05 executes before Phase 07 (stories created first)
- Phase 07 executes SECOND (gaps added to debt register)
- Debt entries have Follow-up field pre-populated with created STORY-XXX IDs
Command Integration
| Context Marker | Set By | Description |
|---|
$ARGUMENTS | /review-qa-reports | Raw command arguments string |
$SESSION_ID | Phase State Init | Generated session identifier |
Phase State Initialization [MANDATORY FIRST]
devforgeai-validate phase-init ${SESSION_ID} --workflow=qa-remediation --project-root=. 2>&1
Generate $SESSION_ID from timestamp: qa-rem-{YYYYMMDD-HHmmss}
| Exit Code | Meaning | Action |
|---|
| 0 | New workflow | State file created. Set CURRENT_PHASE = "01". |
| 1 | Existing workflow | Resume. Run devforgeai-validate phase-status ${SESSION_ID} --workflow=qa-remediation to get CURRENT_PHASE. |
| 2 | Invalid session ID | HALT. |
| 127 | CLI not installed | Continue without enforcement (backward compatibility). |
Resume Detection:
Glob(pattern="devforgeai/workflows/checkpoints/qa-remediation-*.checkpoint.json")
IF checkpoint found:
Read(file_path=checkpoint_path)
AskUserQuestion:
Question: "Found existing QA remediation session. Resume or start fresh?"
Options:
- label: "Resume session"
- label: "Start fresh"
IF "Resume":
Restore state from checkpoint
$CURRENT_PHASE = checkpoint.progress.current_phase
ELSE:
Delete checkpoint, set CURRENT_PHASE = "01"
ELSE:
Set CURRENT_PHASE = "01"
Phase Orchestration Loop
FOR phase_num in [01, 02, 03, 04, 05, 06, 07]:
phase_id = phase_num
IF $DRY_RUN == true AND phase_id > 04:
SKIP remaining phases (dry-run exits after Phase 04)
BREAK
1. ENTRY GATE: devforgeai-validate phase-check ${SESSION_ID} --workflow=qa-remediation --from={prev} --to={phase_id} --project-root=.
IF exit != 0: HALT
2. LOAD: Read(file_path=".claude/skills/spec-driven-qa-remediation/phases/{phase_files[phase_id]}")
Load FRESH - do NOT rely on memory of previous reads
3. EXECUTE: Follow every step in the phase file (EXECUTE-VERIFY-RECORD triplets)
- Each step's EXECUTE instruction tells you exactly what to do
- Each step's VERIFY instruction tells you how to confirm it happened
- Each step's RECORD instruction tells you what CLI command to call
4. RECORD: devforgeai-validate phase-record ${SESSION_ID} --workflow=qa-remediation --phase={phase_id} --project-root=.
5. EXIT GATE: devforgeai-validate phase-complete ${SESSION_ID} --workflow=qa-remediation --phase={phase_id} --checkpoint-passed --project-root=.
IF exit != 0: HALT
| Phase | Name | File |
|---|
| 01 | Pre-Flight Validation | phases/phase-01-preflight.md |
| 02 | Discovery & Parsing | phases/phase-02-discovery-parsing.md |
| 03 | Aggregation & Prioritization | phases/phase-03-aggregation-prioritization.md |
| 04 | Interactive Selection | phases/phase-04-interactive-selection.md |
| 05 | Batch Story Creation | phases/phase-05-batch-story-creation.md |
| 06 | Source Report Update | phases/phase-06-source-report-update.md |
| 07 | Technical Debt Integration | phases/phase-07-technical-debt-integration.md |
Required Subagents Per Phase
| Phase | Required Subagents | Enforcement |
|---|
| 01 | (none) | N/A |
| 02 | (none) | N/A |
| 03 | (none) | N/A |
| 04 | (none) | N/A |
| 05 | spec-driven-stories (Skill) | BLOCKING |
| 06 | (none) | N/A |
| 07 | technical-debt-analyzer | CONDITIONAL (config-driven) |
Deviation Protocol: Any skip requires explicit user consent via AskUserQuestion.
Phase Summaries
Each phase is fully specified in its own file under phases/. The summaries below provide orientation; the phase files are the source of truth.
Phase 01: Pre-Flight Validation (6 steps)
Validate project root, load configuration from devforgeai/config/qa-remediation.yaml, parse 7 arguments, validate flag dependencies, verify source paths exist, create checkpoint.
Reference: None (inline bootstrap)
Key Outputs: $CONFIG, $SOURCE, $MIN_SEVERITY, $EPIC_ID, $DRY_RUN, $ADD_TO_DEBT, $CREATE_STORIES, $BLOCKING_ONLY, $GAP_PATHS
Phase 02: Discovery & Parsing (5 steps)
Glob gap files from configured sources, parse JSON structure, validate required fields per gap type (coverage_gaps, anti_pattern_violations, code_quality_violations, deferral_issues), handle backward compatibility for missing blocking field (defaults to true), build unified normalized gap list.
Reference: references/gap-discovery-workflow.md
Key Outputs: $GAP_FILES, $ALL_GAPS, $FILES_PROCESSED, $TOTAL_GAPS
Phase 03: Aggregation & Prioritization (6 steps)
Deduplicate gaps by file+type+description key, calculate priority scores using severity weights (CRITICAL:100, HIGH:75, MEDIUM:50, LOW:25) plus type modifiers (deferral:+25, security:+15, Business Logic coverage:+10), filter by $MIN_SEVERITY threshold, apply --blocking-only filter (AND logic with severity), sort by score descending.
Reference: references/gap-aggregation-algorithm.md
Key Outputs: $UNIQUE_GAPS, $FILTERED_GAPS, $DEFERRED_GAPS, $ADVISORY_HIDDEN_COUNT
Phase 04: Interactive Selection (4 steps)
Display gap summary table with [R] (blocking) and [Y] (advisory) indicators, show statistics summary, handle dry-run exit (display and EXIT — no further phases), present AskUserQuestion with selection options (all, CRITICAL only, CRITICAL+HIGH, cancel).
Reference: None (user interaction phase)
Key Outputs: $SELECTED_GAPS, $SELECTION_COUNT
Dry-Run Exit: If $DRY_RUN == true, display summary and EXIT skill. Phases 05-07 are NOT executed.
Phase 05: Batch Story Creation (7 steps)
Initialize tracking arrays, determine next story ID, generate story context markers per gap (with advisory story naming per STORY-348), invoke spec-driven-stories skill in batch mode for each gap, handle --create-stories auto-mode (skip confirmation), track created/failed stories with failure isolation, display batch completion summary.
Reference: references/gap-to-story-mapping.md
Key Outputs: $CREATED_STORIES, $FAILED_STORIES, $STORIES_CREATED_COUNT, $BLOCKING_STORIES_COUNT, $ADVISORY_STORIES_COUNT, $STORY_ID_MAP
Phase 06: Source Report Update (4 steps)
Update LOCAL gap files with implemented_in and remediation_date fields (imported files are read-only), generate enhancement report from template at devforgeai/qa/enhancement-reports/{date}-enhancement-report.md, invoke optional post-qa-remediation hook.
Reference: references/report-update-protocol.md
Key Outputs: $REPORTS_UPDATED, $ENHANCEMENT_REPORT_PATH
Phase 07: Technical Debt Integration (8 steps)
Check config for auto-add setting, read current debt register, generate formatted debt entries for $DEFERRED_GAPS, append to register under "## Open Debt Items" section, update statistics, handle --add-to-debt auto-mode (skip confirmation, pre-populate Follow-up with story IDs from Phase 05), invoke optional technical-debt-analyzer subagent.
Reference: references/technical-debt-update.md
Key Outputs: $DEBT_ENTRIES_ADDED, $REGISTER_UPDATED
State Persistence
Checkpoint Location: devforgeai/workflows/checkpoints/qa-remediation-${SESSION_ID}.checkpoint.json
{
"checkpoint_version": "1.0",
"session_id": "${SESSION_ID}",
"workflow": "qa-remediation",
"created_at": "ISO 8601 timestamp",
"updated_at": "ISO 8601 timestamp",
"status": "in_progress|completed|paused",
"input": {
"source": "${SOURCE}",
"min_severity": "${MIN_SEVERITY}",
"epic_id": "${EPIC_ID}",
"dry_run": false,
"add_to_debt": false,
"create_stories": false,
"blocking_only":
Workflow Completion Validation
expected_phases = 7 (or 4 if $DRY_RUN)
IF completed_count < expected_phases: HALT "WORKFLOW INCOMPLETE - {completed_count}/{expected_phases} phases"
IF completed_count == expected_phases: "All {expected_phases} phases completed - QA Remediation workflow passed"
Final Summary Display
After all phases complete (or after Phase 04 in dry-run mode), display:
┌────────────────────────────────────────────────────────────────────────────┐
│ QA Gap Remediation Complete │
├────────────────────────────────────────────────────────────────────────────┤
│ Gap Files Processed: {$FILES_PROCESSED} │
│ Total Gaps Found: {$TOTAL_GAPS} │
│ Blocking Gaps: {$BLOCKING_GAPS_COUNT} │
│ Advisory Gaps: {$ADVISORY_GAPS_COUNT} │
│ Gaps Selected: {$SELECTION_COUNT} │
│ Stories Created: {$STORIES_CREATED_COUNT} │
│ Blocking Stories: {$BLOCKING_STORIES_COUNT} │
│ Advisory Stories: {$ADVISORY_STORIES_COUNT} │
│ Stories Failed: {count of $FAILED_STORIES} │
│ Gaps Deferred to Debt: {$DEBT_ENTRIES_ADDED} │
│ Advisory Gaps Hidden: {$ADVISORY_HIDDEN_COUNT} │
├────────────────────────────────────────────────────────────────────────────┤
│ Enhancement Report: {$ENHANCEMENT_REPORT_PATH} │
│ Technical Debt Register: devforgeai/technical-debt-register.md │
└────────────────────────────────────────────────────────────────────────────┘
Validation: Total Gaps = Blocking Gaps + Advisory Gaps
IF $BLOCKING_ONLY == true:
"--blocking-only filter active ({$ADVISORY_HIDDEN_COUNT} advisory gaps hidden)"
Next Steps:
1. Review created stories in devforgeai/specs/Stories/
2. Assign stories to sprint via /create-sprint
3. Review deferred gaps in technical-debt-register.md
4. Re-run with --min-severity LOW to address deferred gaps
Success Criteria
| Criterion | Validation |
|---|
| Gap files discovered | $FILES_PROCESSED > 0 |
| Gaps parsed | $TOTAL_GAPS > 0 |
| Selection completed | User made selection or dry-run completed |
| Stories created | $STORIES_CREATED_COUNT >= 0 |
| Source reports updated | Local files have implemented_in field |
| Debt register updated | Deferred gaps added (if any) |
| Enhancement report generated | File exists at $ENHANCEMENT_REPORT_PATH |
| Blocking vs advisory distinction | Correct counting per gap blocking field |
Error Handling
HALT Conditions
| Condition | Action |
|---|
| Project root invalid | HALT with navigation instructions |
| Config file missing | HALT with creation instructions |
| No gap files found | HALT with generation/import guidance |
| User cancels selection | EXIT gracefully with message |
Continue Conditions (Failure Isolation)
| Condition | Action |
|---|
| Individual story creation fails | Log error, continue to next gap |
| Gap file update fails (imports) | Skip update (imports are read-only) |
| Debt register update fails | Log warning, continue with summary |
Reference Files
| Reference | Phase | Purpose |
|---|
references/gap-discovery-workflow.md | 02 | Detailed gap file parsing algorithm |
references/gap-aggregation-algorithm.md | 03 | Scoring, deduplication, and filtering |
references/gap-to-story-mapping.md | 05 | Story context marker generation rules |
references/report-update-protocol.md | 06 | Gap file update and report generation |
references/technical-debt-update.md | 07 | Debt register entry format and update |
Template Files
| Template | Phase | Purpose |
|---|
assets/templates/enhancement-report-template.md | 06 | Enhancement report markdown template |
assets/templates/import-metadata-template.yaml | 02 | Import metadata schema |
Related Components
| Component | Relationship |
|---|
/review-qa-reports command | Invokes this skill |
spec-driven-stories skill | Batch mode story creation (Phase 05) |
spec-driven-qa skill | Produces gap files consumed by this skill |
technical-debt-analyzer subagent | Optional debt analysis (Phase 07) |
devforgeai/config/qa-remediation.yaml | Runtime configuration |
devforgeai/technical-debt-register.md | Deferred gap tracking |
devforgeai/qa/reports/ | Local gap file source |
devforgeai/qa/imports/ | External project gap imports |
devforgeai/qa/enhancement-reports/ | Generated report output |
Configuration
Runtime settings in devforgeai/config/qa-remediation.yaml:
| Setting | Default | Description |
|---|
sources.local | devforgeai/qa/reports/*-gaps.json | Local gap file glob |
sources.imports | devforgeai/qa/imports/**/*-gaps.json | Import gap file glob |
severity_weights.CRITICAL | 100 | Scoring weight |
severity_weights.HIGH | 75 | Scoring weight |
severity_weights.MEDIUM | 50 | Scoring weight |
severity_weights.LOW | 25 | Scoring weight |
defaults.min_severity | MEDIUM | Default severity filter |
defaults.sprint | Backlog | Default sprint for stories |
technical_debt.register_path | devforgeai/technical-debt-register.md | Debt register location |
technical_debt.auto_add_skipped | true | Auto-add deferred gaps |
technical_debt.invoke_analyzer | false | Run debt analyzer subagent |
batch_mode.continue_on_failure | true | Continue if story fails |
batch_mode.max_stories_per_run | 20 | Safety limit |
