visual-diff-fix

name	visual-diff-fix
description	This skill should be used after visual-acceptance-review has generated fix-tasks.json. It applies precise visual fixes from structured diff tasks, preserves source-of-truth contracts, avoids redesign and unrelated refactors, validates each batch, and outputs resolved fix task reports.
argument-hint	[fix-tasks-json]

Version: 2.0.0

visual-diff-fix

Apply precise visual fixes from fix-tasks.json.

This skill only fixes listed visual diff tasks. It does not redesign, does not rewrite visual specs, and does not expand scope.

Trigger Conditions

Use this skill when:

• 07_validation/visual_acceptance/fix-tasks.json exists
• visual-acceptance-review returned Fail or Conditional Pass
• user asks to fix visual differences
• user asks Codex to apply visual diff fixes

Required Inputs

ui/07_validation/visual_acceptance/
  fix-tasks.json
  comparison-report.md
  acceptance-summary.md
  region-diffs/

ui/03_visual_spec/
  visual-analysis.md
  layout-spec.md
  component-tree.md
  DESIGN.md
  tokens.json
  implementation-risks.md
  human-review-needed.md

ui/04_visual_spec_review/
  spec-review-report.md
  conflict-log.md
  revised-files-needed.md

ui/05_design_system/
  MASTER.md
  pages/target-page.md
  ux-checklist.md
  component-state-spec.md
  responsive-spec.md
  accessibility-spec.md
  implementation-constraints.md

Recommended:

ui/06_spec_review/
  compliance-report.md
  violation-list.json

package.json
playwright.config.*
src/
app/
components/
styles/

Source of Truth

1. fix-tasks.json
2. reference.png
3. visual-analysis.md / UI Type Classification
4. layout-spec.md / Layout Paradigm
5. implementation-risks.md / Asset Strategy
6. component-tree.md
7. tokens.json
8. 05_design_system/
9. Implementation code

Main Workflow

1. Run preflight gates.
2. Load and validate fix-tasks.json.
3. Sort tasks by priority, blocking, strictness, source, and dependency.
4. Group related tasks by root cause and file.
5. Apply one small batch of fixes.
6. Run available validation commands.
7. Capture screenshot if available.
8. Update resolved task status.
9. Repeat until high/medium blocking issues are fixed or convergence is reached.
10. Write outputs under 08_diff_fix/.

Hard Rules

• Only fix tasks listed in fix-tasks.json.
• Do not redesign.
• Do not refactor unrelated code.
• Do not introduce new visual style.
• Do not create new tokens unless task explicitly requires it and source-of-truth allows it.
• Do not overwrite screenshot-derived required tokens without impact analysis.
• Do not modify visual spec files.
• Do not modify design system files.
• Do not modify OpenSpec files.
• If a task is review-required, do not auto-fix it.
• If a task requires UI Type or Asset Strategy restoration, do not substitute with local spacing/color tweaks.
• If a fix causes regression, rollback or mark caused-regression.

Output

Write:

08_diff_fix/
  fix-report.md
  fix-tasks.resolved.json
  convergence-report.md
  escalation-report.md
  screenshots/
    after-batch-1.png
    after-batch-2.png
    final.png
  validation/
    lint.log
    build.log
    test.log
    screenshot.log

convergence-report.md and escalation-report.md are only required when applicable.

Supporting Files

Read these references directly:

• references/fix-workflow.md
• references/preflight-gates.md
• references/prioritization-rules.md
• references/fix-handlers.md
• references/token-protection-rules.md
• references/validation-rules.md
• references/convergence-rules.md
• references/fix-task-schema.md
• references/output-files.md

Examples:

• examples/fix-tasks.example.json
• examples/fix-tasks.resolved.example.json
• examples/fix-report.example.md
• examples/convergence-report.example.md
• examples/escalation-report.example.md