Spec Driven Remediation

Spec-Driven Remediation

Apply automated and guided fixes to story, epic, and context files based on structured audit findings from /validate-stories. Every step uses Execute-Verify-Record to prevent token optimization bias from skipping phases.

Audit findings are the input. Fixed files are the output. User approval gates every structural change.

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 wrote the file"

IF any box checked: EXECUTION MODEL VIOLATION. Go directly to Phase State Initialization now.

Anti-Skip Enforcement Contract

This skill enforces 3 independent anti-skip layers (Layer 1 is N/A since remediation is interactive with no subagent delegation). ALL THREE must fail for a step to be skipped:

1. Fresh-context subagent execution — N/A (remediation requires real-time user decisions via AskUserQuestion at multiple points; isolated subagent context would break the interactive workflow)
2. Binary CLI gates — devforgeai-validate commands enforce phase state transitions; cannot be forged by LLM
3. Hook enforcement — Shell scripts in .claude/hooks/ run outside LLM control
4. Step registry + artifact verification — Glob/Grep confirmation after every step, not trust-based

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)
• 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.

Parameter Extraction

Extract parameters from conversation context markers set by /fix-story command. See references/parameter-extraction.md for the extraction algorithm.

Command Integration

Phase State Initialization [MANDATORY FIRST]

Derive SESSION_ID from audit file name:

SESSION_ID = "FIX-" + basename(AUDIT_FILE).replace(".md", "")
# Example: "FIX-custody-chain-audit-stories-413-424"

devforgeai-validate phase-init ${SESSION_ID} --workflow=remediation --project-root=.

Resume Detection: If resuming, read checkpoint:

Read(file_path="devforgeai/temp/.remediation-checkpoint-${SESSION_ID}.yaml")

Extract current_phase and phase_completion to determine where to resume.

Phase Orchestration Loop

FOR phase_num in range(CURRENT_PHASE, 06):
    phase_id = format(phase_num, "02d")

    1. ENTRY GATE: devforgeai-validate phase-check ${SESSION_ID} --workflow=remediation --from={prev} --to={phase_id}
       IF exit != 0: HALT

    2. LOAD: Read(file_path="phases/{phase_files[phase_id]}")

    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=remediation --phase={phase_id}

    5. EXIT GATE: devforgeai-validate phase-complete ${SESSION_ID} --workflow=remediation --phase={phase_id} --checkpoint-passed
       IF exit != 0: HALT

Dry Run Skip Path: If $DRY_RUN == true, Phase 02 exits early and skips directly to Phase 05 (report only, no modifications).

State Persistence

Phase State: devforgeai/workflows/${SESSION_ID}-remediation-phase-state.json Session Memory: .claude/memory/sessions/${SESSION_ID}-remediation-session.md Checkpoint: devforgeai/temp/.remediation-checkpoint-${SESSION_ID}.yaml References: references/checkpoint-schema.md, references/memory-file-operations.md

Workflow Completion Validation

IF completed_count < 6: HALT "WORKFLOW INCOMPLETE - {completed_count}/6 phases"
IF completed_count == 6: "All 6 phases completed - Remediation workflow passed"

Success Criteria

• All findings loaded and classified correctly
• Automated fixes applied only after user confirmation
• Interactive fixes presented with clear resolution options
• All applied fixes pass post-fix verification
• Fix report generated with accurate summary
• Session record appended to audit file for resume capability
• No files modified without user approval (--dry-run respected)
• Deferred items properly marked with AUDIT-DEFERRED comments

Reference Files

Phase Execution (phases/ directory)

Supporting References (references/ directory)

Templates (assets/templates/ directory)