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

```text
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:

```text
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:

```text
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`