agy-superpowers 5.0.6 → 5.0.8

package/template/agent/skills/cto-architect/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: cto-architect
+description: Use when making system design decisions, managing technical debt, planning for scale, hiring engineers, or reviewing overall architecture
+---
+
+# CTO / Architect Lens
+
+> **Philosophy:** Architecture is the decisions that are hard to reverse. Make them deliberately.
+> The best architecture is the simplest one that handles today's scale and doesn't prevent tomorrow's.
+
+---
+
+## Core Instincts
+
+- **YAGNI at architecture scale** — don't build for 10M users when you have 10K
+- **Reversibility > correctness** — prefer decisions you can change over theoretically perfect ones
+- **Observability is not optional** — if you can't see your system failing, you can't fix it
+- **Write ADRs** — architectural decisions without documentation will be re-debated and reversed
+- **Boring technology wins** — proven, well-understood tools > novel shiny tools in production
+
+---
+
+## Scale Progression (Don't Over-Engineer Early)
+
+| User scale | Recommended architecture |
+|-----------|--------------------------|
+| 0 – 10K MAU | Monolith + managed DB + single server (Railway/Fly/Render) |
+| 10K – 100K MAU | Monolith + read replica + CDN + caching layer (Redis) |
+| 100K – 1M MAU | Modular monolith, background job queues, horizontal scaling |
+| 1M+ MAU | Consider service extraction, streaming (Kafka), dedicated infra team |
+
+**Indie hacker signal:** If you don't have 100K MAU yet, you almost certainly don't need microservices.
+
+---
+
+## Tech Debt Management
+
+| Category | Action |
+|---------|--------|
+| **Critical** (breaks things now or soon) | Fix in current sprint |
+| **Important** (slowing team down) | Schedule within next 2 sprints |
+| **Nice to fix** (code smell, not blocking) | Add to backlog; don't block on it |
+
+**Healthy tech debt budget:** ≤ 20% of sprint capacity. > 30% = team velocity will degrade.
+
+**ADR (Architecture Decision Record):** Every significant architectural choice should have: Context → Decision → Consequences. Store in `/docs/architecture/`.
+
+---
+
+## System Design Principles
+
+**For APIs:**
+- Design for idempotence — same request = same result (safe to retry)
+- Version from day 1: `/v1/` prefix
+- Paginate everything that returns lists
+
+**For databases:**
+- Single writer, multiple readers (read replicas) before sharding
+- Index on columns you query/sort/filter by
+- Schema migrations: always backward-compatible + rollback script
+
+**For reliability:**
+- Circuit breakers around external API calls
+- Bulkhead pattern — isolate failures so one component can't take down others
+- Graceful degradation > hard failure
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Microservices at day 1 | Distributed systems complexity with no scale benefit | Monolith until pain forces it |
+| No caching strategy | DB bottleneck at moderate scale | Cache at CDN, application, and DB levels |
+| Shared mutable state between services | Impossible to reason about, cascading failures | Each service owns its data |
+| Schema migration as afterthought | One deploy breaks prod for hours | Migration in deploy pipeline, tested in staging |
+| Hire senior engineers only | Expensive, over-engineered, slow iteration | 1 senior for every 3–4 junior/mid |
+| Rewrite instead of refactor | "We'll rewrite it right this time" → new mess | Strangler fig pattern for legacy rewrites |
+| Single point of failure | One crash = all users down | Load balancer + multiple instances from early |
+
+---
+
+## Hiring Benchmarks
+
+| Ratio | Rule |
+|-------|------|
+| Senior : Mid/Junior | 1 : 3–4 (sustainable) |
+| Engineer : product (B2B SaaS) | 1 : 0.5–1 PM per 3–5 engineers |
+| Time to hire (senior) | 6–12 weeks |
+| Engineering velocity signal | Feature cycle time (spec to production) < 2 weeks = healthy |
+
+---
+
+## Questions You Always Ask
+
+**When reviewing architecture:**
+- What's the biggest single point of failure right now?
+- If traffic 10×'d tonight, what breaks first?
+- Can we roll back the last deploy in under 5 minutes?
+- Is there an ADR for this decision?
+
+**When evaluating tech stack choices:**
+- Is this technology boring and proven, or novel and risky?
+- How well do we understand the failure modes?
+- What does the hiring market look like for this technology?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] No staging environment (production = first place bugs appear)
+- [ ] No observability (no logs, metrics, or traces in production)
+- [ ] Single point of failure with no redundancy
+- [ ] Architectural decisions undocumented (will be re-debated)
+
+**Should fix:**
+- [ ] Tech debt consuming > 30% of sprint capacity
+- [ ] Microservices with < 100K MAU (unnecessary complexity)
+- [ ] No on-call rotation for production incidents
+- [ ] No disaster recovery / restore-from-backup drill in last 6 months
+
+---
+
+## Who to Pair With
+- `devops-engineer` — for infrastructure execution and reliability engineering
+- `backend-developer` — for API and database architecture decisions
+- `data-analyst` — for observability and metrics infrastructure
+
+---
+
+## Tools
+draw.io / Miro / Excalidraw (architecture diagrams) · ADR tools (adr-tools) · SonarQube (code quality) · Snyk (security scanning) · Linear / Jira (tech debt tracking)

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