agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/performance/skills/agileflow-performance/workflows/improve-web-vitals.md

@@ -0,0 +1,344 @@
+# Workflow: Improve Core Web Vitals
+
+**Triggers:** "Lighthouse score is failing", "CWV is red in Search Console", "LCP is too slow", "CLS keeps shifting", "INP is failing", user pastes a Lighthouse report or CrUX data
+
+**Goal:** Identify which Core Web Vital is failing, diagnose the root cause using attribution data, apply targeted fixes, and verify improvement in field data — not just lab scores.
+
+---
+
+## Inputs needed
+
+| Input                                     | Required  | How to get it                                                |
+| ----------------------------------------- | --------- | ------------------------------------------------------------ |
+| Which metric is failing (LCP / INP / CLS) | Yes       | Lighthouse report, CrUX data, Search Console, or user report |
+| Current metric value                      | Yes       | From any of the above sources                                |
+| URL or page type                          | Yes       | The specific page (homepage, product page, checkout, etc.)   |
+| Tech stack                                | Preferred | Knowing React/Next.js vs plain HTML changes the fix approach |
+| Lighthouse report (full JSON or HTML)     | Preferred | Paste or share — provides the "Opportunities" section        |
+
+---
+
+## Steps
+
+### Step 1: Run Lighthouse and record the baseline
+
+If the user does not already have a report:
+
+```bash
+# Run 3 times and take the median — Lighthouse has ±15% variance
+npx lighthouse https://yoursite.com/page --output=json --output-path=report.json --chrome-flags="--headless"
+
+# Or for a quick score check:
+npx lighthouse https://yoursite.com/page --output=html --view
+```
+
+**Record the baseline values for all three Core Web Vitals:**
+
+```
+Baseline (date):
+  LCP: ___ s  (good < 2.5 s)
+  INP: ___ ms (good < 200 ms)
+  CLS: ___    (good < 0.1)
+  TTFB: ___ ms
+  FCP: ___ s
+```
+
+Note: Lighthouse INP is not reliable in lab mode — use Chrome DevTools Performance → "Interaction to Next Paint" or field data from CrUX/RUM for INP diagnosis.
+
+### Step 2: Identify the failing metric
+
+**Triage by severity** — fix the worst metric first, but be aware that some fixes affect multiple metrics.
+
+```
+Is LCP > 2.5 s? → Follow §LCP Diagnosis
+Is INP > 200 ms? → Follow §INP Diagnosis
+Is CLS > 0.1? → Follow §CLS Diagnosis
+All three failing? → Start with LCP (loading is usually the root cause)
+```
+
+---
+
+### LCP Diagnosis
+
+**Step LCP-1: Identify the LCP element**
+
+In Chrome DevTools, look for the "LCP" marker in the Performance recording. Or run:
+
+```js
+// Paste in DevTools console
+new PerformanceObserver((list) => {
+  for (const entry of list.getEntries()) {
+    console.log("LCP element:", entry.element);
+    console.log("LCP time:", entry.startTime);
+  }
+}).observe({ type: "largest-contentful-paint", buffered: true });
+```
+
+**Step LCP-2: Decompose LCP time into phases**
+
+```js
+import { onLCP } from "web-vitals/attribution";
+
+onLCP(({ value, attribution }) => {
+  const {
+    timeToFirstByte,
+    resourceLoadDelay,
+    resourceLoadDuration,
+    elementRenderDelay,
+  } = attribution;
+  console.table({
+    timeToFirstByte,
+    resourceLoadDelay,
+    resourceLoadDuration,
+    elementRenderDelay,
+  });
+});
+```
+
+| Phase                  | High value means...                                                     | Fix                                             |
+| ---------------------- | ----------------------------------------------------------------------- | ----------------------------------------------- |
+| `timeToFirstByte`      | Server is slow; CDN is not being used; origin is far from user          | CDN, edge caching, SSR optimization             |
+| `resourceLoadDelay`    | LCP resource not discovered early; preload not set; lazy-load blocking  | `<link rel="preload">`, remove `loading="lazy"` |
+| `resourceLoadDuration` | Resource is too large; connection is slow                               | Image optimization, compression, CDN            |
+| `elementRenderDelay`   | Render-blocking resource; JavaScript blocking paint; hydration blocking | Defer scripts, eliminate blocking resources     |
+
+**Step LCP-3: Apply the fix for the dominant phase**
+
+See `references/web-vitals-guide.md` §LCP and `references/optimization-patterns.md` §Image optimization for implementation details.
+
+**Most common LCP fixes (in order of impact):**
+
+1. Preload the LCP image: `<link rel="preload" as="image" href="..." fetchpriority="high">`
+2. Remove `loading="lazy"` from the LCP image
+3. Convert the LCP image to WebP/AVIF and compress it
+4. Move the LCP image to static HTML (out of JavaScript rendering)
+5. Add a CDN or improve TTFB if `timeToFirstByte` > 600 ms
+6. Eliminate render-blocking `<script>` and `<link>` tags above the LCP element
+
+---
+
+### INP Diagnosis
+
+**Note on lab vs field:** Lighthouse lab INP is unreliable because it simulates a single interaction. Use field data (CrUX or your RUM `web-vitals` instrumentation) to confirm INP is actually a problem in production. In DevTools, use the INP overlay.
+
+**Step INP-1: Find the slow interaction**
+
+```js
+import { onINP } from "web-vitals/attribution";
+
+onINP(({ value, attribution }) => {
+  const {
+    interactionTarget,
+    inputDelay,
+    processingDuration,
+    presentationDelay,
+    interactionType,
+  } = attribution;
+  console.log(`INP: ${value}ms`);
+  console.log(`Target: ${interactionTarget}`);
+  console.log(`Type: ${interactionType}`);
+  console.table({ inputDelay, processingDuration, presentationDelay });
+});
+```
+
+**Step INP-2: Identify which phase dominates**
+
+| Phase                | High value means...                                               | Fix                                              |
+| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------ |
+| `inputDelay`         | Another long task was running when the user interacted            | Break up long tasks with `scheduler.yield()`     |
+| `processingDuration` | The event handler itself is slow                                  | Optimize the handler; move work to a web worker  |
+| `presentationDelay`  | The browser took a long time to paint after the handler completed | Reduce DOM size; avoid forced synchronous layout |
+
+**Step INP-3: Profile the slow interaction**
+
+1. Open Chrome DevTools → Performance
+2. Click "Record", perform the slow interaction, stop
+3. Find the "Interaction" track — click the INP interaction bar
+4. In the Summary panel, note the three phases
+5. Find the longest task in "Main" during the processing phase
+6. Click into the flame chart to find the slow function
+
+**Step INP-4: Apply the fix**
+
+- Long task in `inputDelay`: find what was running before the interaction — use `scheduler.yield()` to break it up
+- Long event handler: profile it with the flame chart; look for synchronous loops, heavy DOM manipulation, or synchronous network calls
+- High `presentationDelay`: check DOM node count (> 1500 nodes is a warning sign); look for layout-triggering reads after writes
+
+---
+
+### CLS Diagnosis
+
+**Step CLS-1: Identify what is shifting**
+
+```js
+import { onCLS } from "web-vitals/attribution";
+
+onCLS(({ value, attribution }) => {
+  console.log(`CLS: ${value}`);
+  if (attribution.largestShiftTarget) {
+    console.log("Largest shift target:", attribution.largestShiftTarget);
+    console.log("Largest shift value:", attribution.largestShiftEntry?.value);
+    console.log(
+      "Largest shift time:",
+      attribution.largestShiftEntry?.startTime,
+    );
+  }
+});
+```
+
+Or in Chrome DevTools:
+
+1. Open DevTools → Rendering tab → check "Layout Shift Regions" (highlights shifting elements with blue overlay)
+2. Reload the page and watch which elements flash blue
+
+**Step CLS-2: Determine the cause of the shift**
+
+| Observation                               | Cause                                   | Fix                                                         |
+| ----------------------------------------- | --------------------------------------- | ----------------------------------------------------------- |
+| Shift happens immediately on load         | Image without width/height              | Add explicit `width` and `height` attributes                |
+| Shift happens 1–3 s after load            | Ad or embed loading                     | Reserve space with `min-height`                             |
+| Shift happens when user scrolls           | Lazy-loaded image without dimensions    | Add dimensions; or use `aspect-ratio` in CSS                |
+| Shift happens when content appears at top | Dynamic content injected above fold     | Inject below existing content; use fixed/sticky positioning |
+| Shift happens when font loads             | Font swap (FOUT)                        | Use `font-display: optional` or size-adjust                 |
+| Shift is triggered by a user interaction  | Not counted in CLS — this is acceptable | No fix needed                                               |
+
+**Step CLS-3: Apply the fix**
+
+See `references/web-vitals-guide.md` §CLS for implementation details.
+
+**Most common CLS fixes:**
+
+1. Add `width` and `height` to all `<img>` tags (or `aspect-ratio` in CSS)
+2. Add `min-height` to ad slots and dynamic content containers
+3. Use `font-display: optional` for web fonts
+4. Switch layout animations from `margin`/`top`/`height` to `transform: translate()`
+5. Reserve space for late-loading embeds (Twitter, YouTube, maps)
+
+---
+
+### Step 3: Verify the fix in the lab
+
+After applying the fix:
+
+```bash
+# Run Lighthouse 3 times, take the median
+npx lighthouse https://yoursite.com/page --output=json --chrome-flags="--headless"
+```
+
+Record the after values:
+
+```
+After fix (date):
+  LCP: ___ s  (Δ: ___ s, ___%)
+  INP: ___ ms (Δ: ___ ms, ___%)
+  CLS: ___    (Δ: ___, ___%)
+```
+
+If the metric did not improve by more than 10%, the fix did not address the root cause. Go back to Step 2.
+
+### Step 4: Verify in field data
+
+Lab scores and field scores can diverge by 50% or more. **Do not declare the problem solved until field data confirms it.**
+
+**How to check field data:**
+
+1. **Google Search Console** → Core Web Vitals report — shows pass/fail by URL group. Updates weekly with a 28-day rolling window.
+
+2. **PageSpeed Insights** (https://pagespeed.web.dev) — shows both lab (Lighthouse) and field (CrUX) data for any public URL.
+
+3. **CrUX Dashboard** in Looker Studio — month-by-month breakdown by form factor.
+
+4. **Your own RUM** using the `web-vitals` library:
+
+```js
+import { onLCP, onINP, onCLS } from "web-vitals";
+
+function sendToAnalytics(metric) {
+  navigator.sendBeacon(
+    "/analytics",
+    JSON.stringify({
+      name: metric.name,
+      value: metric.value,
+      rating: metric.rating, // 'good', 'needs-improvement', 'poor'
+      id: metric.id,
+      page: location.pathname,
+    }),
+  );
+}
+
+onLCP(sendToAnalytics);
+onINP(sendToAnalytics);
+onCLS(sendToAnalytics);
+```
+
+**Timeline expectation:** CrUX field data has a 28-day rolling window. A fix deployed today will be fully reflected in CrUX in ~28 days. Your own RUM shows improvement immediately.
+
+### Step 5: Prevent regression
+
+After a successful fix, add a performance budget to CI to catch regressions automatically:
+
+**Lighthouse CI budget:**
+
+```json
+// lighthouserc.json
+{
+  "ci": {
+    "assert": {
+      "assertions": {
+        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
+        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
+        "total-blocking-time": ["warn", { "maxNumericValue": 200 }]
+      }
+    }
+  }
+}
+```
+
+```yaml
+# .github/workflows/lighthouse.yml
+- name: Run Lighthouse CI
+  run: npx lhci autorun
+  env:
+    LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
+```
+
+### Step 6: Next steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Lab metrics are improved. What would you like to do next?",
+  "header": "Next step",
+  "multiSelect": false,
+  "options": [
+    {"label": "Set up RUM to monitor field data (Recommended)", "description": "Add the web-vitals library to collect real user metrics and send them to your analytics backend"},
+    {"label": "Add Lighthouse CI to prevent regression", "description": "Configure @lhci/cli in GitHub Actions to fail PRs that regress performance"},
+    {"label": "Investigate another failing metric", "description": "I can walk through LCP, INP, or CLS diagnosis for a different page or metric"},
+    {"label": "Check field data now", "description": "I'll show you how to read PageSpeed Insights or your Search Console CWV report"},
+    {"label": "Done for now", "description": "Field data will update in CrUX over the next 28 days"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+
+```
+Core Web Vitals investigation complete.
+
+Failing metric identified: LCP = 4.2 s (target: < 2.5 s)
+Root cause: Hero image not preloaded; browser discovers it 2.1 s into page load
+Fix applied: Added <link rel="preload" as="image" fetchpriority="high">; removed loading="lazy"; converted to WebP
+Lab result: LCP = 1.9 s (-55%)
+
+Next steps:
+1. Verify in field data: check PageSpeed Insights or Search Console CWV (28-day lag)
+2. Prevent regression: add Lighthouse CI budget (maxNumericValue: 2500 for LCP)
+3. Set up web-vitals RUM for real-time field monitoring
+
+Reply with a step number to continue, or describe the next issue.
+```

package/content/plugins/performance/skills/agileflow-performance/workflows/profile-and-fix.md

@@ -0,0 +1,254 @@
+# Workflow: Profile and Fix
+
+**Triggers:** "this is slow", "the API is timing out", "memory keeps growing", "the query takes forever", user describes lag or jank in any layer of the stack
+
+**Goal:** Establish a measurable baseline, identify the actual bottleneck through profiling, apply a targeted fix, and verify the improvement with numbers.
+
+---
+
+## Inputs needed
+
+| Input                                          | Required  | How to get it                                                           |
+| ---------------------------------------------- | --------- | ----------------------------------------------------------------------- |
+| Domain: frontend / backend / database / memory | Yes       | Ask if not specified                                                    |
+| Description of what is slow                    | Yes       | User description or monitoring alert                                    |
+| Existing profiling data                        | No        | Flame chart, APM trace, slow query log — paste or describe if available |
+| Tech stack (language, framework, DB)           | Yes       | Read `package.json`, `go.mod`, `pyproject.toml`, or ask                 |
+| Environment details                            | Preferred | Production vs staging; estimated traffic volume; hardware specs         |
+
+---
+
+## Steps
+
+### Step 1: Establish a baseline
+
+**Never skip this step.** Without a before number, you cannot confirm any fix helped.
+
+Choose the measurement method for your domain:
+
+| Domain   | Measurement method                                                              |
+| -------- | ------------------------------------------------------------------------------- |
+| Frontend | Lighthouse CLI (3 runs, take median); Chrome DevTools Performance recording     |
+| Backend  | `wrk` or `autocannon` benchmark against the endpoint; APM p50/p95 from traces   |
+| Database | `EXPLAIN (ANALYZE, BUFFERS)` output with actual timing; slow query log entry    |
+| Memory   | Heap snapshot size at steady state; RSS trend in APM or `process.memoryUsage()` |
+
+**Record the baseline:**
+
+```
+Baseline (2026-05-08):
+  Metric: LCP / p95 latency / query time / heap size
+  Value: [before number]
+  Environment: [how measured]
+  URL / endpoint / query: [what was measured]
+```
+
+If the user already has baseline data, skip to Step 3.
+
+### Step 2: Identify the bottleneck
+
+Load `references/profiling-guide.md` for tool-specific guidance. Quick decision tree:
+
+**Frontend — which sub-problem?**
+
+```
+Is Lighthouse LCP > 2.5 s?
+  → Is TTFB > 600 ms? → Server / CDN problem (see Step 3 TTFB fixes)
+  → Is the LCP image lazy-loaded or discovered late? → Preload fix
+  → Is there a render-blocking script or CSS? → Deferral fix
+  → Is the LCP image too large? → Image optimization
+
+Is INP > 200 ms?
+  → Open Chrome DevTools → Performance → record the slow interaction
+  → Look for long tasks (red triangles) during the interaction
+  → Find the widest bar in the event handler call stack
+
+Is CLS > 0.1?
+  → Open DevTools → Performance → look for "Layout Shift" events
+  → Use web-vitals attribution to find the shifting element
+```
+
+**Backend — which sub-problem?**
+
+```
+Is the endpoint slow on every request?
+  → Profile with clinic flame / py-spy / pprof
+  → Is CPU high? → Hot function in flame chart → optimize the algorithm
+  → Is CPU low but still slow? → I/O wait → check DB queries, external HTTP calls
+
+Is it slow only under load?
+  → Check connection pool exhaustion (pool size vs concurrent requests)
+  → Check event loop lag (clinic bubbleprof for Node.js)
+  → Check DB lock contention (pg_locks, SHOW PROCESSLIST for MySQL)
+```
+
+**Database — which sub-problem?**
+
+```
+Run EXPLAIN (ANALYZE, BUFFERS) on the slow query.
+  → "Seq Scan" on a large table? → Add an index
+  → Many small queries for same table? → N+1 pattern → batch or JOIN
+  → "Sort" with "external merge"? → Add index on sort column or increase work_mem
+  → Rows estimated vs actual differ wildly? → Run ANALYZE on the table
+```
+
+**Memory — which sub-problem?**
+
+```
+Is heap growing continuously?
+  → Take two heap snapshots (before and after the growth period)
+  → Compare in Chrome DevTools Memory → "Comparison" view
+  → Find the object type with the largest delta
+  → Use "Retainers" to find what is keeping it alive
+
+Is heap growing only under specific actions?
+  → Use "Allocation instrumentation on timeline"
+  → Filter by the object type identified above
+  → Find the allocation call site in the flame chart
+```
+
+### Step 3: Form a hypothesis
+
+Before changing anything, write down your hypothesis. This forces clarity and makes the result interpretable.
+
+```
+Hypothesis: The LCP is slow because the hero image (620 KB JPEG) is not preloaded
+and the browser discovers it late in the HTML parse.
+
+Expected fix: Add <link rel="preload" as="image"> for the hero image.
+Expected improvement: LCP should drop from 4.2 s → ~2.0 s by eliminating
+the ~2 s resource load delay phase.
+```
+
+If you cannot form a specific hypothesis, go back to Step 2 — the bottleneck is not yet identified.
+
+### Step 4: Apply ONE change
+
+**Do not apply multiple changes at once.** You will not know which one helped (or hurt).
+
+Make the single change implied by your hypothesis. Common targeted changes:
+
+**Frontend:**
+
+- Add `<link rel="preload" as="image">` for the LCP image
+- Remove `loading="lazy"` from the LCP image
+- Add `defer` to a synchronous `<script>` tag
+- Split a large component into a lazy-loaded chunk
+- Add explicit `width`/`height` to images causing CLS
+- Break up a long task with `scheduler.yield()`
+
+**Backend:**
+
+- Add caching with Redis for a frequently-read endpoint
+- Move synchronous CPU work to a worker thread
+- Increase the database connection pool size
+- Add `defer`/`async` to non-critical startup tasks
+
+**Database:**
+
+- Add a covering index on the filtered + selected columns
+- Rewrite a correlated subquery as a JOIN
+- Replace N separate queries with a single batch query
+- Add `LIMIT` to a query that was fetching all rows
+
+**Memory:**
+
+- Add `removeEventListener` in a component cleanup function
+- Add a TTL to a module-level cache Map
+- Return a cleanup function from a `useEffect`
+- Replace a `setInterval` with a `setTimeout` that reschedules itself with a guard
+
+### Step 5: Measure again
+
+Repeat the exact same measurement from Step 1 in the same environment. Record the result.
+
+```
+After fix (2026-05-08):
+  Metric: LCP
+  Value: [after number]
+  Change: [delta and % improvement]
+  Environment: [same as baseline]
+```
+
+**Is the improvement real?**
+
+- Run Lighthouse at least 3 times and take the median (lab results have ±15% variance)
+- For backend benchmarks, run with the same concurrency and duration as the baseline
+- For database queries, run `EXPLAIN ANALYZE` multiple times (first run may be cold-cache)
+
+If the improvement is within noise (< 10%), the change did not help. Revert and re-investigate.
+
+### Step 6: Check for regressions
+
+Verify that the fix did not introduce a problem in a related metric:
+
+| If you optimized | Also check                                                                  |
+| ---------------- | --------------------------------------------------------------------------- |
+| LCP              | CLS (did preloading change layout?) and INP                                 |
+| INP              | TBT and LCP (did breaking up tasks delay the paint?)                        |
+| CLS              | LCP (did reserving space affect element discovery timing?)                  |
+| Bundle size      | App functionality (did tree shaking remove a needed export?)                |
+| DB query         | Application correctness (does the optimized query return the same results?) |
+| Caching          | Data freshness (is staleness now a problem?)                                |
+
+Run the test suite after any code change. A fast but broken feature is not an improvement.
+
+### Step 7: Document the result
+
+Add a note to `_learnings/performance.yaml` with the finding. If this was a significant architecture decision (adding Redis, redesigning a query pattern, adding a CDN), create an ADR with `/agileflow:adr`.
+
+```yaml
+# _learnings/performance.yaml entry:
+- date: 2026-05-08
+  metric: LCP
+  url: /
+  before: 4.2s
+  after: 1.9s
+  change: -55%
+  fix: "Preloaded hero image; removed lazy-load; converted to WebP"
+  tools_used: Lighthouse CLI
+```
+
+### Step 8: Present the result and next steps
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Fix applied and verified. LCP improved from 4.2 s → 1.9 s (-55%). What next?",
+  "header": "Next step",
+  "multiSelect": false,
+  "options": [
+    {"label": "Investigate the next bottleneck (Recommended)", "description": "Lighthouse still flags INP at 320 ms — I can guide you through fixing that next"},
+    {"label": "Verify in field data", "description": "I'll show you how to check CrUX or set up web-vitals RUM to confirm this improvement reflects in real user data"},
+    {"label": "Create an ADR for this optimization", "description": "Document the decision and rationale for future maintainers"},
+    {"label": "Write a benchmark test to lock in this gain", "description": "Add a Lighthouse budget or k6 threshold to CI so this regression is caught automatically"},
+    {"label": "Done for now", "description": "Close out the investigation"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+
+Present findings as a numbered summary:
+
+```
+Profiling complete. Here is what was found and fixed:
+
+Baseline: LCP = 4.2 s (measured with Lighthouse CLI, median of 3 runs)
+Bottleneck: Hero image (620 KB JPEG) discovered late; no preload; lazy-load attribute present
+Fix applied: Added <link rel="preload">, removed loading="lazy", converted to WebP (190 KB)
+Result: LCP = 1.9 s (-55%)
+No regressions: CLS unchanged at 0.02; INP unchanged at 180 ms; tests pass
+
+Suggested next steps:
+1. Verify improvement in CrUX field data (updates monthly in Search Console)
+2. Investigate INP — Lighthouse shows 180 ms (passing) but p95 may be higher in the field
+3. Set up a Lighthouse budget in CI to prevent LCP regression
+
+Reply with a number to continue, or describe the next issue to investigate.
+```