visual-evaluator

Visual Evaluator Skill

Captures Playwright screenshots at discovered routes and invokes the visual-evaluator agent, producing structured JSON findings with pixel-observable spatial quality scores.

Parameters

Read from ${CLAUDE_PLUGIN_ROOT}/config/visual-evaluator-params.yaml at dispatch time.

Preconditions

Before running, check all four preconditions in order. On any failure, write visual_eval_inapplicable:<reason> to the ticket (via .claude/scripts/dso ticket tag <id> visual_eval_inapplicable:<reason>) AND surface to the integration gate via a non-zero exit or explicit annotation. Never soft-pass — emit the reason explicitly.

Gate 1: project_type=web

PROJECT_TYPE=$(bash "$PLUGIN_SCRIPTS/read-config.sh" project.type 2>/dev/null || echo "")
if [[ "$PROJECT_TYPE" != "web" ]]; then
  echo "visual_eval_inapplicable:not_web_project — project.type is '$PROJECT_TYPE', not 'web'"
  .claude/scripts/dso ticket tag "$STORY_ID" visual_eval_inapplicable:not_web_project 2>/dev/null || true
  exit 1
fi

Gate 2: playwright_available

if ! command -v npx >/dev/null 2>&1 || ! npx playwright --version >/dev/null 2>&1; then
  echo "visual_eval_inapplicable:playwright_unavailable — Playwright not found via npx"
  .claude/scripts/dso ticket tag "$STORY_ID" visual_eval_inapplicable:playwright_unavailable 2>/dev/null || true
  exit 1
fi

Gate 3: check-local-env.sh exit 0

if ! bash "$PLUGIN_SCRIPTS/check-local-env.sh" >/dev/null 2>&1; then
  echo "visual_eval_inapplicable:local_env_check_failed — check-local-env.sh returned non-zero"
  .claude/scripts/dso ticket tag "$STORY_ID" visual_eval_inapplicable:local_env_check_failed 2>/dev/null || true
  exit 1
fi

Gate 4: route_map_fresh<24h

ROUTE_MAP=".ui-discovery-cache/route-map.json"
if [[ ! -f "$ROUTE_MAP" ]]; then
  echo "visual_eval_inapplicable:route_map_missing — .ui-discovery-cache/route-map.json not found. Run /dso:ui-discover first."
  .claude/scripts/dso ticket tag "$STORY_ID" visual_eval_inapplicable:route_map_missing 2>/dev/null || true
  exit 1
fi
_ROUTE_MAP_MTIME=$(stat -f %m "$ROUTE_MAP" 2>/dev/null || stat -c %Y "$ROUTE_MAP" 2>/dev/null || echo "")
if [[ -z "$_ROUTE_MAP_MTIME" ]]; then
  echo "visual_eval_inapplicable:route_map_missing — could not stat .ui-discovery-cache/route-map.json"
  .claude/scripts/dso ticket tag "$STORY_ID" visual_eval_inapplicable:route_map_missing 2>/dev/null || true
  exit 1
fi
ROUTE_MAP_AGE=$(( $(date +%s) - _ROUTE_MAP_MTIME ))
ROUTE_MAP_MAX_AGE=${visual_evaluator_route_map_max_age_hours:-24}
ROUTE_MAP_MAX_AGE_SECS=$(( ROUTE_MAP_MAX_AGE * 3600 ))
if (( ROUTE_MAP_AGE > ROUTE_MAP_MAX_AGE_SECS )); then
  echo "visual_eval_inapplicable:route_map_stale — .ui-discovery-cache/route-map.json is older than ${ROUTE_MAP_MAX_AGE}h. **Re-run /dso:ui-discover to refresh the route map.** (age: ${ROUTE_MAP_AGE}s, max: ${ROUTE_MAP_MAX_AGE_SECS}s)"
  .claude/scripts/dso ticket tag "$STORY_ID" visual_eval_inapplicable:route_map_stale 2>/dev/null || true
  exit 1
fi