swe-workflow-skills 0.1.0

package/skills/performance-optimization/references/bottleneck-patterns.md

@@ -0,0 +1,256 @@
+# Bottleneck Detection Patterns
+
+## Contents
+- Database bottlenecks
+- Algorithmic bottlenecks
+- Memory bottlenecks
+- Network and I/O bottlenecks
+- Frontend-specific bottlenecks
+- Caching strategies
+
+## Database Bottlenecks
+
+### N+1 Query Problem
+
+**Signature**: A loop that makes one database query per iteration.
+
+```javascript
+// BAD: N+1 — 1 query for orders + N queries for users
+const orders = await db.orders.findMany();
+for (const order of orders) {
+  order.user = await db.users.findById(order.userId); // N queries!
+}
+
+// GOOD: Eager loading — 2 queries total
+const orders = await db.orders.findMany({
+  include: { user: true }
+});
+
+// GOOD: Batch loading — 2 queries total
+const orders = await db.orders.findMany();
+const userIds = [...new Set(orders.map(o => o.userId))];
+const users = await db.users.findMany({ where: { id: { in: userIds } } });
+const userMap = new Map(users.map(u => [u.id, u]));
+orders.forEach(o => o.user = userMap.get(o.userId));
+```
+
+**How to detect**: Look for database calls inside loops, `.map()`, `.forEach()`, or Promise.all with individual queries. Also check ORM lazy-loading that triggers queries on property access.
+
+### Missing Indexes
+
+**Signature**: Slow queries on columns used in WHERE, JOIN, ORDER BY, or GROUP BY.
+
+```sql
+-- If this is slow, check if there's an index on user_id and created_at
+SELECT * FROM orders
+WHERE user_id = 123
+ORDER BY created_at DESC
+LIMIT 20;
+
+-- Fix: Add a compound index
+CREATE INDEX idx_orders_user_id_created_at ON orders(user_id, created_at DESC);
+```
+
+**How to detect**: Run `EXPLAIN ANALYZE` on slow queries. Look for "Seq Scan" on large tables — that usually means a missing index.
+
+**Index rules of thumb:**
+- Index columns in WHERE clauses that filter large tables
+- Index columns in JOIN conditions
+- Compound indexes should match the query's column order
+- Don't index columns with very low cardinality (boolean flags on huge tables)
+- Every index slows writes — don't over-index
+
+### SELECT * Anti-pattern
+
+**Signature**: Selecting all columns when only a few are needed.
+
+```javascript
+// BAD: Loads entire row including large text columns
+const users = await db.query('SELECT * FROM users');
+
+// GOOD: Only fetch what's needed
+const users = await db.query('SELECT id, name, email FROM users');
+```
+
+Especially impactful when tables have large TEXT/BLOB columns or many unused columns.
+
+### Unoptimized Pagination
+
+**Signature**: Using OFFSET on large tables.
+
+```sql
+-- BAD: Database must scan and discard 100,000 rows
+SELECT * FROM events ORDER BY created_at OFFSET 100000 LIMIT 20;
+
+-- GOOD: Cursor-based — database seeks directly
+SELECT * FROM events
+WHERE created_at < '2025-01-15T10:00:00Z'
+ORDER BY created_at DESC
+LIMIT 20;
+```
+
+OFFSET performance degrades linearly with page number. Cursor-based pagination is O(1).
+
+## Algorithmic Bottlenecks
+
+### Hidden O(n²)
+
+**Signature**: Nested loops over collections, often disguised as `.includes()`, `.find()`, or `.indexOf()` inside a loop.
+
+```javascript
+// BAD: O(n²) — includes() scans the array each time
+const uniqueItems = [];
+for (const item of items) {
+  if (!uniqueItems.includes(item)) {
+    uniqueItems.push(item);
+  }
+}
+
+// GOOD: O(n) — Set has O(1) lookup
+const uniqueItems = [...new Set(items)];
+```
+
+```javascript
+// BAD: O(n*m) — find() inside map()
+const enriched = orders.map(order => ({
+  ...order,
+  user: users.find(u => u.id === order.userId) // O(m) per order
+}));
+
+// GOOD: O(n+m) — build lookup map first
+const userMap = new Map(users.map(u => [u.id, u]));
+const enriched = orders.map(order => ({
+  ...order,
+  user: userMap.get(order.userId) // O(1) per order
+}));
+```
+
+### Unnecessary Computation
+
+**Signature**: Recalculating something in every request/loop that doesn't change.
+
+```javascript
+// BAD: Parsing config on every request
+app.get('/data', (req, res) => {
+  const config = JSON.parse(fs.readFileSync('config.json')); // Every request!
+  // ...
+});
+
+// GOOD: Parse once at startup
+const config = JSON.parse(fs.readFileSync('config.json'));
+app.get('/data', (req, res) => {
+  // Use pre-parsed config
+});
+```
+
+## Memory Bottlenecks
+
+### Loading Entire Datasets
+
+**Signature**: Reading all rows into memory instead of streaming or paginating.
+
+```javascript
+// BAD: Loads 1M rows into memory
+const allUsers = await db.users.findMany();
+const csv = allUsers.map(u => `${u.name},${u.email}`).join('\n');
+
+// GOOD: Stream rows
+const stream = db.users.stream();
+for await (const user of stream) {
+  writeChunk(`${user.name},${user.email}\n`);
+}
+```
+
+### Unbounded Caches
+
+**Signature**: In-memory cache with no size limit or eviction policy.
+
+```javascript
+// BAD: Grows forever
+const cache = {};
+function getData(key) {
+  if (!cache[key]) cache[key] = fetchExpensiveData(key);
+  return cache[key];
+}
+
+// GOOD: LRU cache with max size
+const cache = new LRUCache({ max: 1000, ttl: 1000 * 60 * 5 });
+```
+
+### Event Listener Leaks
+
+**Signature**: Adding event listeners without removing them, especially in loops or on repeated operations.
+
+```javascript
+// BAD: Adds a new listener every time this function runs
+function setupHandler() {
+  emitter.on('data', handleData); // Accumulates!
+}
+
+// GOOD: Remove before adding, or add once
+function setupHandler() {
+  emitter.removeListener('data', handleData);
+  emitter.on('data', handleData);
+}
+```
+
+## Network and I/O Bottlenecks
+
+### Sequential External Calls
+
+**Signature**: Awaiting multiple independent API calls one after another.
+
+```javascript
+// BAD: 3 sequential calls — total time = sum of all three
+const user = await fetchUser(id);
+const orders = await fetchOrders(id);
+const recommendations = await fetchRecommendations(id);
+
+// GOOD: Parallel — total time = slowest of the three
+const [user, orders, recommendations] = await Promise.all([
+  fetchUser(id),
+  fetchOrders(id),
+  fetchRecommendations(id),
+]);
+```
+
+### Large Payloads
+
+**Signature**: API responses that include data the client doesn't use.
+
+- Return only the fields the client needs (field selection / sparse fieldsets)
+- Compress responses (gzip/brotli)
+- Paginate collections
+- Use appropriate image sizes and formats
+
+### Missing Connection Pooling
+
+**Signature**: Creating a new database connection per request instead of reusing from a pool.
+
+Most ORMs handle this, but verify: is the pool configured? Is the max size appropriate for the workload? Are connections returned to the pool after use?
+
+## Frontend-Specific Bottlenecks
+
+- **Unoptimized images**: Serve WebP/AVIF, lazy-load below-the-fold images, use srcset for responsive sizes
+- **Bundle size**: Tree-shake unused code, code-split by route, analyze with `webpack-bundle-analyzer` or `source-map-explorer`
+- **Render blocking**: Defer non-critical JS/CSS, inline critical CSS, preload key assets
+- **Excessive re-renders**: In React — memoize expensive components, avoid creating objects/functions in render, use proper keys in lists
+- **Layout thrashing**: Reading then writing DOM properties in a loop forces the browser to recalculate layout repeatedly
+
+## Caching Strategies
+
+| Strategy | Use When | Watch Out For |
+|----------|----------|---------------|
+| **HTTP caching** (Cache-Control, ETag) | Static assets, rarely-changing responses | Stale data served to users |
+| **Application cache** (Redis, Memcached) | Expensive queries, computed results | Cache invalidation complexity |
+| **In-memory cache** (LRU) | Hot data, single-instance apps | Memory pressure, stale data |
+| **CDN** | Static assets, public API responses | Purging on update |
+| **Database query cache** | Read-heavy workloads | Invalidated on any write (may not help) |
+
+**Cache invalidation rules:**
+- Write-through: Update cache on every write (consistent but slower writes)
+- Write-behind: Queue cache updates asynchronously (fast writes, eventually consistent)
+- TTL-based: Let entries expire after a time (simplest, acceptable staleness)
+- Event-driven: Invalidate on specific events (most precise, most complex)
+
+Start with TTL-based caching. Only add complexity if staleness is unacceptable.

