| name | spec-driven-remediation |
| description | Apply automated and guided fixes to story, epic, and context files based on structured audit findings with 4-layer anti-skip enforcement. Classifies findings by fix complexity, applies safe automated fixes, guides interactive fixes with user confirmation, verifies all changes, and produces a fix report. Uses Execute-Verify-Record pattern at every step to prevent token optimization bias. Use when /fix-story is invoked, when audit findings need remediation, or when custody chain validation produces findings requiring correction. Make sure to use this skill whenever the user mentions fixing stories, remediating audit findings, applying fixes from /validate-stories output, or addressing custody chain violations.
|
| metadata | {"author":"DevForgeAI","version":"2.0.0","category":"story-lifecycle","agent-skills-spec-version":"1.0","last-updated":"2026-03-18","migrated-from":"story-remediation v1.0.0"} |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","ask the user","Bash(devforgeai-validate:*)","Bash(git:*)"] |
| model | opus |
| effort | High |
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 ask the user
Execution Model
See .claude/rules/core/anti-skip-behavior.md for the canonical execution contract (expand inline; do not wait passively or offer execution options; honor every step of every phase; Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076). After invocation, execute Phase State Initialization immediately.
Anti-Skip Enforcement Contract
Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the devforgeai-validate phase gates, the settings.json-registered .codex/hooks/ scripts, and .codex/hooks/phase-steps-registry.json (ADR-076). Behavioral residue: .claude/rules/core/anti-skip-behavior.md.
Parameter Extraction
Extract parameters from conversation context markers set by /fix-story command. See references/parameter-extraction.md for the extraction algorithm.
Command Integration
| Context Marker | Set By | Description |
|---|
$FIX_MODE | /fix-story | Input mode: audit_file, story_id, or epic_id |
$AUDIT_FILE | /fix-story | Path to audit file |
$DRY_RUN | /fix-story | true = preview only, no file modifications |
$AUTO_ONLY | /fix-story | true = skip interactive and ADR fixes |
$FINDING_FILTER | /fix-story | F-NNN for single finding, "all" for everything |
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=.
| Exit Code | Meaning | Action |
|---|
| 0 | New workflow | State file created. Set CURRENT_PHASE = "00". |
| 1 | Existing workflow | Resume. Check checkpoint file for CURRENT_PHASE. |
| 2 | Invalid session ID | HALT. Verify audit file path. |
| 127 | CLI not installed | HALT. Restore the validator before any governed operation. |
Resume Detection: If resuming, read checkpoint:
inspect `{project-root}/tmp/.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: inspect `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).
| Phase | Name | File |
|---|
| 00 | Context Loading + Finding Extraction | phases/phase-00-context-loading.md |
| 01 | Finding Triage + Classification | phases/phase-01-triage.md |
| 02 | Safety Preview | phases/phase-02-preview.md |
| 03 | Fix Execution | phases/phase-03-execution.md |
| 04 | Post-Fix Verification | phases/phase-04-verification.md |
| 05 | Fix Report + Session Record | phases/phase-05-reporting.md |
State Persistence
Phase State: devforgeai/workflows/${SESSION_ID}-remediation-phase-state.json
Session Memory: .claude/memory/sessions/${SESSION_ID}-remediation-session.md
Checkpoint: {project-root}/tmp/.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
Reference Files
Phase Execution (phases/ directory)
| File | Phase |
|---|
| phase-00-context-loading.md | Context Loading + Finding Extraction |
| phase-01-triage.md | Finding Triage + Classification |
| phase-02-preview.md | Safety Preview |
| phase-03-execution.md | Fix Execution |
| phase-04-verification.md | Post-Fix Verification |
| phase-05-reporting.md | Fix Report + Session Record |
Supporting References (references/ directory)
| File | Purpose |
|---|
| fix-actions-catalog.md | Classification matrix and fix procedures for each finding type |
| fix-verification-workflow.md | Per-type verification procedures and feedback loop protocol |
| context-validation.md | Context file constraint validation rules |
| checkpoint-schema.md | Checkpoint YAML schema for remediation sessions |
| memory-file-operations.md | Session memory file read/write operations |
| parameter-extraction.md | Audit file resolution and parameter extraction algorithm |
Templates (assets/templates/ directory)
| File | Purpose |
|---|
| fix-report-template.md | Fix session report markdown template |
| checkpoint-template.yaml | Checkpoint YAML structure template |
