@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/claude-code/perf-image-formats/skill.yaml

@@ -0,0 +1,39 @@
+name: perf-image-formats
+version: '1.0.0'
+description: Image formats — WebP, AVIF, JPEG XL format selection, quality tuning, and automated conversion pipelines
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-responsive-images
+  - perf-lazy-loading-media
+  - perf-compression
+  - perf-cdn-strategies
+  - perf-largest-contentful-paint
+stack_signals: []
+keywords:
+  - webp
+  - avif
+  - jpeg xl
+  - image optimization
+  - image compression
+  - format selection
+  - sharp
+  - squoosh
+  - image quality
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-index-strategies/SKILL.md

@@ -0,0 +1,210 @@
+# Index Strategies
+
+> Master database indexing — B-tree index mechanics and column ordering, composite indexes for multi-column queries, partial indexes for filtered subsets, covering indexes for index-only scans, GIN indexes for JSONB and full-text search, GiST for geometric and range data, and index maintenance strategies.
+
+## When to Use
+
+- EXPLAIN shows sequential scans on frequently queried tables
+- Adding an index is needed but you must choose the right type and column order
+- A WHERE clause filters on multiple columns and no composite index exists
+- A large table has indexes that are never used (write overhead without read benefit)
+- JSONB columns need to support efficient key/value lookups
+- Full-text search queries are slow without proper indexing
+- A table has millions of rows but queries typically filter to a small active subset
+- Index bloat has grown to consume significant disk space
+- A query returns only indexed columns but still accesses the heap (table data)
+- Range queries on timestamps or numeric values do not use indexes efficiently
+
+## Instructions
+
+1. **Understand B-tree index mechanics.** B-tree is the default index type and supports equality, range, sorting, and prefix matching:
+
+   ```sql
+   -- B-tree supports: =, <, >, <=, >=, BETWEEN, IN, IS NULL
+   -- Also supports: ORDER BY, MIN(), MAX()
+   CREATE INDEX idx_orders_created ON orders(created_at);
+
+   -- This index accelerates:
+   SELECT * FROM orders WHERE created_at > '2024-01-01';           -- range
+   SELECT * FROM orders WHERE created_at = '2024-03-15';           -- equality
+   SELECT * FROM orders ORDER BY created_at DESC LIMIT 10;         -- sorting
+   SELECT MIN(created_at) FROM orders;                              -- aggregate
+   ```
+
+2. **Design composite indexes with correct column order.** Column order in a composite index determines which queries can use it:
+
+   ```sql
+   -- Composite index: (status, created_at)
+   CREATE INDEX idx_orders_status_created ON orders(status, created_at DESC);
+
+   -- Uses the index (leftmost prefix):
+   WHERE status = 'active'                              -- equality on first col
+   WHERE status = 'active' AND created_at > '2024-01-01'  -- equality + range
+   WHERE status = 'active' ORDER BY created_at DESC     -- equality + sort
+   WHERE status IN ('active', 'pending')                -- IN on first col
+
+   -- Cannot use this index (skips first column):
+   WHERE created_at > '2024-01-01'                      -- needs separate index
+   ORDER BY created_at DESC                              -- needs separate index
+   ```
+
+   **Rule of thumb:** Put equality columns first, then range/sort columns. High-cardinality columns first when multiple equality filters exist.
+
+3. **Create partial indexes for filtered subsets.** Index only the rows that queries actually filter:
+
+   ```sql
+   -- Full index: indexes ALL 10M orders (large, expensive to maintain)
+   CREATE INDEX idx_orders_status ON orders(status);
+
+   -- Partial index: indexes only the 50K active orders (tiny, fast)
+   CREATE INDEX idx_orders_active ON orders(created_at DESC)
+     WHERE status = 'active';
+   -- 99.5% smaller than a full index
+
+   -- Partial index for soft deletes
+   CREATE INDEX idx_users_email_active ON users(email)
+     WHERE deleted_at IS NULL;
+   -- Queries with WHERE deleted_at IS NULL use this smaller, faster index
+
+   -- Partial unique constraint
+   CREATE UNIQUE INDEX idx_users_email_unique ON users(email)
+     WHERE deleted_at IS NULL;
+   -- Allows duplicate emails for soft-deleted users
+   ```
+
+4. **Create covering indexes for index-only scans.** When the index contains all columns the query needs, PostgreSQL skips the heap entirely:
+
+   ```sql
+   -- Query: frequently fetch order status and total for a user
+   SELECT status, total FROM orders WHERE user_id = 123;
+
+   -- Covering index: INCLUDE columns that are SELECTed but not searched
+   CREATE INDEX idx_orders_user_covering ON orders(user_id)
+     INCLUDE (status, total);
+   -- Result: Index Only Scan (no heap access, ~2x faster)
+
+   -- Verify with EXPLAIN:
+   -- Index Only Scan using idx_orders_user_covering on orders
+   --   Index Cond: (user_id = 123)
+   --   Heap Fetches: 0  ← confirms index-only scan
+   ```
+
+5. **Use GIN indexes for JSONB and arrays.** GIN (Generalized Inverted Index) supports containment and existence operators:
+
+   ```sql
+   -- GIN index for JSONB containment queries
+   CREATE INDEX idx_products_metadata ON products USING GIN (metadata);
+
+   -- Supports:
+   WHERE metadata @> '{"color": "red"}'          -- containment
+   WHERE metadata ? 'warranty'                     -- key existence
+   WHERE metadata ?& array['color', 'size']       -- all keys exist
+   WHERE metadata ?| array['sale', 'clearance']   -- any key exists
+
+   -- GIN index for array containment
+   CREATE INDEX idx_posts_tags ON posts USING GIN (tags);
+   WHERE tags @> ARRAY['javascript', 'react']     -- contains these tags
+
+   -- GIN index for full-text search
+   CREATE INDEX idx_articles_search ON articles
+     USING GIN (to_tsvector('english', title || ' ' || body));
+   ```
+
+6. **Use GiST indexes for geometric and range types.** GiST (Generalized Search Tree) handles spatial, range, and nearest-neighbor queries:
+
+   ```sql
+   -- GiST for PostGIS geometric queries
+   CREATE INDEX idx_locations_geom ON locations USING GIST (geom);
+   WHERE ST_DWithin(geom, ST_MakePoint(-122.4, 37.8)::geography, 5000);
+
+   -- GiST for range type queries (tsrange, int4range)
+   CREATE INDEX idx_bookings_period ON bookings USING GIST (
+     tsrange(check_in, check_out)
+   );
+   WHERE tsrange(check_in, check_out) && tsrange('2024-06-01', '2024-06-07');
+   -- && is the "overlaps" operator
+   ```
+
+7. **Monitor and maintain indexes.** Identify unused indexes and bloat:
+
+   ```sql
+   -- Find unused indexes (PostgreSQL)
+   SELECT
+     schemaname || '.' || relname AS table,
+     indexrelname AS index,
+     pg_size_pretty(pg_relation_size(i.indexrelid)) AS size,
+     idx_scan AS scans
+   FROM pg_stat_user_indexes i
+   JOIN pg_index USING (indexrelid)
+   WHERE idx_scan < 50          -- fewer than 50 scans since last stats reset
+     AND NOT indisunique          -- keep unique constraints
+   ORDER BY pg_relation_size(i.indexrelid) DESC;
+
+   -- Check index bloat
+   SELECT
+     tablename,
+     indexname,
+     pg_size_pretty(pg_relation_size(indexname::regclass)) AS index_size,
+     round(100 * pg_relation_size(indexname::regclass) /
+       NULLIF(pg_table_size(tablename::regclass), 0)) AS pct_of_table
+   FROM pg_indexes
+   WHERE schemaname = 'public'
+   ORDER BY pg_relation_size(indexname::regclass) DESC;
+
+   -- Rebuild bloated indexes (online, no lock in PostgreSQL 12+)
+   REINDEX INDEX CONCURRENTLY idx_orders_status_created;
+   ```
+
+## Details
+
+### B-tree Internal Structure
+
+A B-tree index is a balanced tree where leaf nodes contain pointers to heap tuples (table rows). For a table with 10 million rows and a B-tree on an integer column: the tree is typically 3-4 levels deep, each level requiring one page read (8KB). An equality lookup reads 3-4 pages (~24-32KB) instead of scanning the entire table (~1.2GB). Range queries read a subtree of consecutive leaf pages. The index is sorted, so ORDER BY on the indexed column is essentially free.
+
+### Write Overhead of Indexes
+
+Every INSERT updates all indexes on the table. Every UPDATE that modifies an indexed column updates those indexes. Every DELETE marks index entries for cleanup. A table with 10 indexes makes writes ~10x more expensive in I/O. This is why dropping unused indexes improves write throughput. The trade-off: read-heavy workloads benefit from more indexes; write-heavy workloads benefit from fewer.
+
+### Worked Example: Instacart Product Search
+
+Instacart's product catalog uses composite B-tree indexes for category browsing: `(store_id, category_id, popularity DESC)` enables instant filtering by store and category sorted by popularity. For search, they use a GIN index on `to_tsvector('english', name || ' ' || description)` that supports full-text search with ranking. For geographic store proximity, a GiST index on the store location column enables `ST_DWithin` queries. The combination of three index types serves their three primary access patterns without full table scans on a 50M+ product table.
+
+### Worked Example: Slack Message History
+
+Slack indexes their messages table with a composite index `(channel_id, ts DESC)` matching their primary query pattern: "show recent messages in channel X." This single index serves both the WHERE filter and the ORDER BY, producing a highly efficient index scan. For search, they use a separate search service (not PostgreSQL) because full-text search at their scale requires a dedicated inverted index system. For the "threads" feature, a partial index `(parent_ts) WHERE parent_ts IS NOT NULL` indexes only the ~10% of messages that are thread replies, keeping the index small.
+
+### Anti-Patterns
+
+**Creating single-column indexes for every column.** If a query filters on (A, B, C), three single-column indexes are less efficient than one composite index (A, B, C). The optimizer can use only one index per table scan (barring BitmapAnd). Design indexes around query patterns, not around individual columns.
+
+**Wrong column order in composite indexes.** `INDEX(created_at, status)` does not help `WHERE status = 'active' ORDER BY created_at` because the range column (created_at) comes before the equality column (status). Correct order: `INDEX(status, created_at)`.
+
+**Indexing low-cardinality columns alone.** An index on a boolean column (true/false) or a status column with 3 values provides minimal selectivity. The optimizer may choose a sequential scan anyway. Use a partial index instead: `WHERE status = 'active'`.
+
+**Never running ANALYZE after bulk loads.** The query planner uses statistics to choose plans. After inserting millions of rows, stale statistics cause cardinality misestimation and suboptimal plans. Run `ANALYZE tablename` after bulk operations.
+
+## Source
+
+- PostgreSQL: Index Types — https://www.postgresql.org/docs/current/indexes-types.html
+- PostgreSQL: Partial Indexes — https://www.postgresql.org/docs/current/indexes-partial.html
+- Use The Index, Luke — https://use-the-index-luke.com/
+- PostgreSQL: GIN Indexes — https://www.postgresql.org/docs/current/gin-intro.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Composite indexes match the application's primary query patterns with correct column order.
+- Partial indexes are used for queries that filter to a small subset of rows.
+- Covering indexes eliminate heap access for frequently-executed read queries.
+- No unused indexes exist (verified via pg_stat_user_indexes).
+- JSONB and full-text search queries use GIN indexes.

