feat(performance): add core-web-vitals-cls skill

[phdro88]

Why

Agents working on storefront performance fixes had no structured way to diagnose CLS. The typical workflow was manual — open DevTools, run Lighthouse in the browser, eyeball culprits — which doesn't translate to autonomous agent execution.

This skill makes CLS diagnosis fully runnable by an agent from the terminal, end-to-end.

What

A new skill at .claude-performance/skills/core-web-vitals-cls/ that:

1. Guides setup — Lighthouse CLI install + Chromium-based browser detection (Chrome → Edge → Brave), with fallback to brew install --cask google-chrome
2. Samples URLs from the sitemap — fetches /sitemap.xml, handles both flat sitemaps and sitemap index files, classifies URLs by page type (home, PLP, PDP, search), and selects one representative URL per type. Running Lighthouse on every URL is wasteful — pages of the same type share components, so fixing one PLP fixes all.
3. Runs Lighthouse locally — against localhost so fixes can be validated before deploying. Produces one JSON report per page type.
4. Parses culprits — extracts Performance Score, CLS value, and the top layout shift elements (with node snippets and individual contribution scores) from each report. Groups culprits across page types — the same component often appears in multiple pages; one fix covers all.
5. Records baseline — before any code change, prints a structured before/after delta table with Performance Score and CLS. A fix is only valid if both numbers improved.
6. Documents common culprits — unsized images, Lazy.tsx above-the-fold swap, w-auto h-auto overriding HTML dimensions, duplicate SSR elements, FOUT — with code-level fixes for each.

Tested on

HomyCasa (www.homycasa.pt) — ran the full workflow end-to-end. Sitemap fetched, 4 URLs sampled, Lighthouse ran against localhost, baseline recorded. CLS was clean across all page types (< 0.1), which correctly concluded there was no CLS problem to fix on that site.

Notes

• Python 3 (stdlib only) is used for sitemap parsing and report parsing — no extra dependencies, works on any macOS out of the box.
• The sitemap script handles both flat sitemaps and sitemap index files (like Deco's default /sitemap.xml which points to sub-sitemaps).
• SITE variable in the sitemap script must be replaced with the actual site URL before running.

---

Summary by cubic

Adds the core-web-vitals-cls skill to diagnose and fix CLS from the terminal using lighthouse. It automates URL sampling, local audits, culprit extraction, and before/after reporting to make CLS fixes reproducible.

• New Features
  • New skill at .claude-performance/skills/core-web-vitals-cls/ with an end-to-end CLS workflow.
  • Setup guidance for lighthouse and Chromium detection (CHROME_PATH support, brew fallback).
  • Samples URLs from /sitemap.xml (flat or index) and selects one per page type (home, PLP, PDP, search).
  • Runs lighthouse against localhost, saves JSON per type, and parses Performance Score, CLS, and top layout shift elements.
  • Records a baseline and after-fix delta table; includes concise code-level fixes for common culprits.

^{Written for commit fec5af2. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".claude-performance/skills/core-web-vitals-cls/SKILL.md">

<violation number="1" location=".claude-performance/skills/core-web-vitals-cls/SKILL.md:76">
P2: Child sitemaps ending in `.xml.gz` are not expanded, so sitemap-index sites can produce incomplete or invalid URL samples.</violation>

<violation number="2" location=".claude-performance/skills/core-web-vitals-cls/SKILL.md:91">
P2: PLP/PDP detection is brittle because trailing slashes change `path.count("/")`, causing category URLs to be misclassified as PDP.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: PLP/PDP detection is brittle because trailing slashes change path.count("/"), causing category URLs to be misclassified as PDP.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .claude-performance/skills/core-web-vitals-cls/SKILL.md, line 91:

<comment>PLP/PDP detection is brittle because trailing slashes change `path.count("/")`, causing category URLs to be misclassified as PDP.</comment>

<file context>
@@ -0,0 +1,266 @@
+        home.append(u)
+    elif "/busca" in path or "/search" in path or "?q=" in path:
+        search.append(u)
+    elif path.count("/") == 1:
+        plp.append(u)
+    elif path.count("/") >= 2:
</file context>

[cubic-dev-ai]

P2: Child sitemaps ending in .xml.gz are not expanded, so sitemap-index sites can produce incomplete or invalid URL samples.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .claude-performance/skills/core-web-vitals-cls/SKILL.md, line 76:

<comment>Child sitemaps ending in `.xml.gz` are not expanded, so sitemap-index sites can produce incomplete or invalid URL samples.</comment>

<file context>
@@ -0,0 +1,266 @@
+locs = fetch_locs(f"{SITE}/sitemap.xml")
+all_urls = []
+for loc in locs:
+    if "sitemap" in loc and loc.endswith(".xml"):
+        all_urls.extend(fetch_locs(loc))
+    else:
</file context>