@decocms/start 0.19.0

package/.cursor/skills/deco-incident-debugging/learnings-index.md

@@ -0,0 +1,227 @@
+# Learnings Index - Quick Reference
+
+This index provides fast access to all documented learnings from past incidents. Use this during incidents to quickly find relevant solutions.
+
+**Location**: `learnings/` folder in workspace root
+
+## By Category
+
+### Cache Strategy
+
+| Learning | Key Symptoms | Quick Fix |
+|----------|--------------|-----------|
+| [cache-strategy-standardization-loaders.md](../../learnings/cache-strategy-standardization-loaders.md) | High API calls, cache misses, rate limits | Add `export const cache = "stale-while-revalidate"` |
+| [vtex-cookies-prevent-edge-caching.md](../../learnings/vtex-cookies-prevent-edge-caching.md) | `/deco/render` uncached, high origin load | Middleware to strip Set-Cookie on lazy renders |
+
+### Loader Optimization
+
+| Learning | Key Symptoms | Quick Fix |
+|----------|--------------|-----------|
+| [loader-overfetching-n-plus-problem.md](../../learnings/loader-overfetching-n-plus-problem.md) | 429 errors, high API volume, slow pages | Reduce pagination, fetch only needed data |
+| [lazy-sections-external-css-loading.md](../../learnings/lazy-sections-external-css-loading.md) | Lazy sections missing styles | Preload CSS or inline critical styles |
+
+### Block Configuration
+
+| Learning | Key Symptoms | Quick Fix |
+|----------|--------------|-----------|
+| [dangling-block-references.md](../../learnings/dangling-block-references.md) | "dangling reference" error, missing sections | Remove or update broken block references |
+| [duplicate-sections-masked-by-broken-loaders.md](../../learnings/duplicate-sections-masked-by-broken-loaders.md) | Duplicate content, hidden loader errors | Fix loader errors, remove duplicates |
+
+### Content Issues
+
+| Learning | Key Symptoms | Quick Fix |
+|----------|--------------|-----------|
+| [hardcoded-domain-urls-in-rich-text.md](../../learnings/hardcoded-domain-urls-in-rich-text.md) | Broken links in rich text, wrong domains | Use relative URLs or dynamic domain |
+
+### UI / Visual Bugs
+
+| Learning | Key Symptoms | Quick Fix |
+|----------|--------------|-----------|
+| [invisible-clickable-areas-from-empty-links.md](../../learnings/invisible-clickable-areas-from-empty-links.md) | Elements not clickable, invisible overlays | Remove empty anchor tags |
+| [responsive-breakpoint-consistency.md](../../learnings/responsive-breakpoint-consistency.md) | Mobile/desktop layout differences | Align breakpoint definitions |
+| [safari-image-flash-fix.md](../../learnings/safari-image-flash-fix.md) | Image flashing in Safari on navigation | Use CSS contain property |
+
+### VTEX Integration
+
+| Learning | Key Symptoms | Quick Fix |
+|----------|--------------|-----------|
+| [vtex-domain-routing-myvtex-vs-vtexcommercestable.md](../../learnings/vtex-domain-routing-myvtex-vs-vtexcommercestable.md) | VTEX API errors, wrong store data | Use correct domain (vtexcommercestable) |
+
+### Retry Logic
+
+| Learning | Key Symptoms | Quick Fix |
+|----------|--------------|-----------|
+| [retry-strategy-max-attempts-off-by-one.md](../../learnings/retry-strategy-max-attempts-off-by-one.md) | Fewer retries than expected, early failures | Fix off-by-one in retry loop |
+
+### Migration
+
+| Learning | Key Symptoms | Quick Fix |
+|----------|--------------|-----------|
+| [migrate-deno1-to-deno2.md](../../learnings/migrate-deno1-to-deno2.md) | Deno 2 compatibility issues | Follow migration checklist |
+| [deco-subpath-imports-version-mismatch.md](../../learnings/deco-subpath-imports-version-mismatch.md) | Import errors after updates | Align subpath import versions |
+
+---
+
+## By Symptom
+
+### Rate Limiting / 429 Errors
+
+1. **loader-overfetching-n-plus-problem.md** - Fetching too much data
+2. **cache-strategy-standardization-loaders.md** - Missing cache causing repeated calls
+
+### Slow Performance / High Latency
+
+1. **cache-strategy-standardization-loaders.md** - Missing or inconsistent caching
+2. **vtex-cookies-prevent-edge-caching.md** - Edge cache blocked by cookies
+3. **lazy-sections-external-css-loading.md** - CSS loading delays
+4. **loader-overfetching-n-plus-problem.md** - Too many API calls
+
+### Missing Content / Blank Sections
+
+1. **dangling-block-references.md** - Block points to deleted component
+2. **duplicate-sections-masked-by-broken-loaders.md** - Loader errors hidden
+
+### Visual / Layout Issues
+
+1. **invisible-clickable-areas-from-empty-links.md** - Empty links blocking clicks
+2. **responsive-breakpoint-consistency.md** - Breakpoint misalignment
+3. **safari-image-flash-fix.md** - Safari image flashing
+4. **lazy-sections-external-css-loading.md** - Missing styles on lazy sections
+
+### VTEX Errors
+
+1. **vtex-domain-routing-myvtex-vs-vtexcommercestable.md** - Wrong VTEX domain
+2. **vtex-cookies-prevent-edge-caching.md** - Cookie issues
+
+### Build / Type Errors
+
+1. **migrate-deno1-to-deno2.md** - Deno 2 migration issues
+2. **deco-subpath-imports-version-mismatch.md** - Import version conflicts
+
+---
+
+## Quick Search Commands
+
+### Find learning by keyword
+
+```bash
+# Rate limiting issues
+grep -ri "429\|rate limit\|too many" learnings/
+
+# Cache issues
+grep -ri "cache\|stale\|swr" learnings/
+
+# Performance issues
+grep -ri "slow\|performance\|ttfb\|latency" learnings/
+
+# VTEX issues
+grep -ri "vtex\|myvtex\|vtexcommerce" learnings/
+
+# Visual/UI issues
+grep -ri "css\|style\|invisible\|layout\|safari" learnings/
+
+# Block/config issues
+grep -ri "dangling\|reference\|block\|missing" learnings/
+
+# Migration issues
+grep -ri "deno\|migrate\|version\|import" learnings/
+```
+
+### List all learnings with categories
+
+```bash
+# Show category of each learning
+for f in learnings/*.md; do echo "=== $f ==="; grep -A 1 "## Category" "$f"; done
+```
+
+### Find learning by error message
+
+```bash
+# Exact error text search
+grep -ri "EXACT_ERROR_TEXT" learnings/
+
+# Partial match
+grep -ri "partial error" learnings/
+```
+
+---
+
+## Learning File Structure
+
+Each learning follows this structure:
+
+```
+# Title
+
+## Category
+[category-name]
+
+## Problem
+[Description]
+
+## Symptoms
+- Observable indicators
+
+## Root Cause
+[Explanation with code]
+
+## Solution
+[Fix with code examples]
+
+## How to Debug
+[Commands]
+
+## Files Affected
+[File patterns]
+
+## Pattern Name
+[Short name]
+
+## Checklist Item
+[One-line check]
+
+## Impact
+[Severity]
+```
+
+---
+
+## Adding New Learnings
+
+When documenting a new incident:
+
+1. **Choose a descriptive filename**: `[keyword]-[brief-description].md`
+   - Example: `cors-headers-missing-api-routes.md`
+
+2. **Pick the right category**:
+   - `cache-strategy` - Caching issues
+   - `loader-optimization` - Data fetching issues
+   - `block-config` - Deco block configuration
+   - `ui-bug` - Visual/layout issues
+   - `vtex-integration` - VTEX-specific issues
+   - `migration` - Version/migration issues
+   - `retry-logic` - Error handling patterns
+   - Or create a new category if needed
+
+3. **Include code examples**: Both problem and solution code
+
+4. **Document debug commands**: Make it reproducible
+
+5. **Update this index**: Add entry to appropriate sections
+
+---
+
+## Statistics
+
+| Metric | Count |
+|--------|-------|
+| Total Learnings | 14 |
+| Categories | 9 |
+| Cache-related | 2 |
+| Loader-related | 2 |
+| VTEX-related | 2 |
+| UI/Visual | 4 |
+| Migration | 2 |
+| Other | 2 |
+
+**Last Updated**: Check git log for learnings/ folder

package/.cursor/skills/deco-incident-debugging/triage-workflow.md

@@ -0,0 +1,312 @@
+# Triage Workflow - Fast Incident Response
+
+This workflow is optimized for **SPEED**. Follow these steps in order. Stop as soon as you identify the issue.
+
+## Step 0: Get Context (30 seconds)
+
+**Gather from the engineer:**
+
+```
+INCIDENT BRIEF:
+- Site: [site name]
+- Error/Behavior: [exact message or description]
+- Started: [when - sudden or gradual]
+- Scope: [all users? specific pages? specific browsers?]
+- Recent changes: [deployments, config, third-party]
+```
+
+## Step 1: Symptom Keyword Search (60 seconds)
+
+**Extract keywords from the error/behavior and search learnings:**
+
+| Symptom Type | Keywords to Search | Command |
+|--------------|-------------------|---------|
+| Rate limits | 429, rate limit, too many requests | `grep -ri "429\|rate limit" learnings/` |
+| Slow pages | slow, cache, ttfb, performance | `grep -ri "slow\|cache\|ttfb" learnings/` |
+| Missing content | blank, missing, not found, null | `grep -ri "missing\|not found\|blank" learnings/` |
+| Errors | error, exception, failed | `grep -ri "error\|failed\|exception" learnings/` |
+| VTEX | vtex, cart, checkout, product | `grep -ri "vtex" learnings/` |
+| Visual | css, style, invisible, layout | `grep -ri "css\|style\|invisible" learnings/` |
+| Safari | safari, webkit, ios | `grep -ri "safari\|webkit" learnings/` |
+| Images | image, flash, loading, lcp | `grep -ri "image\|flash\|lcp" learnings/` |
+| Lazy | lazy, defer, render | `grep -ri "lazy\|defer\|render" learnings/` |
+
+**If match found**: Read the learning file and jump to Step 4.
+
+## Step 2: Category-Based Search (60 seconds)
+
+**If keyword search didn't find exact match, search by category:**
+
+```bash
+# List all learnings
+ls learnings/
+
+# Read category headers
+head -20 learnings/*.md | grep -A 2 "## Category"
+```
+
+| Category | When to Check |
+|----------|---------------|
+| `cache-strategy` | Slow pages, high API calls, rate limits |
+| `loader-optimization` | Performance, N+1 queries, overfetching |
+| `block-config` | Missing sections, "not found" errors |
+| `rich-text` | Content display issues, broken links |
+| `ui-bug` | Visual problems, click issues |
+| `responsive` | Mobile/desktop differences |
+| `safari-bug` | Safari-only issues |
+| `vtex-routing` | VTEX API errors, wrong responses |
+| `migration` | Post-migration issues |
+
+## Step 3: Quick Diagnostics (2 minutes)
+
+**If no learning match, run quick diagnostics:**
+
+### 3a. Error-Based Issues
+
+```bash
+# Check error logs (last 1 hour)
+SEARCH_LOGS({ 
+  query: "level:error site:SITENAME", 
+  limit: 50,
+  startTime: "-1h",
+  endTime: "now"
+})
+
+# Group by error type
+GET_LOG_DETAILS({ 
+  query: "level:error site:SITENAME",
+  groupBy: ["body"]
+})
+```
+
+**Look for**:
+- Error message patterns
+- Stack traces pointing to specific files
+- Frequency of errors
+
+### 3b. Performance Issues
+
+```bash
+# CDN metrics
+MONITOR_SUMMARY({ 
+  sitename: "SITE", 
+  hostname: "HOST", 
+  startDate: "TODAY", 
+  endDate: "TODAY",
+  granularity: "hourly"
+})
+
+# Top error paths
+MONITOR_TOP_PATHS({
+  ...baseParams,
+  filters: [{ type: "status_code", operator: "contains", value: "5" }]
+})
+
+# Cache effectiveness
+MONITOR_CACHE_STATUS({ ...baseParams })
+```
+
+**Look for**:
+- Cache hit rate < 50% (should be >80%)
+- 5xx error spike
+- 429 rate limiting
+- Specific paths with high errors
+
+### 3c. Code Issues
+
+```bash
+# Type errors (fast check)
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | head -50
+
+# Block validation
+deno run -A https://deco.cx/validate 2>&1 | grep -E "❌|⚠️|error"
+
+# Recent changes
+git log --oneline -10
+```
+
+**Look for**:
+- New TypeScript errors after deployment
+- Invalid block configurations
+- Recent commits touching affected areas
+
+## Step 4: Apply Known Fix (if learning matched)
+
+**Read the full learning file:**
+
+```bash
+cat learnings/[MATCHED_FILE].md
+```
+
+**Verify match:**
+- [ ] Symptoms in learning match current symptoms
+- [ ] Root cause explanation makes sense for this case
+- [ ] Solution is applicable to this site
+
+**Apply solution:**
+1. Follow the code examples in the learning
+2. Test the fix locally if possible
+3. Deploy with confidence
+
+## Step 5: Unknown Issue - Deep Dive
+
+**If no learning matches, gather comprehensive data:**
+
+### 5a. Full Error Context
+
+```bash
+# Extended error search
+SEARCH_LOGS({ 
+  query: "level:error site:SITENAME path:AFFECTED_PATH", 
+  limit: 100
+})
+
+# Error timeline
+QUERY_CHART_DATA({
+  series: [{
+    dataSource: "events",
+    aggFn: "count",
+    where: "level:error site:SITENAME",
+    groupBy: ["body"]
+  }],
+  granularity: "5 minute",
+  startTime: "-6h"
+})
+```
+
+### 5b. Code Investigation
+
+```bash
+# Find the affected file
+grep -r "ERROR_KEYWORD" sections/ loaders/ actions/
+
+# Read the file
+cat [AFFECTED_FILE]
+
+# Check git blame
+git blame [AFFECTED_FILE] | head -50
+
+# Check recent changes to file
+git log -5 --oneline -- [AFFECTED_FILE]
+```
+
+### 5c. Runtime Investigation
+
+```bash
+# Check server timing
+curl -sI "https://SITE.com/affected-page?__d" | grep server-timing
+
+# Check response headers
+curl -sI "https://SITE.com/affected-page" | grep -i "cache\|set-cookie\|x-"
+
+# Check for specific loader
+curl -s "https://SITE.com/live/invoke/site/loaders/[LOADER]" | jq '.'
+```
+
+## Step 6: Document Novel Issue
+
+**If this is a new pattern, create a learning:**
+
+```bash
+# Create new learning file
+touch learnings/[descriptive-name].md
+```
+
+**Template:**
+
+```markdown
+# [Title - Descriptive Problem Name]
+
+## Category
+[category-name]
+
+## Problem
+[Clear description of what went wrong]
+
+## Symptoms
+- [Observable indicator 1]
+- [Observable indicator 2]
+- [Error message if applicable]
+
+## Root Cause
+[Explanation with code examples showing the problem]
+
+\`\`\`typescript
+// PROBLEM CODE
+\`\`\`
+
+## Solution
+[How to fix with code examples]
+
+\`\`\`typescript
+// FIXED CODE
+\`\`\`
+
+## How to Debug
+\`\`\`bash
+# Commands to diagnose this issue
+\`\`\`
+
+## Files Affected
+- [File pattern 1]
+- [File pattern 2]
+
+## Pattern Name
+[Short memorable name]
+
+## Checklist Item
+[One-line check for future audits]
+
+## Impact
+[What happens if unfixed - severity and scope]
+```
+
+## Decision Tree
+
+```
+START: What is the primary symptom?
+│
+├─► Rate Limit / 429
+│   └─► Check: loader-overfetching, cache-strategy learnings
+│       ├─► Match? Apply fix
+│       └─► No match? Check for missing cache exports, N+1 queries
+│
+├─► Slow Page / High Latency
+│   └─► Check: cache-strategy, lazy-sections, vtex-cookies learnings
+│       ├─► Match? Apply fix
+│       └─► No match? Run MONITOR_CACHE_STATUS, check for uncached loaders
+│
+├─► Missing Content / Blank Areas
+│   └─► Check: dangling-block, duplicate-sections learnings
+│       ├─► Match? Apply fix
+│       └─► No match? Run block validation, check browser console
+│
+├─► Visual / UI Bug
+│   └─► Check: invisible-clickable, responsive, safari, lazy-css learnings
+│       ├─► Match? Apply fix
+│       └─► No match? Inspect DOM, check CSS loading order
+│
+├─► VTEX Error
+│   └─► Check: vtex-domain, vtex-cookies learnings
+│       ├─► Match? Apply fix
+│       └─► No match? Check VTEX status, verify credentials
+│
+└─► Unknown Error
+    └─► Run full diagnostics (Step 3a-3c)
+        └─► Create new learning when resolved
+```
+
+## Speed Tips
+
+1. **Parallel searches**: Run multiple grep commands at once
+2. **Use exact error text**: Copy-paste errors for precise matching
+3. **Check recent deploys first**: Most incidents follow deployments
+4. **Trust the learnings**: If symptoms match, the fix likely works
+5. **Don't over-investigate**: If you find a match, apply it and verify
+
+## Common Pitfalls
+
+- **Over-diagnosing**: Stop investigating once you find the cause
+- **Ignoring learnings**: Always check learnings before deep diving
+- **Missing scope**: Verify if issue is widespread or isolated
+- **Forgetting to document**: Novel issues must become learnings