package/dist/agents/skills/claude-code/perf-index-strategies/skill.yaml

@@ -0,0 +1,40 @@
+name: perf-index-strategies
+version: '1.0.0'
+description: Index strategies — B-tree, hash, GIN, GiST, composite, partial, and covering indexes for query optimization
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-query-optimization
+  - perf-n-plus-one
+  - perf-connection-pooling
+  - prisma-performance-patterns
+  - drizzle-performance-patterns
+stack_signals: []
+keywords:
+  - database index
+  - b-tree
+  - composite index
+  - partial index
+  - covering index
+  - GIN index
+  - GiST index
+  - index strategy
+  - index bloat
+  - multi-column index
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-interaction-to-next-paint/SKILL.md

@@ -0,0 +1,170 @@
+# Interaction to Next Paint (INP)
+
+> Measure and optimize INP — the worst-case interaction latency across the entire page session — by decomposing each interaction into input delay, processing time, and presentation delay, then targeting each phase with yielding, scheduling, and rendering strategies.
+
+## When to Use
+
+- CrUX or RUM data reports INP exceeding 200ms at the 75th percentile
+- Users report the UI feels "sluggish" or "unresponsive" when clicking, tapping, or typing
+- DevTools Performance panel shows long tasks overlapping with user interactions
+- Click or keypress event handlers execute heavy synchronous work on the main thread
+- You are migrating from FID (First Input Delay) to INP and need to understand the differences
+- `scheduler.yield()` or `scheduler.postTask()` could break up long processing in event handlers
+- Third-party scripts cause main thread contention during user interactions
+- Input events are queued behind long-running tasks and experience delayed responses
+- Form interactions or search-as-you-type features exhibit perceptible lag
+- You need to attribute which phase of an interaction (input delay, processing, presentation) is the bottleneck
+
+## Instructions
+
+1. **Understand how INP differs from FID.** FID measured only the input delay of the first interaction. INP measures the full latency (input delay + processing time + presentation delay) of all interactions throughout the page session, and reports the worst interaction (approximately — it uses a high-percentile heuristic to avoid outliers).
+
+2. **Decompose interaction into 3 phases:**
+   - **Input delay** — Time from user action (click/tap/keypress) to the start of event handler execution. Caused by long tasks already running on the main thread when the user interacts.
+   - **Processing time** — Time to execute all event handlers (pointerdown, mousedown, click, etc.) for the interaction.
+   - **Presentation delay** — Time from event handler completion to the next frame being painted to screen. Caused by style recalculation, layout, paint, and compositing work.
+
+3. **Reduce input delay by avoiding long tasks.** If a 200ms task is running when the user clicks, the click handler cannot start until that task finishes:
+
+   ```javascript
+   // BAD — monolithic initialization blocks all interactions for 500ms
+   function initialize() {
+     processData(); // 200ms
+     buildIndex(); // 150ms
+     renderWidgets(); // 150ms
+   }
+
+   // GOOD — yield between chunks so user input can be processed
+   async function initialize() {
+     processData();
+     await scheduler.yield(); // let pending input events execute
+     buildIndex();
+     await scheduler.yield();
+     renderWidgets();
+   }
+   ```
+
+4. **Reduce processing time by keeping event handlers lean.** Move non-essential work out of the synchronous event handler:
+
+   ```javascript
+   // BAD — analytics + validation + DOM update all synchronous in click handler
+   button.addEventListener('click', () => {
+     trackAnalytics(event); // 50ms
+     validateForm(); // 100ms
+     updateDOM(); // 30ms
+   }); // Total: 180ms processing time
+
+   // GOOD — only essential work synchronous, defer the rest
+   button.addEventListener('click', () => {
+     updateDOM(); // 30ms — user sees immediate feedback
+     requestIdleCallback(() => {
+       trackAnalytics(event); // runs when idle
+       validateForm(); // runs when idle
+     });
+   }); // Processing time: 30ms
+   ```
+
+5. **Reduce presentation delay.** Minimize the work between event handler completion and the next paint:
+   - Avoid forcing layout in event handlers (triggers synchronous layout in the presentation phase)
+   - Use `content-visibility: auto` to reduce rendering cost for off-screen content
+   - Keep DOM mutation scope small — update only what changed
+
+6. **Use event delegation to reduce event handler overhead.** Instead of attaching listeners to each list item, delegate to the parent:
+
+   ```javascript
+   // BAD — 500 event listeners for 500 items
+   items.forEach((item) => item.addEventListener('click', handleClick));
+
+   // GOOD — 1 event listener, delegate based on target
+   list.addEventListener('click', (e) => {
+     const item = e.target.closest('.item');
+     if (item) handleClick(item);
+   });
+   ```
+
+7. **Measure INP with the Performance API:**
+
+   ```javascript
+   const observer = new PerformanceObserver((list) => {
+     for (const entry of list.getEntries()) {
+       // entry.duration = total interaction latency (input delay + processing + presentation)
+       // entry.processingStart - entry.startTime = input delay
+       // entry.processingEnd - entry.processingStart = processing time
+       // entry.startTime + entry.duration - entry.processingEnd = presentation delay
+       console.log('INP candidate:', entry.duration, 'Target:', entry.target);
+     }
+   });
+   observer.observe({ type: 'event', buffered: true, durationThreshold: 16 });
+   ```
+
+## Details
+
+### INP Thresholds
+
+| Rating            | INP (p75) | Perception                 |
+| ----------------- | --------- | -------------------------- |
+| Good              | <= 200ms  | Interface feels responsive |
+| Needs improvement | <= 500ms  | Noticeable lag             |
+| Poor              | > 500ms   | Interface feels broken     |
+
+INP is measured at the 75th percentile of all interactions during a page session. On pages with fewer than 50 interactions, the worst interaction is used. On pages with 50+ interactions, the 98th percentile is used (approximately the worst 1-2 interactions).
+
+### Worked Example: Redbus INP Optimization
+
+Redbus improved INP from 657ms to 164ms by breaking a monolithic click handler into yielding chunks. The original handler executed a 400ms data processing function synchronously on bus route selection click. The fix:
+
+1. Split the data processing into 3 phases: filter (100ms), sort (150ms), render (150ms)
+2. Inserted `await scheduler.yield()` between each phase
+3. The first chunk (filter) completed in 100ms, yielding to the browser to paint the loading state
+4. Processing time dropped from 400ms to 100ms per yield point
+5. Total INP went from 657ms (input delay: 107ms + processing: 400ms + presentation: 150ms) to 164ms (input delay: 14ms + processing: 100ms + presentation: 50ms)
+
+### Worked Example: Tesco Analytics Deferral
+
+Tesco reduced INP by 50% by moving analytics event processing from synchronous click handlers to `requestIdleCallback`. Every product click triggered synchronous analytics calls that serialized product data, computed session metrics, and prepared beacon payloads — totaling 80ms of processing. Moving to `requestIdleCallback` reduced click handler processing to 5ms (just the DOM update), with analytics work deferred to idle periods.
+
+### How INP Selects the Worst Interaction
+
+INP does not simply report the single worst interaction (which could be an outlier). Instead:
+
+- If fewer than 50 interactions occur, the worst one is reported
+- If 50+ interactions occur, the 98th percentile is used (1 in 50 interactions excluded)
+
+This makes INP resilient to one-off anomalies while still capturing consistently slow interactions.
+
+### Anti-Patterns
+
+**Synchronous DOM manipulation in event handlers.** Large DOM updates in a click handler force the browser to perform style, layout, and paint synchronously before the next frame. Use `requestAnimationFrame` to batch visual updates.
+
+**Heavy computation in input handlers without yielding.** A click handler that processes 10,000 data records without yielding blocks the main thread for the entire duration. No other interactions can be processed during this time.
+
+**Individual event listeners on hundreds of list items.** Besides the memory cost of hundreds of closures, the browser must evaluate each listener binding during event dispatch. Event delegation on the parent element reduces both memory and dispatch overhead.
+
+**Running `requestAnimationFrame` work inside click handlers.** `requestAnimationFrame` callbacks execute before the next paint but after the current task. Scheduling heavy work in rAF from a click handler delays the visual update to the frame after next, increasing presentation delay.
+
+**Ignoring input delay in favor of processing time.** Many developers focus on optimizing their event handler code but ignore that a 300ms long task running before the user clicks creates 300ms of input delay before the handler even starts. Reducing background long tasks is equally important.
+
+## Source
+
+- web.dev INP documentation — https://web.dev/articles/inp
+- Chrome INP Attribution API — https://web.dev/articles/debug-performance-in-the-field
+- Web Vitals JavaScript library — https://github.com/GoogleChrome/web-vitals
+- Scheduler API specification — https://wicg.github.io/scheduling-apis/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- INP is measured using the Performance Observer API and meets the 200ms threshold at p75.
+- Each interaction phase (input delay, processing, presentation) is identified and optimized.

