/arn-spark-visual-readiness

name: arn-spark-visual-readiness
description: >-
  This skill should be used when the user says "visual readiness",
  "check visual layers", "activate visual layer", "visual checkpoint",
  "promote visual testing", "enable layer 2", "visual test health",
  "check deferred layers", "activate deferred layers", "layer promotion",
  or wants to validate and activate deferred visual testing layers
  after project milestones.
version: 1.0.0

Arness Visual Readiness

Validate and activate deferred visual testing layers after project milestones. When `arn-spark-visual-strategy` sets up a multi-layer testing strategy, Layer 1 (typically browser-based capture) is validated and activated immediately. Additional layers (e.g., native window capture) are marked as **deferred** because the project may not yet have the build pipeline, platform access, or tooling required to validate them. This skill is the checkpoint that evaluates whether deferred layers are now ready, validates them with a spike, and promotes them to active.

This is a conversational skill that runs in normal conversation (NOT plan mode). It uses the `arn-spark-visual-test-engineer` agent for layer validation spikes.

The primary artifacts are:

• **Updated CLAUDE.md** -- deferred layers promoted to active with validation evidence
• **Updated strategy document** -- validation results appended per layer
• **Readiness report** -- layer status table with evidence and recommendations

**The core problem this solves:** deferred visual testing layers sit dormant after `arn-spark-visual-strategy` because nothing re-evaluates whether the project has reached the point where those layers can be activated. This skill closes that gap by checking activation criteria, running validation spikes, and promoting layers that pass.

Prerequisites

Read the project's `CLAUDE.md` for a `## Arness` section. If no `## Arness` section exists or Arness Spark fields are missing, inform the user: "Arness Spark is not configured for this project yet. Run `/arn-brainstorming` to get started — it will set everything up automatically." Do not proceed without it.

Extract:

• **Plans directory**
• **Vision directory** (default: `.arness/vision`)
• **Spikes directory** (default: `.arness/spikes`) -- for validation spike workspaces
• **Git** / **Platform**

Check for `### Visual Testing` subsection: 1. If found: parse all fields (see Step 1 for details) 2. If NOT found: "No visual testing configuration found in CLAUDE.md. Run `/arn-spark-visual-strategy` first to set up your visual testing strategy." Exit.

Workflow

Step 1: Load Visual Testing Config

Read CLAUDE.md `### Visual Testing` section.

**Parse top-level fields as Layer 1 config (always active):**

• **Strategy doc:** path to the visual strategy document
• **Baseline directory:** path to baseline images
• **Capture script:** path to the capture script
• **Compare script:** path to the comparison script
• **Layers:** comma-separated list of layer names
• **Diff threshold:** pixel difference tolerance percentage
• **Integration:** manual / npm-script / ci / arness-pipeline

**Scan for `#### Layer N:` subsections.** For each subsection, extract per-layer fields:

• **Status:** active / deferred
• **Capture script:** path to the layer's capture script
• **Compare script:** path to the layer's comparison script
• **Baseline directory:** path to the layer's baselines
• **Diff threshold:** layer-specific threshold (or inherit top-level)
• **Requires dev server:** yes / no
• **Activation criteria:** free-text description of what must be true to activate
• **Environment:** target platform/OS for this layer
• **Spike result:** previous spike outcome (Validated / Partially validated / Failed / Deferred)

Build a layer list with all extracted data. Layer 1 is always the top-level config (implicit, always active). Additional layers come from `#### Layer N:` subsections.

**If no `### Visual Testing` found:** suggest `/arn-spark-visual-strategy` and exit.

**If no deferred layers:** "All visual testing layers are active. No deferred layers to promote." Present a summary table of active layers and suggest `/arn-code-review-implementation` for a full multi-layer quality check. Exit.

Step 2: Validate Active Layers

For each active layer, verify the existing pipeline still works:

1. Run the layer's capture script against the development build (or prototype if dev build unavailable) 2. Run the layer's compare script against the baselines 3. Check baseline counts against the screen manifest (if `baseline-manifest.json` exists) 4. Report newly capturable screens that lack baselines (screens added since last baseline update)

Present results per active layer:

"**Layer [N] ([Name]) -- Active:**

• Capture: [PASS / FAIL] -- [N] screens captured
• Compare: [PASS / FAIL] -- [N] screens compared, [M] within threshold
• Baselines: [N] baselines / [M] screens in manifest ([coverage]%)
• New screens without baselines: [list or 'none']"

If an active layer's pipeline fails: report it as a **WARNING** but continue. Do not block deferred layer evaluation because an active layer has a transient issue.

Step 3: Check Activation Criteria

Read the readiness checklist: > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-visual-readiness/references/readiness-checklist.md`

For each deferred layer:

1. Read the layer's `**Activation criteria:**` field from CLAUDE.md 2. Match the criteria text against the common patterns in the readiness checklist (Build Success, Platform Access, Tool Availability, CI Configuration) 3. Execute the concrete checks for each matching pattern:

• Run commands to verify tool availability (`which [tool]`, `[tool] --version`)
• Check for build artifacts at expected paths
• Test file transfer mechanisms for cross-environment layers
• Verify CI workflow configuration if relevant

4. Collect evidence for each check 5. **Journey upgrade check** — If the layer has `**Interaction:** static` or no