package/skills/performance-optimization/references/concurrency.md

@@ -0,0 +1,101 @@
+# Concurrency Reference
+
+## Contents
+- Separating concurrency from business logic
+- Limiting shared mutable state
+- Concurrency models
+- Common concurrency bugs
+- Testing concurrent code
+
+## Separating Concurrency from Business Logic
+
+Concurrency is inherently difficult — it changes the behavior of otherwise correct code in subtle ways. Keep concurrent code separate from business logic so that each can be reasoned about independently.
+
+Principles:
+- **Business logic should be pure**: Functions that compute business rules should not manage threads, locks, or async coordination. They take input and return output.
+- **Concurrency is a deployment concern**: The decision to run code in parallel belongs to the orchestration layer, not the domain layer.
+- **Single Responsibility applies**: A class that manages thread safety AND implements business rules has two reasons to change.
+
+In practice:
+- Write business logic as synchronous, pure functions
+- Wrap concurrent execution in an orchestration layer (executor service, task queue, event loop)
+- Use the Humble Object pattern: the concurrent wrapper is humble (hard to test but simple), the business logic is testable
+
+## Limiting Shared Mutable State
+
+Most concurrency bugs stem from shared mutable state — two threads reading and writing the same data without proper coordination.
+
+Strategies to eliminate or reduce shared state (ordered by preference):
+
+1. **Immutable data**: If data cannot change, it can be shared freely without synchronization. Use `const`, `final`, frozen objects, or immutable data structures.
+
+2. **Message passing**: Instead of sharing state, send copies of data between concurrent tasks. Actor models (Erlang, Akka), channels (Go, Rust), and async queues follow this pattern.
+
+3. **Thread-local / task-local storage**: Each concurrent task gets its own copy. No sharing, no coordination needed.
+
+4. **Synchronized access**: When sharing is unavoidable, protect with mutexes, locks, or atomic operations. This is the last resort — it's correct but slow and error-prone.
+
+**Rule of thumb**: If you need more than one lock to protect an operation, redesign the data model so the operation only touches one piece of shared state.
+
+## Concurrency Models
+
+Different concurrency models suit different problems. Choose based on the workload:
+
+**Threads / OS processes**: Best for CPU-bound work that benefits from true parallelism. Heavy resource cost per thread. Risk of races and deadlocks with shared state.
+
+**Async/await (event loop)**: Best for I/O-bound work (network calls, file I/O, database queries). Single-threaded concurrency — no shared state issues, but CPU-bound work blocks the loop.
+
+**Goroutines / green threads**: Lightweight threads managed by the runtime. Good balance of parallelism and low overhead. Still require discipline with shared state (channels preferred).
+
+**Actor model**: Each actor has private state and communicates via messages. Eliminates shared state by design. Good for distributed systems and complex state machines.
+
+**Fork-join / work stealing**: Best for recursive divide-and-conquer problems. The runtime distributes sub-tasks across threads. Common in parallel stream/collection processing.
+
+## Common Concurrency Bugs
+
+### Race conditions
+Two tasks access shared state and the outcome depends on execution order. The code works "most of the time" but fails under load or on different hardware.
+
+Detection: Non-deterministic test failures, bugs that disappear under debugger (which changes timing), inconsistent data in production.
+
+Prevention: Eliminate shared mutable state, use atomic operations, or protect with proper synchronization.
+
+### Deadlocks
+Two tasks each hold a lock the other needs. Both wait forever.
+
+Prevention:
+- Always acquire locks in the same order across the codebase
+- Use timeouts on lock acquisition
+- Prefer lock-free data structures when possible
+- Reduce the number of locks (redesign to reduce shared state)
+
+### Livelocks
+Tasks keep responding to each other without making progress — like two people sidestepping in a hallway.
+
+Prevention: Add randomized backoff to retry logic. Ensure at least one task can make progress.
+
+### Starvation
+A task never gets the resources it needs because other tasks monopolize them.
+
+Prevention: Use fair scheduling, bounded queues, and priority mechanisms. Monitor task latency distributions for signs of starvation.
+
+### Thread pool exhaustion
+All threads in a pool are blocked waiting for I/O or downstream services. New work cannot be accepted.
+
+Prevention: Size pools appropriately, use non-blocking I/O for network calls, add circuit breakers for slow dependencies, separate pools for different workload types.
+
+## Testing Concurrent Code
+
+Concurrency bugs are notoriously hard to reproduce. Standard unit tests often pass because they run too fast to trigger race conditions.
+
+Strategies:
+
+**Stress tests**: Run the same operation from many threads/tasks simultaneously. Repeat thousands of times. Bugs that occur "1 in 1000" will surface.
+
+**Deterministic testing**: Use test frameworks that control thread scheduling (e.g., `ThreadSanitizer`, `loom` for Rust, `Lincheck` for Kotlin). These systematically explore different interleavings.
+
+**Invariant checking**: Instead of asserting specific outcomes, assert invariants that must hold regardless of execution order. "Account balance is never negative" rather than "balance equals 42."
+
+**Timeout-based detection**: If a test hangs instead of failing, a deadlock is likely. Set aggressive timeouts on concurrent tests.
+
+**Race detectors**: Use runtime tools (`-race` flag in Go, ThreadSanitizer for C/C++/Rust, Java's `jcstress`) to detect data races automatically.

package/skills/prd-writing/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: prd-writing
+description: "Write lightweight agile PRDs and technical RFCs that align stakeholders before implementation. Triggers: PRD, product requirements, RFC, request for comments, technical design doc, design document, tech spec, write requirements, what are we building, spec this out. Produces the WHAT and WHY — feature-planning handles HOW."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# PRD & RFC Writing
+
+Write lightweight requirements and design documents that align stakeholders without drowning in waterfall-style documentation. In agile, these documents are living artifacts — concise enough to write quickly, clear enough to prevent misalignment.
+
+## Two Document Types
+
+### Agile PRD (Product Requirements Document)
+**Audience**: Product, design, engineering, stakeholders
+**Purpose**: Define WHAT to build and WHY, from the user's perspective
+**When**: Before starting a significant feature or epic (more than a sprint of work)
+
+### Technical RFC (Request for Comments)
+**Audience**: Engineering team, tech leads, architects
+**Purpose**: Propose HOW to build something technically, gather feedback before committing
+**When**: Before implementing non-trivial technical work (new service, data migration, architecture change)
+
+Many features need both: a PRD from the product side and an RFC from the engineering side. Some only need one.
+
+## Workflow: Agile PRD
+
+### Step 1: Start with the Problem
+
+Every PRD begins with a crystal-clear problem statement:
+
+- What user pain or business need does this address?
+- Who specifically has this problem? (Define the persona)
+- How big is this problem? (Frequency, severity, number of users affected)
+- What do users do today to work around it?
+
+If you can't articulate the problem, you're not ready to write requirements.
+
+### Step 2: Define Goals and Non-Goals
+
+**Goals**: What this project will achieve (tied to metrics when possible)
+**Non-goals**: What this project explicitly will NOT do (prevents scope creep)
+
+Non-goals are just as important as goals. They're the guardrails that keep the project focused.
+
+### Step 3: Write User Stories
+
+Express requirements as user stories:
+
+```
+As a [user persona],
+I want to [action/capability],
+so that [benefit/outcome].
+```
+
+Group stories by priority using MoSCoW:
+- **Must have**: Project fails without these
+- **Should have**: Important but not launch-blocking
+- **Could have**: Nice to have if time allows
+- **Won't have (this time)**: Explicitly deferred
+
+### Step 4: Define Acceptance Criteria and Constraints
+
+For each must-have story, define acceptance criteria (use feature-planning's Given/When/Then format).
+
+Document constraints: performance requirements, accessibility requirements, platform support, backwards compatibility, regulatory compliance.
+
+### Step 5: Include Design Context
+
+If mockups, wireframes, or user flows exist, link them. If not, describe the intended user experience in enough detail that a designer can start.
+
+### Step 6: Produce the PRD
+
+Use the template at [templates/prd.md](templates/prd.md). Keep it under 3 pages. Link to detailed resources rather than embedding everything.
+
+## Workflow: Technical RFC
+
+### Step 1: State the Problem and Context
+
+Same discipline as the PRD — start with why, not what. Include:
+- What triggered this RFC (feature requirement, scaling issue, tech debt)
+- Current state of the system
+- Constraints (timeline, backward compatibility, team expertise)
+
+### Step 2: Propose the Solution
+
+Describe the technical approach clearly. Include:
+- High-level architecture or design
+- Key components and their interactions
+- Data model changes (link to `data-modeling` if needed)
+- API changes (link to `api-design` if needed)
+
+### Step 3: Present Alternatives
+
+List 2-3 alternatives considered with tradeoffs. This proves you've thought beyond the first idea.
+
+### Step 4: Identify Open Questions
+
+List questions that need answering during or after the review process. This invites targeted feedback.
+
+### Step 5: Produce the RFC
+
+Use the template at [templates/rfc.md](templates/rfc.md). Circulate for review with a clear deadline.
+
+## Principles Applied
+
+- **Agile over waterfall**: These documents are living drafts, not contracts. Update as understanding evolves.
+- **KISS**: If it takes more than an afternoon to write, the scope is too large — split it.
+- **Working software over comprehensive documentation**: Write just enough to align. The code is the real spec.

package/skills/prd-writing/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill_name": "prd-writing",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write a PRD for adding multi-language support (i18n) to our React web app. We currently only support English. Our analytics show 30% of users have non-English browser locales. We want to support Spanish, French, and Portuguese initially.",
+      "expected_output": "Should produce a lightweight agile PRD with clear problem statement backed by data, user stories prioritized by MoSCoW, non-goals (e.g., not RTL languages yet), and success metrics.",
+      "assertions": [
+        "Problem statement includes the 30% data point as justification",
+        "Goals are measurable (e.g., support 3 languages, reduce bounce rate for non-English users)",
+        "Non-goals explicitly state what's deferred (RTL, CJK, machine translation)",
+        "User stories cover content translation, language switching, locale detection",
+        "MoSCoW prioritization distinguishes must-have from nice-to-have",
+        "Constraints mention things like URL strategy, SEO, content workflow",
+        "Keeps the PRD concise (not a 10-page waterfall spec)"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Write a technical RFC for migrating our user authentication from session-based to JWT tokens. We have 200K active users and can't afford downtime during migration.",
+      "expected_output": "Should produce an RFC with the zero-downtime constraint front and center, propose a gradual migration strategy, present alternatives, and identify specific risks.",
+      "assertions": [
+        "Zero-downtime requirement shapes the entire proposal (not just a footnote)",
+        "Proposes a gradual migration (dual-auth period, not big bang)",
+        "Presents alternatives (session-based improvements, OAuth provider, etc.)",
+        "Addresses security implications of JWT (token revocation, expiry strategy)",
+        "Includes data migration plan for existing sessions",
+        "Has open questions that invite reviewer input",
+        "Links to feature-planning for implementation task breakdown"
+      ]
+    }
+  ]
+}

package/skills/prd-writing/references/prd-examples.md

@@ -0,0 +1,132 @@
+# PRD and RFC Examples
+
+## What "Lightweight Agile" Means in Practice
+
+A lightweight agile PRD is NOT:
+- A 50-page waterfall requirements spec
+- An exhaustive list of every edge case
+- A contract that cannot change
+
+A lightweight agile PRD IS:
+- 1-3 pages that capture the essential problem, goals, and requirements
+- A shared understanding document — alignment tool, not a spec
+- Something a motivated engineer can write in an afternoon
+- Living: updated as the team learns more
+
+---
+
+## Example: Good Lightweight PRD
+
+**Feature**: Saved Searches
+
+---
+
+**Problem**
+
+Power users of our analytics dashboard run the same searches every day. Currently they must re-enter filter combinations manually each session. Support tickets show 15% of users mention "having to set the same filters every time" as a pain point. Usage logs confirm the top 20% of users average 8 filter changes per session.
+
+**Goals**
+- Users can save up to 20 named search configurations
+- Saved searches load with one click from the search bar
+- Reduces average filter changes per session by 50% for power users (measure at 30 days post-launch)
+
+**Non-goals**
+- Sharing saved searches between users (deferred to v2)
+- Search history / auto-complete (separate feature)
+- Mobile app support (web only for now)
+
+**User Stories**
+
+*Must have:*
+- As a power user, I want to save my current filter state with a name, so that I can return to it without re-entering filters
+- As a power user, I want to load a saved search by clicking its name, so that I can switch between common configurations quickly
+- As a power user, I want to delete saved searches I no longer need
+
+*Should have:*
+- As a power user, I want to rename a saved search, so that I can keep my list organized
+
+**Acceptance Criteria** (for must-haves)
+
+*Save a search:*
+- Given I have applied one or more filters, when I click "Save search", then I see a dialog to name it
+- Given I enter a name and click Save, then the search appears in my saved searches list immediately
+- Given I try to save with a duplicate name, then I'm warned and can choose to overwrite or rename
+
+*Load a search:*
+- Given I have saved searches, when I click a saved search name, then all filters update to that saved configuration in under 200ms
+- Given no saved searches exist, then the saved searches dropdown shows an empty state with "Save your first search" prompt
+
+**Constraints**
+- Max 20 saved searches per user (storage and UI constraint)
+- Saved searches are persisted server-side (not localStorage) so they sync across devices
+- Names limited to 50 characters
+
+**Design context**: Saved searches appear as a dropdown from the existing search bar. Mockup linked in Figma: [link].
+
+---
+
+## What Makes This PRD Good
+
+- **Problem is quantified**: "15% of support tickets", "8 filter changes per session" — not "users find it annoying"
+- **Non-goals are explicit**: prevents scope creep discussions during development
+- **MoSCoW prioritization**: the team knows what to cut if time is short
+- **Acceptance criteria are testable**: Given/When/Then format, specific and binary (pass/fail)
+- **Constraints are technical facts**, not preferences
+- **Under 2 pages** — a motivated engineer can read this in 5 minutes
+
+---
+
+## Example: Good Technical RFC
+
+**RFC: Migrate Session Storage from Redis to PostgreSQL**
+
+---
+
+**Context**
+
+Our Redis cluster is consistently at 80% memory usage and requires a $2,400/month upgrade. Sessions are currently stored as Redis hashes with 24-hour TTL. We have ~50,000 active sessions at peak.
+
+**Proposed Solution**
+
+Store sessions in a `sessions` PostgreSQL table:
+```sql
+CREATE TABLE sessions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id BIGINT NOT NULL REFERENCES users(id),
+  data JSONB NOT NULL DEFAULT '{}',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  expires_at TIMESTAMPTZ NOT NULL,
+  last_accessed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX sessions_user_id_idx ON sessions(user_id);
+CREATE INDEX sessions_expires_at_idx ON sessions(expires_at) WHERE expires_at > NOW();
+```
+
+Expired sessions are cleaned by a nightly job (`DELETE FROM sessions WHERE expires_at < NOW()`). Session reads update `last_accessed_at` asynchronously (fire-and-forget) to avoid read amplification.
+
+**Alternatives Considered**
+
+1. **Upgrade Redis** ($2,400/month, solves capacity but not the operational cost). Simple but doesn't reduce cost.
+2. **Switch to JWT sessions** (stateless, no storage needed). Rejected: cannot revoke JWTs before expiry, which is a security requirement for us.
+3. **PostgreSQL** (proposed): Reduces infrastructure cost to ~$0 marginal (existing PG cluster has headroom), adds session revocation query capability, adds audit trail. Tradeoff: higher read latency (~5ms vs ~1ms) and additional load on primary database.
+
+**Migration Plan**
+1. Add `sessions` table to Postgres (backwards compatible — Redis still in use)
+2. Write to both Redis and Postgres for 2 weeks (dual-write)
+3. Read from Postgres with Redis fallback for 1 week
+4. Remove Redis reads; remove Redis writes
+5. Remove Redis cluster
+
+**Open Questions**
+- Should we keep Redis for other uses (rate limiting, pub/sub)? If yes, downgrade instead of removing.
+- Acceptable session read latency budget? Current Redis ~1ms, Postgres ~5ms. Impact on auth-heavy pages?
+
+---
+
+## What Makes This RFC Good
+
+- **Quantified trigger**: "$2,400/month", "80% memory" — not "Redis is getting full"
+- **Alternatives include "do nothing" equivalent**: upgrade Redis is explicitly evaluated
+- **Tradeoffs are honest**: "higher read latency (~5ms vs ~1ms)" — doesn't hide downsides
+- **Migration plan is phased**: dual-write period reduces risk
+- **Open questions are targeted**: asks the two things that could change the decision