package/dist/agents/skills/claude-code/perf-interaction-to-next-paint/skill.yaml

@@ -0,0 +1,40 @@
+name: perf-interaction-to-next-paint
+version: '1.0.0'
+description: INP measurement — input delay, processing time, presentation delay, long task attribution
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-event-loop
+  - perf-long-tasks
+  - perf-largest-contentful-paint
+  - perf-cumulative-layout-shift
+  - perf-performance-api
+  - angular-performance-patterns
+stack_signals: []
+keywords:
+  - INP
+  - interaction to next paint
+  - Core Web Vitals
+  - input delay
+  - processing time
+  - presentation delay
+  - responsiveness
+  - event handlers
+  - scheduler.yield
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-largest-contentful-paint/SKILL.md

@@ -0,0 +1,162 @@
+# Largest Contentful Paint (LCP)
+
+> Measure and optimize LCP — the time until the largest visible content element renders — by decomposing it into 4 sub-parts (TTFB, resource load delay, resource load time, element render delay) and targeting each with specific strategies.
+
+## When to Use
+
+- Lighthouse or CrUX reports LCP exceeding 2.5 seconds at the 75th percentile
+- The hero image or main content block takes noticeably long to appear
+- You need to determine whether LCP is bottlenecked by server response, resource loading, or rendering
+- A Single Page Application has poor LCP because content depends on JavaScript execution
+- Field data (CrUX, RUM) shows LCP regression after a deployment
+- You are implementing `fetchpriority` or `<link rel="preload">` for critical resources
+- Lazy-loading might be accidentally applied to above-the-fold images
+- Server response time (TTFB) exceeds 800ms and contributes to LCP delay
+- You need to identify which element is the LCP candidate on a given page
+- Image optimization (format, compression, sizing) could reduce LCP resource load time
+
+## Instructions
+
+1. **Identify the LCP element.** In Chrome DevTools, run a Lighthouse audit or use the Performance panel. The LCP element is highlighted in the Performance Insights panel. Common LCP elements: hero images, background images via CSS, large text blocks, video poster images. The LCP candidate can change during load — the browser reports the largest element at the time each candidate is rendered.
+
+2. **Decompose LCP into 4 sub-parts.** Every millisecond of LCP belongs to one of these phases:
+   - **TTFB (Time to First Byte)** — Time from navigation start to first byte of HTML. Target: <800ms. Affected by server processing, CDN, redirects.
+   - **Resource load delay** — Time from TTFB to when the LCP resource starts downloading. This is the gap caused by the browser not discovering the resource early enough.
+   - **Resource load time** — Time to download the LCP resource. Affected by file size, compression, CDN, connection speed.
+   - **Element render delay** — Time from resource loaded to LCP element rendered. Caused by render-blocking CSS/JS, main thread contention.
+
+3. **Optimize TTFB.** Reduce server response time:
+   - Use a CDN with edge caching for HTML documents
+   - Implement stale-while-revalidate caching headers
+   - Reduce redirect chains (each redirect adds 300-600ms)
+   - Stream HTML to flush `<head>` early
+
+4. **Eliminate resource load delay.** Ensure the browser discovers the LCP resource as early as possible:
+
+   ```html
+   <!-- Preload the LCP image so the browser fetches it immediately -->
+   <link rel="preload" href="/hero.webp" as="image" fetchpriority="high" />
+
+   <!-- For responsive images, preload with srcset -->
+   <link
+     rel="preload"
+     href="/hero-800.webp"
+     as="image"
+     imagesrcset="/hero-400.webp 400w, /hero-800.webp 800w"
+     imagesizes="100vw"
+   />
+   ```
+
+5. **Reduce resource load time.** Optimize the LCP resource itself:
+   - Use modern formats: WebP (26-34% smaller than JPEG) or AVIF (50% smaller)
+   - Serve correctly sized images (do not serve 4000px when viewport needs 800px)
+   - Enable compression (Brotli for text, already compressed for images)
+   - Use a CDN with HTTP/2 or HTTP/3
+
+6. **Minimize element render delay.** Remove bottlenecks between resource load and render:
+   - Eliminate render-blocking CSS that is not needed for the LCP element
+   - Inline critical CSS to avoid waiting for external stylesheet download
+   - Do not wrap LCP elements in JavaScript-rendered containers (client-side rendering adds JS parse + execute + fetch + render)
+
+7. **Never lazy-load the LCP image.** `loading="lazy"` on the LCP image delays its discovery and loading:
+
+   ```html
+   <!-- BAD — hero image waits for intersection observer, delaying LCP -->
+   <img src="/hero.webp" loading="lazy" alt="Hero" />
+
+   <!-- GOOD — hero image loads immediately with high priority -->
+   <img src="/hero.webp" fetchpriority="high" alt="Hero" />
+   ```
+
+## Details
+
+### LCP Thresholds
+
+| Rating            | LCP (p75) | Description                 |
+| ----------------- | --------- | --------------------------- |
+| Good              | <= 2.5s   | Users perceive load as fast |
+| Needs improvement | <= 4.0s   | Noticeable delay            |
+| Poor              | > 4.0s    | Users likely to abandon     |
+
+These thresholds are at the 75th percentile of page loads — meaning 75% of users should see LCP under 2.5s for a "good" rating.
+
+### Worked Example: Vodafone LCP Optimization
+
+Vodafone improved LCP by 31%, from 4.2s to 2.9s. The sub-part breakdown before optimization:
+
+- TTFB: 800ms (acceptable)
+- Resource load delay: 1,800ms (hero image not discovered until CSS was parsed)
+- Resource load time: 1,200ms (large JPEG, no CDN)
+- Element render delay: 400ms (render-blocking analytics script)
+
+Fixes applied:
+
+1. Added `<link rel="preload" href="/hero.webp" as="image" fetchpriority="high">` in `<head>` — resource load delay dropped from 1,800ms to 300ms
+2. Converted hero from 850KB JPEG to 200KB WebP — resource load time dropped from 1,200ms to 350ms
+3. Deferred analytics script — render delay dropped from 400ms to 50ms
+
+### Worked Example: The Economic Times SSR Migration
+
+The Economic Times reduced LCP from 7s to 2.5s by switching from client-side rendering (CSR) to server-side rendering (SSR) with streamed HTML. Under CSR, LCP required: HTML download (200ms) + JS bundle download (1.5s) + JS parse and execute (2s) + API fetch (1.5s) + render (500ms) + image load (1.3s). Under SSR, the HTML already contains the rendered content, so LCP required: HTML download with streamed flush (200ms) + image preloaded in parallel (800ms) + render (200ms).
+
+### LCP Element Types
+
+The LCP API considers these element types:
+
+- `<img>` elements (including `<img>` inside `<picture>`)
+- `<image>` inside `<svg>`
+- `<video>` poster images (the poster attribute image, not the video itself)
+- Elements with `background-image` loaded via CSS `url()`
+- Block-level elements containing text nodes (paragraphs, headings)
+
+Elements with `opacity: 0`, `visibility: hidden`, or zero-size are excluded.
+
+### Measuring LCP with the Performance API
+
+```javascript
+const observer = new PerformanceObserver((list) => {
+  const entries = list.getEntries();
+  const lastEntry = entries[entries.length - 1];
+  console.log('LCP:', lastEntry.startTime, 'Element:', lastEntry.element);
+  console.log('URL:', lastEntry.url); // resource URL for images
+  console.log('Size:', lastEntry.size); // area in pixels
+});
+observer.observe({ type: 'largest-contentful-paint', buffered: true });
+```
+
+### Anti-Patterns
+
+**Lazy-loading the LCP image.** `loading="lazy"` defers image loading until it enters the viewport, detected by an IntersectionObserver. For the LCP image (which is by definition visible in the viewport), this adds unnecessary delay — the image is not fetched until after layout determines it is visible, instead of immediately on HTML parse.
+
+**LCP element loaded via JavaScript.** Client-side rendering means the LCP element does not exist in the initial HTML. The browser must download JavaScript, parse it, execute it, potentially fetch data from an API, then render the element. This adds 2-5 seconds to LCP compared to server-side rendering.
+
+**Excessive redirect chains before the document.** Each HTTP redirect adds a full roundtrip (300-600ms). A chain of marketing-tracking redirect to www redirect to HTTPS redirect adds 1-2 seconds before the HTML even begins downloading.
+
+**Unoptimized hero images.** A 6MB PNG hero image when a 200KB WebP would produce identical visual quality at the viewport size. Always serve correctly-sized, modern-format images. Use `<picture>` with `<source>` for format fallbacks.
+
+**Render-blocking third-party scripts.** Synchronous third-party scripts (analytics, A/B testing, consent managers) in `<head>` delay rendering of the LCP element. Load them with `defer` or `async`, or load them after LCP fires.
+
+## Source
+
+- web.dev LCP documentation — https://web.dev/articles/lcp
+- Chrome User Experience Report methodology — https://developers.google.com/web/tools/chrome-user-experience-report
+- Web Vitals JavaScript library — https://github.com/GoogleChrome/web-vitals
+- "Optimize Largest Contentful Paint" — https://web.dev/articles/optimize-lcp
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- LCP is measured with the Performance API and meets the 2.5s threshold at p75.
+- Each LCP sub-part is identified and optimized individually.