@patricio0312rev/skillset 0.1.0

package/templates/architecture/reliability-strategy-builder/ SKILL.md

@@ -0,0 +1,286 @@
+---
+name: reliability-strategy-builder
+description: Implements reliability patterns including circuit breakers, retries, fallbacks, bulkheads, and SLO definitions. Provides failure mode analysis and incident response plans. Use for "SRE", "reliability", "resilience", or "failure handling".
+---
+
+# Reliability Strategy Builder
+
+Build resilient systems with proper failure handling and SLOs.
+
+## Reliability Patterns
+
+### 1. Circuit Breaker
+
+Prevent cascading failures by stopping requests to failing services.
+
+```typescript
+class CircuitBreaker {
+  private state: "closed" | "open" | "half-open" = "closed";
+  private failureCount = 0;
+  private lastFailureTime?: Date;
+
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.state === "open") {
+      if (this.shouldAttemptReset()) {
+        this.state = "half-open";
+      } else {
+        throw new Error("Circuit breaker is OPEN");
+      }
+    }
+
+    try {
+      const result = await operation();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+
+  private onSuccess() {
+    this.failureCount = 0;
+    this.state = "closed";
+  }
+
+  private onFailure() {
+    this.failureCount++;
+    this.lastFailureTime = new Date();
+
+    if (this.failureCount >= 5) {
+      this.state = "open";
+    }
+  }
+
+  private shouldAttemptReset(): boolean {
+    if (!this.lastFailureTime) return false;
+    const now = Date.now();
+    const elapsed = now - this.lastFailureTime.getTime();
+    return elapsed > 60000; // 1 minute
+  }
+}
+```
+
+### 2. Retry with Backoff
+
+Handle transient failures with exponential backoff.
+
+```typescript
+async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3,
+  baseDelay = 1000
+): Promise<T> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (attempt === maxRetries) throw error;
+
+      // Exponential backoff: 1s, 2s, 4s
+      const delay = baseDelay * Math.pow(2, attempt);
+      await sleep(delay);
+    }
+  }
+  throw new Error("Max retries exceeded");
+}
+```
+
+### 3. Fallback Pattern
+
+Provide degraded functionality when primary fails.
+
+```typescript
+async function getUserWithFallback(userId: string): Promise<User> {
+  try {
+    // Try primary database
+    return await primaryDb.users.findById(userId);
+  } catch (error) {
+    logger.warn("Primary DB failed, using cache");
+
+    // Fallback to cache
+    const cached = await cache.get(`user:${userId}`);
+    if (cached) return cached;
+
+    // Final fallback: return minimal user object
+    return {
+      id: userId,
+      name: "Unknown User",
+      email: "unavailable",
+    };
+  }
+}
+```
+
+### 4. Bulkhead Pattern
+
+Isolate failures to prevent resource exhaustion.
+
+```typescript
+class ThreadPool {
+  private pools = new Map<string, Semaphore>();
+
+  constructor() {
+    // Separate pools for different operations
+    this.pools.set("critical", new Semaphore(100));
+    this.pools.set("standard", new Semaphore(50));
+    this.pools.set("background", new Semaphore(10));
+  }
+
+  async execute(priority: string, operation: () => Promise<any>) {
+    const pool = this.pools.get(priority);
+    await pool.acquire();
+
+    try {
+      return await operation();
+    } finally {
+      pool.release();
+    }
+  }
+}
+```
+
+## SLO Definitions
+
+### SLO Template
+
+```yaml
+service: user-api
+slos:
+  - name: Availability
+    description: API should be available for successful requests
+    target: 99.9%
+    measurement:
+      type: ratio
+      success: status_code < 500
+      total: all_requests
+    window: 30 days
+
+  - name: Latency
+    description: 95% of requests complete within 500ms
+    target: 95%
+    measurement:
+      type: percentile
+      metric: request_duration_ms
+      threshold: 500
+      percentile: 95
+    window: 7 days
+
+  - name: Error Rate
+    description: Less than 1% of requests result in errors
+    target: 99%
+    measurement:
+      type: ratio
+      success: status_code < 400 OR status_code IN [401, 403, 404]
+      total: all_requests
+    window: 24 hours
+```
+
+### Error Budget
+
+```
+Error Budget = 100% - SLO
+
+Example:
+SLO: 99.9% availability
+Error Budget: 0.1% = 43.2 minutes/month downtime allowed
+```
+
+## Failure Mode Analysis
+
+```markdown
+| Component   | Failure Mode | Impact | Probability | Detection               | Mitigation                     |
+| ----------- | ------------ | ------ | ----------- | ----------------------- | ------------------------------ |
+| Database    | Unresponsive | HIGH   | Medium      | Health checks every 10s | Circuit breaker, read replicas |
+| API Gateway | Overload     | HIGH   | Low         | Request queue depth     | Rate limiting, auto-scaling    |
+| Cache       | Eviction     | MEDIUM | High        | Cache hit rate          | Fallback to DB, larger cache   |
+| Queue       | Backed up    | LOW    | Medium      | Queue depth metric      | Add workers, DLQ               |
+```
+
+## Reliability Checklist
+
+### Infrastructure
+
+- [ ] Load balancer with health checks
+- [ ] Multiple availability zones
+- [ ] Auto-scaling configured
+- [ ] Database replication
+- [ ] Regular backups (tested!)
+
+### Application
+
+- [ ] Circuit breakers on external calls
+- [ ] Retry logic with backoff
+- [ ] Timeouts on all I/O
+- [ ] Fallback mechanisms
+- [ ] Graceful degradation
+
+### Monitoring
+
+- [ ] SLO dashboard
+- [ ] Error budgets tracked
+- [ ] Alerting on SLO violations
+- [ ] Latency percentiles (p50, p95, p99)
+- [ ] Dependency health checks
+
+### Operations
+
+- [ ] Incident response runbook
+- [ ] On-call rotation
+- [ ] Postmortem template
+- [ ] Disaster recovery plan
+- [ ] Chaos engineering tests
+
+## Incident Response Plan
+
+### Severity Levels
+
+```
+SEV1 (Critical): Complete service outage, data loss
+  - Response time: <15 minutes
+  - Page on-call immediately
+
+SEV2 (High): Partial outage, degraded performance
+  - Response time: <1 hour
+  - Alert on-call
+
+SEV3 (Medium): Minor issues, workarounds available
+  - Response time: <4 hours
+  - Create ticket
+
+SEV4 (Low): Cosmetic issues, no user impact
+  - Response time: Next business day
+  - Backlog
+```
+
+### Incident Response Steps
+
+1. **Acknowledge**: Confirm receipt within SLA
+2. **Assess**: Determine severity and impact
+3. **Communicate**: Update status page
+4. **Mitigate**: Stop the bleeding (rollback, scale, disable)
+5. **Resolve**: Fix root cause
+6. **Document**: Write postmortem
+
+## Best Practices
+
+1. **Design for failure**: Assume components will fail
+2. **Fail fast**: Don't let slow failures cascade
+3. **Isolate failures**: Bulkhead pattern
+4. **Graceful degradation**: Reduce functionality, don't crash
+5. **Monitor SLOs**: Track error budgets
+6. **Test failure modes**: Chaos engineering
+7. **Document runbooks**: Clear incident response
+
+## Output Checklist
+
+- [ ] Circuit breakers implemented
+- [ ] Retry logic with backoff
+- [ ] Fallback mechanisms
+- [ ] Bulkhead isolation
+- [ ] SLOs defined (availability, latency, errors)
+- [ ] Error budgets calculated
+- [ ] Failure mode analysis
+- [ ] Monitoring dashboard
+- [ ] Incident response plan
+- [ ] Runbooks documented

package/templates/architecture/rfc-generator/ SKILL.md

@@ -0,0 +1,362 @@
+---
+name: rfc-generator
+description: Generates Request for Comments documents for technical proposals including problem statement, solution design, alternatives, risks, and rollout plans. Use for "RFC", "technical proposals", "design docs", or "architecture proposals".
+---
+
+# RFC Generator
+
+Create comprehensive technical proposals with RFCs.
+
+## RFC Template
+
+```markdown
+# RFC-042: Implement Read Replicas for Analytics
+
+**Status:** Draft | In Review | Accepted | Rejected | Implemented
+**Author:** Alice (alice@example.com)
+**Reviewers:** Bob, Charlie, David
+**Created:** 2024-01-15
+**Updated:** 2024-01-20
+**Target Date:** Q1 2024
+
+## Summary
+
+Add PostgreSQL read replicas to separate analytical queries from transactional workload, improving database performance and enabling new analytics features.
+
+## Problem Statement
+
+### Current Situation
+
+Our PostgreSQL database serves both transactional (OLTP) and analytical (OLAP) workloads:
+
+- 1000 writes/min (checkout, orders, inventory)
+- 5000 reads/min (user browsing, search)
+- 500 analytics queries/min (dashboards, reports)
+
+### Issues
+
+1. **Performance degradation**: Analytics queries slow down transactions
+2. **Resource contention**: Complex reports consume CPU/memory
+3. **Blocking features**: Can't add more dashboards without impacting users
+4. **Peak hour problems**: Analytics scheduled during business hours
+
+### Impact
+
+- Checkout p95 latency: 800ms (target: <300ms)
+- Database CPU: 75% average, 95% peak
+- Customer complaints about slow pages
+- Product team blocked on analytics features
+
+### Success Criteria
+
+- Checkout latency <300ms p95
+- Database CPU <50%
+- Support 2x more analytics queries
+- Zero impact on transactional performance
+
+## Proposed Solution
+
+### High-Level Design
+```
+
+┌─────────────┐
+│ Primary │────────────────┐
+│ (Write) │ │
+└─────────────┘ │
+▼
+┌─────────────┐
+│ Replica 1 │
+│ (Read) │
+└─────────────┘
+▼
+┌─────────────┐
+│ Replica 2 │
+│ (Analytics)│
+└─────────────┘
+
+````
+
+### Architecture
+1. **Primary database**: Handles all writes and critical reads
+2. **Read Replica 1**: Serves user-facing read queries
+3. **Read Replica 2**: Dedicated to analytics/reporting
+
+### Routing Strategy
+```typescript
+const db = {
+  primary: primaryConnection,
+  read: replicaConnection,
+  analytics: analyticsConnection,
+};
+
+// Write
+await db.primary.users.create(data);
+
+// Critical read (always fresh)
+await db.primary.users.findById(id);
+
+// Non-critical read (can be slightly stale)
+await db.read.products.search(query);
+
+// Analytics
+await db.analytics.orders.aggregate(pipeline);
+````
+
+### Replication
+
+- **Type:** Streaming replication
+- **Lag:** <1 second for read replica, <5 seconds acceptable for analytics
+- **Monitoring:** Alert if lag >5 seconds
+
+## Detailed Design
+
+### Database Configuration
+
+```yaml
+# Primary
+max_connections: 200
+shared_buffers: 4GB
+work_mem: 16MB
+
+# Read Replica
+max_connections: 100
+shared_buffers: 8GB
+work_mem: 32MB
+
+# Analytics Replica
+max_connections: 50
+shared_buffers: 16GB
+work_mem: 64MB
+```
+
+### Connection Pooling
+
+```typescript
+const pools = {
+  primary: new Pool({ max: 20, min: 5 }),
+  read: new Pool({ max: 50, min: 10 }),
+  analytics: new Pool({ max: 10, min: 2 }),
+};
+```
+
+### Query Classification
+
+```typescript
+enum QueryType {
+  WRITE = "primary",
+  CRITICAL_READ = "primary",
+  READ = "read",
+  ANALYTICS = "analytics",
+}
+
+function route(queryType: QueryType) {
+  return pools[queryType];
+}
+```
+
+## Alternatives Considered
+
+### Alternative 1: Vertical Scaling
+
+**Approach:** Upgrade to larger database instance
+
+- **Pros:** Simple, no code changes
+- **Cons:** Expensive ($500 → $2000/month), doesn't separate workloads, still hits limits
+- **Verdict:** Rejected - doesn't solve isolation problem
+
+### Alternative 2: Separate Analytics Database
+
+**Approach:** Copy data to dedicated analytics DB (e.g., ClickHouse)
+
+- **Pros:** Optimal for analytics, no impact on primary
+- **Cons:** Complex ETL pipeline, eventual consistency, high maintenance
+- **Verdict:** Defer - consider for future if replicas insufficient
+
+### Alternative 3: Materialized Views
+
+**Approach:** Pre-compute analytics results
+
+- **Pros:** Fast queries, no replicas needed
+- **Cons:** Limited to known queries, maintenance overhead
+- **Verdict:** Complement to replicas, not replacement
+
+## Tradeoffs
+
+### What We're Optimizing For
+
+- Performance isolation
+- Cost efficiency
+- Quick implementation
+- Operational simplicity
+
+### What We're Sacrificing
+
+- Slight data staleness (acceptable for analytics)
+- Additional infrastructure complexity
+- Higher operational costs
+
+## Risks & Mitigations
+
+### Risk 1: Replication Lag
+
+**Impact:** Analytics sees stale data
+**Probability:** Medium
+**Mitigation:**
+
+- Monitor lag continuously
+- Alert if >5 seconds
+- Document expected lag for users
+
+### Risk 2: Configuration Complexity
+
+**Impact:** Routing errors, performance issues
+**Probability:** Low
+**Mitigation:**
+
+- Comprehensive testing
+- Gradual rollout
+- Easy rollback mechanism
+
+### Risk 3: Cost Overrun
+
+**Impact:** Budget exceeded
+**Probability:** Low
+**Mitigation:**
+
+- Use smaller instance for analytics ($300/month)
+- Monitor usage
+- Right-size after 1 month
+
+## Rollout Plan
+
+### Phase 1: Setup (Week 1-2)
+
+- [ ] Provision read replica 1
+- [ ] Provision analytics replica 2
+- [ ] Configure replication
+- [ ] Verify lag <1 second
+- [ ] Load testing
+
+### Phase 2: Read Replica (Week 3)
+
+- [ ] Deploy routing logic
+- [ ] Route 10% search queries to replica
+- [ ] Monitor errors and latency
+- [ ] Ramp to 100%
+
+### Phase 3: Analytics Migration (Week 4-5)
+
+- [ ] Identify analytics queries
+- [ ] Update dashboard queries to analytics replica
+- [ ] Test reports
+- [ ] Migrate all analytics
+
+### Phase 4: Validation (Week 6)
+
+- [ ] Measure checkout latency improvement
+- [ ] Verify CPU reduction
+- [ ] User acceptance testing
+- [ ] Mark as complete
+
+## Success Metrics
+
+### Primary Goals
+
+- ✅ Checkout latency <300ms p95 (currently 800ms)
+- ✅ Primary DB CPU <50% (currently 75%)
+- ✅ Zero errors from replication lag
+
+### Secondary Goals
+
+- Support 2x analytics queries
+- Enable new dashboard features
+- Team satisfaction survey >8/10
+
+## Cost Analysis
+
+| Component         | Current     | Proposed      | Delta        |
+| ----------------- | ----------- | ------------- | ------------ |
+| Primary DB        | $500/mo     | $500/mo       | $0           |
+| Read Replica      | -           | $500/mo       | +$500        |
+| Analytics Replica | -           | $300/mo       | +$300        |
+| **Total**         | **$500/mo** | **$1,300/mo** | **+$800/mo** |
+
+**ROI:** Better performance enables revenue growth; analytics unlocks product insights
+
+## Open Questions
+
+1. What's acceptable replication lag for analytics? (Proposed: <5 sec)
+2. How do we handle replica failure? (Proposed: Fallback to primary)
+3. Should we add more replicas later? (Proposed: Monitor and decide in Q2)
+
+## Timeline
+
+- Week 1-2: Provisioning and setup
+- Week 3: Read replica migration
+- Week 4-5: Analytics migration
+- Week 6: Validation
+- **Total: 6 weeks**
+
+## Appendix
+
+### References
+
+- [PostgreSQL Replication Docs](https://postgresql.org/docs/replication)
+- [Cost Analysis Spreadsheet](https://docs.google.com/)
+- [Load Test Results](https://example.com)
+
+### Review History
+
+- 2024-01-15: Initial draft (Alice)
+- 2024-01-17: Added cost analysis (Bob)
+- 2024-01-20: Addressed review comments
+
+```
+
+## RFC Process
+
+### 1. Draft (1 week)
+- Author writes RFC
+- Include problem, solution, alternatives
+- Share with team for early feedback
+
+### 2. Review (1-2 weeks)
+- Distribute to reviewers
+- Collect comments
+- Address feedback
+- Iterate on design
+
+### 3. Approval (1 week)
+- Present to architecture review
+- Resolve remaining concerns
+- Vote: Accept/Reject
+- Update status
+
+### 4. Implementation
+- Track progress
+- Update RFC with learnings
+- Mark as implemented
+
+## Best Practices
+
+1. **Clear problem**: Start with why
+2. **Concrete solution**: Be specific
+3. **Consider alternatives**: Show you explored options
+4. **Honest tradeoffs**: Every choice has costs
+5. **Measurable success**: Define done
+6. **Risk mitigation**: Plan for failure
+7. **Iterative**: Update based on feedback
+
+## Output Checklist
+
+- [ ] Problem statement
+- [ ] Proposed solution with architecture
+- [ ] 2+ alternatives considered
+- [ ] Tradeoffs documented
+- [ ] Risks with mitigations
+- [ ] Rollout plan with phases
+- [ ] Success metrics defined
+- [ ] Cost analysis
+- [ ] Timeline estimated
+- [ ] Reviewers assigned
+```