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):

• Stopping to ask about token budget
• Stopping to offer execution options
• Waiting passively for results
• Asking "should I execute this?"
• Skipping a phase because it "seems simple"
• Combining multiple phases into one
• Summarizing instead of loading a reference file
• Skipping verification because "I already know the result"

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:

1. Fresh-context subagent execution — Story creation runs in isolated context via spec-driven-stories skill invocation
2. Binary CLI gates — devforgeai-validate phase-check/phase-complete/phase-record --workflow=qa-remediation (compiled, cannot be forged by LLM)
3. Hook enforcement — Shell scripts in .claude/hooks/ run outside LLM control
4. 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).

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:

1. Phase 05 executes before Phase 07 (stories created first)
2. Phase 07 executes SECOND (gaps added to debt register)
3. Debt entries have Follow-up field pre-populated with created STORY-XXX IDs

Command Integration

Phase State Initialization [MANDATORY FIRST]

source .venv/bin/activate && devforgeai-validate phase-init ${SESSION_ID} --workflow=qa-remediation --project-root=. 2>&1

Generate $SESSION_ID from timestamp: qa-rem-{YYYYMMDD-HHmmss}

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

Required Subagents Per Phase

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": false
  },

  "progress": {
    "current_phase": 1,
    "phases_completed": [],
    "phases_skipped": [],
    "total_steps_completed": 0
  },

  "phases": {
    "01": { "status": "pending", "steps_completed": [] },
    "02": { "status": "pending", "steps_completed": [] },
    "03": { "status": "pending", "steps_completed": [] },
    "04": { "status": "pending", "steps_completed": [] },
    "05": { "status": "pending", "steps_completed": [] },
    "06": { "status": "pending", "steps_completed": [] },
    "07": { "status": "pending", "steps_completed": [] }
  },

  "output": {
    "gap_files_processed": 0,
    "total_gaps": 0,
    "stories_created": 0,
    "debt_entries_added": 0,
    "enhancement_report_path": null,
    "error": null
  }
}

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

Error Handling

HALT Conditions

Continue Conditions (Failure Isolation)

Reference Files

Template Files

Related Components

Configuration

Runtime settings in devforgeai/config/qa-remediation.yaml: