agy-superpowers 5.0.7 → 5.0.8

package/template/agent/skills/customer-success-manager/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: customer-success-manager
+description: Use when managing user support, building feedback loops, tracking NPS/CSAT, handling churn, or building a customer-centric culture
+---
+
+# Customer Success Manager Lens
+
+> **Philosophy:** Customer success is proactive, not reactive. Support is reactive.
+> A user who succeeds doesn't churn. A user who churns was never fully successful.
+
+---
+
+## Core Instincts
+
+- **Proactive > reactive** — reach out before users struggle, not after they cancel
+- **Churn happens before cancellation** — disengagement is the real churn event (usually 2–4 weeks before cancel)
+- **Every complaint is a gift** — unhappy users who complain are giving you free product research; silent churners aren't
+- **Response time = trust signal** — slow responses signal that you don't care about users
+- **Success = users achieving their goal** — not "user didn't cancel yet"
+
+---
+
+## Response Time SLAs
+
+| Priority | Situation | SLA |
+|----------|-----------|-----|
+| **P1 — Critical** | App is down, data loss, payment issue | < 1 hour |
+| **P2 — High** | Core feature broken, blocking user's work | < 4 hours |
+| **P3 — Medium** | Non-blocking bug, confusion with feature | < 24 hours |
+| **P4 — Low** | Feature request, general question | < 48 hours |
+
+**First response time benchmarks:** < 5 minutes = exceptional; < 1 hour = good; > 4 hours = churn risk.
+
+---
+
+## NPS Interpretation
+
+| Score | Interpretation | Action |
+|-------|---------------|--------|
+| > 70 | World-class | Leverage promoters for referrals and testimonials |
+| 50–70 | Excellent | Double down on what promoters love |
+| 30–50 | Good | Investigate and convert passives (7–8) |
+| 0–30 | Needs work | Focus on detractors — what's the consistent complaint? |
+| < 0 | Crisis | Deep qualitative research required immediately |
+
+**NPS survey timing:** Send after first success event, not on sign-up. Re-survey every 90 days.
+
+---
+
+## Churn Signal Detection
+
+| Signal | Days before churn (avg) | Action |
+|--------|------------------------|--------|
+| No login for 7 days | 14–21 days | Automated re-engagement + personal email |
+| Support ticket marked unresolved | 3–7 days | Escalate and personal follow-up |
+| Downgrade plan | 0–14 days | Check-in call or personalized offer |
+| Opened cancellation page | 0–3 days | Trigger save flow immediately |
+| Multiple failed payments | 0–7 days | Dunning email sequence (3 emails over 7 days) |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Auto-close support tickets without resolution | Users re-open, feel dismissed | Confirmation before closing: "Did we solve this?" |
+| Generic reply templates | Feel like a robot, destroy trust | Personalize every reply (use name, reference issue) |
+| No cancel/churn flow | 20–40% of cancellers are saveable | Pause option, downgrade option, discount offer |
+| Collect NPS without acting on feedback | Users stop responding ("useless surveys") | Close the loop: tell users what you changed |
+| Reply only to 5-star reviews | 1-star respondents are the most valuable | Respond to every 1–3 star review publicly |
+| Treat all churn equally | Different churn reasons need different solutions | Segment: voluntary vs involuntary, reason codes |
+
+---
+
+## Dunning (Failed Payment Recovery)
+
+```
+Day 0: First failed charge → Email: friendly heads-up, update card CTA
+Day 3: Second attempt + Email: "Is this the right card?"
+Day 7: Third attempt + Email: "Your account access is at risk"
+Day 14: Cancellation + Email: "We hate to see you go — here's how to reactivate"
+```
+
+**Involuntary churn (failed payments) = typically 20–40% of all churn.** Always set up dunning.
+
+---
+
+## Questions You Always Ask
+
+**When reviewing CS operations:**
+- What's the current first response time? (P2 benchmark: < 4 hours)
+- What's the most common support ticket category? (Pattern = product/UX issue)
+- What's the NPS, and are we surveying at the right time?
+- What % of churn is voluntary vs involuntary?
+
+**When a user churns:**
+- Did we get exit survey data? What was the stated reason?
+- Were there warning signals we could have acted on earlier?
+- Is this a one-off or a pattern we see across multiple users?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] P1 response time > 4 hours
+- [ ] No exit survey on cancellation
+- [ ] No dunning email sequence for failed payments
+- [ ] NPS < 0 with no active investigation
+
+**Should fix:**
+- [ ] No churn signal tracking (usage drop, login frequency)
+- [ ] Support tickets closed without user confirmation
+- [ ] NPS survey sent on day 1 (too early)
+
+---
+
+## Who to Pair With
+- `retention-specialist` — for proactive retention and churn prevention
+- `product-manager` — convert support patterns into product improvements
+- `data-analyst` — for churn analysis and cohort health monitoring
+
+---
+
+## Tools
+Intercom · Crisp · HelpScout · Zendesk (support) · Delighted · Typeform (NPS) · Stripe Radar / Chargebee (dunning)

package/template/agent/skills/data-analyst/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: data-analyst
+description: Use when setting up metrics frameworks, analyzing funnels, running cohort analysis, designing dashboards, or evaluating A/B test results
+---
+
+# Data Analyst Lens
+
+> **Philosophy:** If you can't measure it, you can't improve it — but measuring the wrong thing is worse than measuring nothing.
+> Good data asks better questions. It rarely answers them alone.
+
+---
+
+## Core Instincts
+
+- **North Star Metric first** — one metric that best captures value delivered to users
+- **Correlation ≠ causation** — always ask "what else changed?" before attributing a result
+- **Segment always** — averages hide everything; cohort and segment data reveals reality
+- **Lagging vs leading indicators** — revenue is lagging (past); activation is leading (predicts future)
+- **Statistical significance is a bar, not a target** — p < 0.05 means 1 in 20 tests will false-positive
+
+---
+
+## North Star Metric Selection
+
+| Product Type | Example North Star Metric |
+|-------------|--------------------------|
+| Productivity / Utility | Tasks completed per week |
+| Health / Fitness | Workouts logged per month |
+| Social | Messages sent per DAU |
+| E-commerce | Revenue per monthly visitor |
+| SaaS / B2B | Weekly active seats |
+| Mobile subscription | D30 retained paying users |
+
+**NSM must:** correlate with revenue, be measurable weekly, be understandable by the whole team.
+
+---
+
+## Standard Metrics Framework
+
+```
+Acquisition:  CAC, installs, signups, traffic source breakdown
+Activation:   Activation rate, time-to-aha-moment, onboarding completion %
+Retention:    D1/D7/D30 retention, DAU/MAU ratio, session frequency
+Revenue:      MRR, ARR, ARPU, LTV, churn rate (voluntary + involuntary)
+Referral:     Viral coefficient K, NPS, referral program conversion
+```
+
+**DAU/MAU ratio** = engagement quality indicator:
+- > 50% = highly engaging (social / gaming)
+- 20–40% = good (productivity tools)
+- < 10% = low engagement / retention problem
+
+---
+
+## A/B Test Significance
+
+| Metric | Requirement |
+|--------|-------------|
+| Sample size per variant | ≥ 1,000 (for conversion rates) |
+| Minimum test duration | 2 weeks (captures weekly patterns) |
+| Statistical significance | p < 0.05 (95% confidence) |
+| Practical significance | Δ > 5% (otherwise not actionable) |
+| Type I error risk | 5% — 1 in 20 "significant" results is false positive |
+| Type II error | Run power analysis before test (sample size calculator) |
+
+**Never stop a test early** — stopping when significance is first reached inflates Type I error rate.
+
+---
+
+## Cohort Analysis Interpretation
+
+```
+Week 0 cohort: users who signed up in week 0
+Retention at Day 30 = % of week 0 cohort still active on day 30
+
+Healthy retention curve: steep drop Day 0→7, then flattens (users who stay, stay)
+Unhealthy curve: no flattening, continues declining → no core retained audience
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Report averages only | Averages hide bimodal distributions | Report medians + percentiles (p50, p90, p99) |
+| Declare test winner before reaching significance | False positive — winner may be noise | Predetermined sample size + duration |
+| Track everything, focus on nothing | Data overload → analysis paralysis | 3–5 top metrics per team |
+| Compare dissimilar cohorts | Apples vs oranges | Cohort by signup date, not current period |
+| Attribute all growth to last-click | Multi-touch attribution required | Use first-touch + last-touch + time-decay models |
+| Ignore data quality | Garbage in, garbage out | Instrument → validate → trust |
+
+---
+
+## Questions You Always Ask
+
+**When setting up metrics:**
+- What is the North Star Metric, and how often can we measure it?
+- Is this a leading or lagging indicator?
+- How will data be collected — are there gaps in instrumentation?
+
+**When analyzing a result:**
+- Is the sample size large enough for significance?
+- Could a confounding variable explain this change?
+- Does the result hold when segmented by cohort/device/acquisition source?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] No North Star Metric defined
+- [ ] A/B tests declared significant before reaching 1,000 per variant
+- [ ] No event tracking on key activation events
+- [ ] Reporting only total signups / installs (not activated users)
+
+**Should fix:**
+- [ ] No cohort retention analysis (only aggregate retention)
+- [ ] All metrics reported as averages (no percentiles)
+- [ ] Dashboard not reviewed in weekly team ritual
+
+---
+
+## Who to Pair With
+- `growth-hacker` — for AARRR funnel analysis and experiment design
+- `product-manager` — for North Star Metric definition and outcome tracking
+- `retention-specialist` — for retention curve and churn cohort analysis
+
+---
+
+## Key Formulas
+
+```
+MRR              = paying_users × ARPU
+ARR              = MRR × 12
+LTV              = ARPU / monthly_churn_rate
+CAC              = total_acquisition_spend / new_customers
+LTV:CAC ratio    ≥ 3:1
+DAU/MAU ratio    = (DAU / MAU) × 100%
+Viral coeff. K   = invites_per_user × invite_conversion_rate
+Monthly churn    = churned_this_month / users_start_of_month
+```
+
+---
+
+## Tools
+Mixpanel · Amplitude · PostHog (self-hosted) · Metabase · Google Looker Studio · Statsig / LaunchDarkly (experiment platform) · Segment (data pipeline) · BigQuery / Redshift (data warehouse)

package/template/agent/skills/devops-engineer/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: devops-engineer
+description: Use when working on CI/CD pipelines, infrastructure, deployment, monitoring, or reliability engineering — regardless of cloud provider
+---
+
+# DevOps Engineer Lens
+
+> **Philosophy:** Automate everything deployable. Observe everything running. Fail safely, recover fast.
+> If it's not in version control, it doesn't exist. If it's not monitored, it will fail silently.
+
+---
+
+## ⚠️ ASK BEFORE ASSUMING
+
+| What | Why it matters |
+|------|----------------|
+| **Cloud provider?** AWS / GCP / Azure / Fly / Railway | Determines services and tooling |
+| **Team size?** Solo / small team | Determines complexity vs value trade-offs |
+| **Current deploy process?** Manual / CI/CD | Determines where to start |
+| **SLO requirements?** 99.9% / 99.99% | Drives infrastructure decisions |
+
+When unspecified, assume small team + Docker + GitHub Actions + managed cloud (Railway/Fly/Render).
+
+---
+
+## Core Instincts
+
+- **Immutable infrastructure** — never SSH to patch production; redeploy instead
+- **Observability-first** — logs, metrics, traces before adding features
+- **Fail fast, recover faster** — MTTR matters more than MTBF for indie hackers
+- **Automate the deploy path** — every manual step is a future incident waiting to happen
+- **Secrets are not config** — credentials never live in code or environment variables baked into images
+
+---
+
+## Reliability Thresholds
+
+| SLO | Allowed downtime/month | Allowed downtime/year |
+|-----|----------------------|----------------------|
+| 99% | 7.3 hours | 3.65 days |
+| 99.5% | 3.6 hours | 1.83 days |
+| **99.9%** | **43 minutes** | **8.7 hours** |
+| 99.95% | 21 minutes | 4.4 hours |
+| 99.99% | 4.3 minutes | 52 minutes |
+
+**For indie hackers:** 99.9% is the right target. 99.99% requires significant investment — only worth it when downtime costs > infra cost.
+
+**Key metrics:**
+- **MTTR** (Mean Time to Recovery): target < 15min for P1 incidents
+- **MTBF** (Mean Time Between Failures): track over rolling 30 days
+- **Deploy frequency**: healthy = multiple times/day; red flag = < once/week
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Deploy directly from local machine | "Works on my machine" incidents, no audit trail | CI/CD pipeline always |
+| No staging environment | Production = first time bugs are discovered | Staging that mirrors prod |
+| Secrets in `.env` committed to git | One git history leak = all creds compromised | Doppler / AWS Secrets Manager / Vault |
+| Long-lived feature branches | Merge conflicts, integration hell | Trunk-based dev + feature flags |
+| No rollback plan | Bad deploy = extended outage | Blue-green or canary + 1-click rollback |
+| Alerts on everything | Alert fatigue = ignored alerts | Page only on SLO breaches, not symptoms |
+| Manual database migrations | Easy to forget, easy to run wrong order | Migration runner in deploy pipeline |
+
+---
+
+## Questions You Always Ask
+
+**When designing infrastructure:**
+- What's the rollback plan if this deploy goes wrong?
+- What does a 10x traffic spike do to this setup?
+- How long does a full restore from backup take?
+- Who gets paged when this fails at 3am?
+
+**When reviewing CI/CD:**
+- Does every PR get tested before merge?
+- Are secrets injected at runtime, not baked into images?
+- Is the deploy pipeline idempotent (safe to re-run)?
+
+---
+
+## Red Flags in Code Review / Infrastructure Review
+
+**Must fix:**
+- [ ] Secrets in source code, Dockerfiles, or `.env` committed to repo
+- [ ] No health check endpoint on services
+- [ ] No automated tests in CI pipeline
+- [ ] Manual production deploys with no audit trail
+
+**Should fix:**
+- [ ] No staging environment (or staging diverged from prod)
+- [ ] Database backups untested (backup ≠ restore test)
+- [ ] Alerts firing on every error (not SLO-based)
+- [ ] Single point of failure with no redundancy
+
+---
+
+## Who to Pair With
+- `backend-developer` — for deployment architecture of APIs
+- `data-analyst` — for metrics pipeline and observability stack
+- `cto-architect` — for scaling decisions and infrastructure design
+
+---
+
+## Tool Reference
+
+| Category | Tools |
+|----------|-------|
+| CI/CD | GitHub Actions, GitLab CI, CircleCI |
+| Container | Docker, Kubernetes (k8s when you have a team), Fly.io, Railway |
+| Secrets management | Doppler, AWS Secrets Manager, 1Password Secrets |
+| Monitoring | Datadog, Grafana + Prometheus, Better Uptime |
+| Error tracking | Sentry, Bugsnag |
+| Logging | Papertrail, Logtail, CloudWatch |
+| IaC | Terraform, Pulumi (for teams), SST (for AWS serverless) |

package/template/agent/skills/email-infrastructure/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: email-infrastructure
+description: Use when setting up transactional email, managing deliverability, configuring SPF/DKIM/DMARC, building email templates, or debugging email delivery issues
+---
+
+# Email Infrastructure Lens
+
+> **Philosophy:** Deliverability is a reputation game. One spam complaint can blacklist your domain for weeks.
+> Transactional email is infrastructure — it must be reliable, observable, and tenant-isolated.
+
+---
+
+## Core Instincts
+
+- **Domain reputation is fragile** — separate transactional from marketing; don't let bulk mail ruin auth emails
+- **Sending ≠ delivering** — always verify delivery via bounce/open tracking and suppression lists
+- **Never send from your root domain** — use a subdomain (`mail.yourdomain.com`) to protect your primary domain's reputation
+- **Warm up new IPs/domains** — cold domains go to spam; ramp gradually
+- **Unsubscribes are legal obligations** — CAN-SPAM, GDPR require easy opt-out
+
+---
+
+## Email Type Separation
+
+| Type | Examples | Volume | Sender domain | Provider pool |
+|------|----------|--------|---------------|--------------|
+| **Transactional** | Password reset, invoice, welcome | Low | `mail.yourdomain.com` | Dedicated / transactional |
+| **Lifecycle / product** | Trial ending, usage nudges | Medium | `mail.yourdomain.com` | Dedicated / transactional |
+| **Marketing / newsletters** | Product updates, promotions | High | `newsletter.yourdomain.com` | Separate / marketing |
+
+❗ **Critical:** Marketing and transactional must use separate sending pools. A spam complaint on a newsletter should never affect password reset delivery.
+
+---
+
+## DNS Authentication (Must Have)
+
+```
+SPF (Sender Policy Framework)
+  → Declares which IPs are allowed to send email from your domain
+  → Add to DNS: TXT record on yourdomain.com
+  → Example: "v=spf1 include:sendgrid.net include:resend.com ~all"
+  → Max 10 DNS lookups (hard limit); use flattening tools if exceeded
+
+DKIM (DomainKeys Identified Mail)
+  → Cryptographic signature proving email wasn't tampered with
+  → Your ESP generates CNAME records; add to DNS
+  → Check: "selector._domainkey.yourdomain.com"
+
+DMARC (Domain-based Message Authentication)
+  → Policy: what to do with emails that fail SPF/DKIM
+  → Start: p=none (monitor) → move to p=quarantine → p=reject
+  → Add: _dmarc.yourdomain.com TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"
+  → DMARC aggregate reports tell you who's failing and why
+
+Required order: SPF → DKIM → DMARC
+Without all three: Google/Yahoo bulk sender requirements (2024) → emails rejected
+```
+
+---
+
+## Deliverability Rules
+
+| Rule | Why |
+|------|-----|
+| Spam complaint rate < **0.08%** | Google/Yahoo threshold; above = Gmail blocks |
+| Hard bounce rate < **2%** | Remove bounced emails immediately |
+| List hygiene: unverified emails | Never send to addresses that haven't confirmed |
+| Unsubscribe link required | CAN-SPAM (US) + GDPR (EU) legal requirement |
+| One-click unsubscribe (RFC 8058) | Gmail requires for bulk senders (> 5K/day) |
+| Text version alongside HTML | Many spam filters penalize HTML-only |
+
+---
+
+## Email Queue Architecture
+
+```
+❌ NEVER send email synchronously in request handler:
+  POST /reset-password → send email → respond
+
+✅ Queue email jobs:
+  POST /reset-password → create job in queue → respond 200
+                                ↓ (async)
+                         Worker picks up job → send via ESP → log result
+
+Why: Email sending can take 1–3 seconds; timeouts → duplicate sends → user frustration
+Queue retry: 3 attempts with exponential backoff (1s, 5s, 30s)
+```
+
+---
+
+## Template Best Practices
+
+```
+Structure:
+- Max width: 600px (renders correctly in all clients)
+- Always include plaintext alternative
+- Inline CSS only (Gmail strips <style> blocks)
+- Images: always include alt text; assume images are blocked
+- CTA button: use table-based HTML (VML for Outlook)
+
+Testing:
+- Litmus / Email on Acid for client rendering
+- SpamAssassin score < 2 (most spam filters use SA)
+- Check: mail-tester.com (free quick test)
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Send from root domain | Spam complaints = root domain blacklisted | Use `mail.yourdomain.com` subdomain |
+| Marketing + transactional same pool | Marketing spam rates kill auth email delivery | Separate sender pools |
+| No SPF/DKIM/DMARC | Emails rejected by Gmail/Yahoo (2024 policy) | Configure all three before launch |
+| Retry email without checking bounces | Sending to bounced emails = reputation damage | Remove hard bounces immediately |
+| Suppress all email on one unsubscribe | User unsubscribes from marketing, loses auth emails | Separate marketing vs transactional opt-out lists |
+| Send email synchronously in API handler | Timeouts → duplicate sends → user sees email twice | Job queue always |
+
+---
+
+## Questions You Always Ask
+
+**When setting up email:**
+- Are SPF, DKIM, and DMARC configured? (Check: `mxtoolbox.com`)
+- Are transactional and marketing emails on separate sending pools?
+- Is email sending queued (not synchronous in the request)?
+- What happens when an email bounces? Is the address suppressed?
+
+**When debugging delivery issues:**
+- What does the ESP delivery log show? Was it accepted or rejected?
+- Is the DMARC report showing authentication failures?
+- What's the spam complaint rate this week?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] No DKIM/SPF/DMARC configured (emails fail Gmail/Yahoo)
+- [ ] Transactional and marketing sent from same pool
+- [ ] Bounced addresses not being suppressed
+- [ ] Email sent synchronously in request handler
+
+**Should fix:**
+- [ ] No plaintext version of HTML emails
+- [ ] No DMARC report monitoring
+- [ ] Unsubscribe doesn't work within 10 seconds (CAN-SPAM requirement)
+
+---
+
+## Who to Pair With
+- `backend-developer` — for queue implementation and webhook handling
+- `security-engineer` — for email token security (reset links, magic links)
+- `devops-engineer` — for DNS configuration and monitoring
+
+---
+
+## Tools
+**ESP:** Resend · SendGrid · Postmark · AWS SES  
+**Testing:** mail-tester.com · Litmus · Email on Acid  
+**DNS check:** MXToolbox · DMARC Analyzer  
+**Templates:** React Email · MJML  
+**Queue:** BullMQ / Inngest / Trigger.dev

package/template/agent/skills/frontend-developer/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: frontend-developer
+description: Use when building web UI, designing component architecture, or reviewing frontend code — regardless of framework (React, Vue, Svelte, etc.)
+---
+
+# Frontend Developer Lens
+
+> **Philosophy:** Component-first. User-perception-first. Accessibility is not optional.
+> Performance is felt by users, not measured in isolation.
+
+---
+
+## ⚠️ ASK BEFORE ASSUMING
+
+If the stack is unspecified, **DO NOT default to Create React App**. Ask:
+
+| What | Why it matters |
+|------|----------------|
+| **Framework?** React / Vue / Svelte / vanilla | Determines patterns, tooling, idioms |
+| **Rendering?** CSR / SSR / SSG / ISR | SEO and performance strategy |
+| **Design system?** Custom / Tailwind / MUI / shadcn | Styling approach and constraints |
+| **Target browsers?** Modern / IE support? | Determines APIs and CSS you can use |
+
+When stack is unspecified, assume React + TypeScript + Next.js (App Router).
+
+---
+
+## Core Instincts
+
+- **User perception is reality** — loading states, micro-animations, and feedback loops matter as much as the happy path
+- **Accessibility is load-bearing** — keyboard nav, screen readers, and contrast ratios affect real users
+- **Render cost is real** — unnecessary re-renders degrade UX; measure before optimizing
+- **Web Vitals are felt** — LCP, CLS, INP directly impact user satisfaction and SEO
+- **Mobile is primary** — design mobile-first; test at real viewport sizes on real devices
+
+---
+
+## Web Vitals Thresholds (Google Standard)
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| **LCP** (Largest Contentful Paint) | < 2.5s | 2.5–4s | > 4s |
+| **INP** (Interaction to Next Paint) | < 200ms | 200–500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | < 0.1 | 0.1–0.25 | > 0.25 |
+| **FCP** (First Contentful Paint) | < 1.8s | 1.8–3s | > 3s |
+| **TTFB** (Time to First Byte) | < 800ms | 800ms–1.8s | > 1.8s |
+
+---
+
+## Bundle Size Guidelines
+
+| Bundle | Target | Action needed |
+|--------|--------|---------------|
+| Main JS (gzipped) | < 200KB | > 400KB: audit imports, code-split |
+| Per-route chunk | < 50KB | > 100KB: lazy load heavy deps |
+| CSS (gzipped) | < 50KB | > 100KB: purge unused styles |
+| Images (hero) | < 200KB | Use `next/image` or WebP + lazy load |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Skip loading/error/empty states | User thinks the app is broken | Always handle all 3 async states |
+| `onClick` only (no keyboard handler) | Keyboard users excluded | Use `<button>`; it's free keyboard support |
+| Index as list `key` in dynamic lists | Reorder causes state and animation bugs | Unique stable ID from data |
+| Images without `alt` or explicit dimensions | Screen reader fail + CLS score hit | `alt` always; `width`/`height` or `aspect-ratio` always |
+| `<div>` for interactive elements | Not focusable, not semantic, no ARIA | Use `<button>`, `<a>`, or explicit `role` + `tabIndex` |
+| Sequential `await` for independent fetches | Each waits on the previous (waterfall) | `Promise.all([fetchA(), fetchB()])` |
+| Barrel exports in app code (`index.ts`) | Defeats tree-shaking, slow cold start | Import directly from the source file |
+| Import entire library for one function | Bundle bloat (e.g., `import _ from 'lodash'`) | Named import or specific entry (`lodash/debounce`) |
+| Client fetch where SSR/SSG would work | Slower FCP, worse SEO | Server-render or static-generate whenever possible |
+
+---
+
+## Accessibility Quick Rules
+
+| Rule | Detail |
+|------|--------|
+| Color contrast (normal text) | ≥ 4.5:1 against background (WCAG AA) |
+| Color contrast (large text, ≥18pt) | ≥ 3:1 against background |
+| Touch / click target size | ≥ 44×44px (WCAG 2.5.5, Level AAA) |
+| Focus indicator | Must be visible; `outline: none` without replacement is a violation |
+| Form inputs | Must have `<label>` (associated via `for`/`id` or wrapping) |
+| Images | Decorative → `alt=""`, informative → descriptive `alt` |
+| Interactive elements order | DOM order must match visual order for keyboard users |
+
+---
+
+## Questions You Always Ask
+
+**When planning UI:**
+- What's the loading state? The error state? The empty state?
+- Is this accessible to keyboard and screen reader users?
+- What does this look like at 375px? At 1440px?
+- Is this content crawlable by search engines (SSR or SSG)?
+
+**When reviewing components:**
+- Does this cause layout shift (CLS)? Are image dimensions declared?
+- Can a user complete this entire flow using only the keyboard?
+- Is every form input associated with a visible `<label>`?
+- What's the bundle size delta from this new dependency?
+
+---
+
+## Red Flags in Code Review
+
+**Must fix:**
+- [ ] No loading/error/empty states for async data
+- [ ] Interactive elements unreachable by keyboard
+- [ ] Images without `alt` text or explicit dimensions (CLS risk)
+- [ ] Form inputs without associated `<label>` elements
+- [ ] Color contrast below 4.5:1 for body text
+
+**Should fix:**
+- [ ] Missing unique identifiers for list items
+- [ ] Large dependencies added without bundle size justification
+- [ ] Client-side fetch where server-rendering would work
+- [ ] `outline: none` without visible focus replacement
+
+---
+
+## Performance Debugging Checklist
+
+```
+Slow initial load  → Check bundle size, server render, remove unused deps
+Layout shift (CLS) → Set image dimensions, avoid injecting content above fold
+Janky interaction  → Use CSS transforms, avoid forced layout (getBoundingClientRect in loops)
+Too many re-renders → React DevTools Profiler → memo, useMemo, useCallback
+Slow data fetch    → Parallel with Promise.all(), SWR/React Query for cache
+Large images       → WebP format, srcset for responsive, lazy loading
+```