@patricio0312rev/skillset 0.1.0

package/templates/performance/load-test-scenario-builder/ SKILL.md

@@ -0,0 +1,256 @@
+---
+name: load-test-scenario-builder
+description: Creates comprehensive load test plans with realistic scenarios, traffic models, k6 scripts, and success criteria. Use for "load testing", "performance testing", "capacity validation", or "stress testing".
+---
+
+# Load Test Scenario Builder
+
+Validate system capacity with realistic load tests.
+
+## Load Test Scenarios
+
+```typescript
+interface LoadTestScenario {
+  name: string;
+  description: string;
+  virtualUsers: number;
+  duration: string;
+  rampUp: string;
+  successCriteria: {
+    p95Latency: number;
+    errorRate: number;
+    throughput: number;
+  };
+}
+
+const scenarios: LoadTestScenario[] = [
+  {
+    name: "Baseline Load",
+    description: "Normal traffic pattern",
+    virtualUsers: 100,
+    duration: "10m",
+    rampUp: "2m",
+    successCriteria: {
+      p95Latency: 500, // ms
+      errorRate: 0.01, // 1%
+      throughput: 1000, // req/s
+    },
+  },
+  {
+    name: "Peak Load",
+    description: "Black Friday traffic",
+    virtualUsers: 1000,
+    duration: "30m",
+    rampUp: "5m",
+    successCriteria: {
+      p95Latency: 2000,
+      errorRate: 0.05,
+      throughput: 5000,
+    },
+  },
+  {
+    name: "Stress Test",
+    description: "Find breaking point",
+    virtualUsers: 5000,
+    duration: "20m",
+    rampUp: "10m",
+    successCriteria: {
+      p95Latency: 5000,
+      errorRate: 0.1,
+      throughput: 10000,
+    },
+  },
+];
+```
+
+## K6 Load Test Script
+
+```javascript
+// load-tests/checkout-flow.js
+import http from "k6/http";
+import { check, sleep } from "k6";
+import { Rate } from "k6/metrics";
+
+const errorRate = new Rate("errors");
+
+export let options = {
+  stages: [
+    { duration: "2m", target: 100 }, // Ramp up
+    { duration: "10m", target: 100 }, // Stay at 100
+    { duration: "2m", target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    http_req_duration: ["p(95)<500"], // 95% under 500ms
+    errors: ["rate<0.01"], // Error rate <1%
+  },
+};
+
+export default function () {
+  // 1. Browse products
+  let browseRes = http.get("https://api.example.com/products");
+  check(browseRes, {
+    "browse status 200": (r) => r.status === 200,
+  }) || errorRate.add(1);
+  sleep(1);
+
+  // 2. Add to cart
+  let addCartRes = http.post(
+    "https://api.example.com/cart",
+    JSON.stringify({
+      productId: "123",
+      quantity: 1,
+    }),
+    {
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+  check(addCartRes, {
+    "add cart status 201": (r) => r.status === 201,
+  }) || errorRate.add(1);
+  sleep(2);
+
+  // 3. Checkout
+  let checkoutRes = http.post(
+    "https://api.example.com/checkout",
+    JSON.stringify({
+      paymentMethod: "card",
+    }),
+    {
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+  check(checkoutRes, {
+    "checkout status 200": (r) => r.status === 200,
+    "checkout success": (r) => r.json("status") === "success",
+  }) || errorRate.add(1);
+  sleep(3);
+}
+```
+
+## Traffic Models
+
+```javascript
+// Realistic traffic patterns
+export const trafficModels = {
+  // Steady state
+  steadyState: {
+    stages: [{ duration: "30m", target: 500 }],
+  },
+
+  // Gradual ramp
+  gradualRamp: {
+    stages: [
+      { duration: "5m", target: 100 },
+      { duration: "5m", target: 300 },
+      { duration: "5m", target: 500 },
+      { duration: "10m", target: 500 },
+      { duration: "5m", target: 0 },
+    ],
+  },
+
+  // Spike test
+  spikeTest: {
+    stages: [
+      { duration: "2m", target: 100 },
+      { duration: "1m", target: 2000 }, // Sudden spike
+      { duration: "2m", target: 100 },
+    ],
+  },
+
+  // Soak test (endurance)
+  soakTest: {
+    stages: [
+      { duration: "5m", target: 500 },
+      { duration: "4h", target: 500 }, // Long duration
+      { duration: "5m", target: 0 },
+    ],
+  },
+};
+```
+
+## Success Thresholds
+
+```javascript
+export const thresholds = {
+  // Latency
+  http_req_duration: [
+    "p(50)<200", // 50% under 200ms
+    "p(95)<500", // 95% under 500ms
+    "p(99)<1000", // 99% under 1s
+  ],
+
+  // Error rate
+  http_req_failed: ["rate<0.01"], // <1% errors
+
+  // Throughput
+  http_reqs: ["rate>1000"], // >1000 req/s
+
+  // Custom metrics
+  checkout_duration: ["p(95)<2000"],
+  checkout_success_rate: ["rate>0.95"],
+};
+```
+
+## Running Load Tests
+
+```bash
+#!/bin/bash
+# scripts/run-load-tests.sh
+
+echo "Running load tests..."
+
+# Baseline test
+k6 run --vus 100 --duration 10m load-tests/checkout-flow.js
+
+# Peak load test
+k6 run --vus 1000 --duration 30m load-tests/checkout-flow.js
+
+# Stress test (find breaking point)
+k6 run --vus 5000 --duration 20m load-tests/stress-test.js
+
+# Generate report
+k6 run --out json=results.json load-tests/checkout-flow.js
+k6 run --out influxdb=http://localhost:8086 load-tests/checkout-flow.js
+```
+
+## Result Analysis
+
+```typescript
+interface LoadTestResult {
+  scenario: string;
+  timestamp: Date;
+  metrics: {
+    p50Latency: number;
+    p95Latency: number;
+    p99Latency: number;
+    errorRate: number;
+    throughput: number;
+    maxVUs: number;
+  };
+  passed: boolean;
+  notes: string[];
+}
+
+function analyzeResults(results: LoadTestResult) {
+  console.log(\`Load Test: \${results.scenario}\`);
+  console.log(\`Status: \${results.passed ? '✅ PASS' : '❌ FAIL'}\`);
+  console.log(\`p95 Latency: \${results.metrics.p95Latency}ms\`);
+  console.log(\`Error Rate: \${(results.metrics.errorRate * 100).toFixed(2)}%\`);
+  console.log(\`Throughput: \${results.metrics.throughput} req/s\`);
+
+  if (!results.passed) {
+    console.log('Failed criteria:');
+    results.notes.forEach(note => console.log(\`  - \${note}\`));
+  }
+}
+```
+
+## Output Checklist
+
+- [ ] Scenarios defined
+- [ ] k6 scripts created
+- [ ] Traffic models configured
+- [ ] Success criteria set
+- [ ] CI integration
+- [ ] Results analysis
+      ENDFILE

package/templates/performance/observability-setup/ SKILL.md

@@ -0,0 +1,232 @@
+---
+name: observability-setup
+description: Implements comprehensive observability with OpenTelemetry tracing, Prometheus metrics, and structured logging. Includes instrumentation plans, sample dashboards, and alert candidates. Use for "observability", "monitoring", "tracing", or "metrics".
+---
+
+# Observability Setup
+
+Implement the three pillars: Traces, Metrics, and Logs.
+
+## OpenTelemetry Tracing
+
+```typescript
+// tracing.ts
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { Resource } from "@opentelemetry/resources";
+import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+import { PrismaInstrumentation } from "@prisma/instrumentation";
+
+const provider = new NodeTracerProvider({
+  resource: new Resource({
+    [SemanticResourceAttributes.SERVICE_NAME]: "my-api",
+    [SemanticResourceAttributes.SERVICE_VERSION]: "1.0.0",
+  }),
+});
+
+registerInstrumentations({
+  instrumentations: [
+    new HttpInstrumentation(),
+    new ExpressInstrumentation(),
+    new PrismaInstrumentation(),
+  ],
+});
+
+provider.register();
+
+// Custom spans
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-app");
+
+async function processOrder(orderId: string) {
+  const span = tracer.startSpan("processOrder");
+  span.setAttribute("order.id", orderId);
+
+  try {
+    await validateOrder(orderId);
+    await chargePayment(orderId);
+    await fulfillOrder(orderId);
+    span.setStatus({ code: 0 }); // OK
+  } catch (error) {
+    span.setStatus({ code: 2, message: error.message }); // ERROR
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+```
+
+## Prometheus Metrics
+
+```typescript
+// metrics.ts
+import { Registry, Counter, Histogram, Gauge } from "prom-client";
+
+const register = new Registry();
+
+// HTTP request counter
+export const httpRequestCounter = new Counter({
+  name: "http_requests_total",
+  help: "Total HTTP requests",
+  labelNames: ["method", "route", "status_code"],
+  registers: [register],
+});
+
+// HTTP request duration
+export const httpRequestDuration = new Histogram({
+  name: "http_request_duration_seconds",
+  help: "HTTP request duration in seconds",
+  labelNames: ["method", "route", "status_code"],
+  buckets: [0.1, 0.5, 1, 2, 5, 10],
+  registers: [register],
+});
+
+// Active connections
+export const activeConnections = new Gauge({
+  name: "active_connections",
+  help: "Number of active connections",
+  registers: [register],
+});
+
+// Business metrics
+export const ordersProcessed = new Counter({
+  name: "orders_processed_total",
+  help: "Total orders processed",
+  labelNames: ["status"],
+  registers: [register],
+});
+
+// Middleware
+app.use((req, res, next) => {
+  const start = Date.now();
+
+  res.on("finish", () => {
+    const duration = (Date.now() - start) / 1000;
+    const route = req.route?.path || "unknown";
+
+    httpRequestCounter.inc({
+      method: req.method,
+      route,
+      status_code: res.statusCode,
+    });
+
+    httpRequestDuration.observe(
+      { method: req.method, route, status_code: res.statusCode },
+      duration
+    );
+  });
+
+  next();
+});
+
+// Metrics endpoint
+app.get("/metrics", async (req, res) => {
+  res.set("Content-Type", register.contentType);
+  res.end(await register.metrics());
+});
+```
+
+## Structured Logging
+
+```typescript
+// logger.ts
+import pino from "pino";
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || "info",
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+  base: {
+    service: "my-api",
+    environment: process.env.NODE_ENV,
+  },
+});
+
+// Usage
+logger.info({ userId: "123", action: "login" }, "User logged in");
+logger.error({ err: error, orderId: "456" }, "Order processing failed");
+```
+
+## Sample Dashboard (Grafana)
+
+```json
+{
+  "dashboard": {
+    "title": "API Overview",
+    "panels": [
+      {
+        "title": "Request Rate",
+        "targets": [{
+          "expr": "rate(http_requests_total[5m])"
+        }]
+      },
+      {
+        "title": "Error Rate",
+        "targets": [{
+          "expr": "rate(http_requests_total{status_code=~"5.."}[5m])"
+        }]
+      },
+      {
+        "title": "p95 Latency",
+        "targets": [{
+          "expr": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))"
+        }]
+      },
+      {
+        "title": "Active Connections",
+        "targets": [{
+          "expr": "active_connections"
+        }]
+      }
+    ]
+  }
+}
+```
+
+## Alert Candidates
+
+```yaml
+# alerts.yml
+groups:
+  - name: api_alerts
+    interval: 30s
+    rules:
+      - alert: HighErrorRate
+        expr: rate(http_requests_total{status_code=~"5.."}[5m]) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "High error rate detected"
+
+      - alert: HighLatency
+        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "p95 latency above 2s"
+
+      - alert: LowAvailability
+        expr: rate(http_requests_total{status_code="200"}[5m]) / rate(http_requests_total[5m]) < 0.95
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Availability below 95%"
+```
+
+## Output Checklist
+
+- [ ] OpenTelemetry tracing configured
+- [ ] Prometheus metrics instrumented
+- [ ] Structured logging implemented
+- [ ] Sample dashboards created
+- [ ] Alert rules defined
+- [ ] Metrics endpoint exposed
+- [ ] Instrumentation tested
+      ENDFILE

package/templates/performance/postmortem-writer/ SKILL.md

@@ -0,0 +1,203 @@
+---
+name: postmortem-writer
+description: Creates comprehensive post-incident documents with timeline, root cause analysis, contributing factors, action items, and ownership. Follows SRE best practices for blameless postmortems. Use for "postmortem", "incident review", "RCA", or "post-incident".
+---
+
+# Postmortem Writer
+
+Document incidents for learning and improvement.
+
+## Postmortem Template
+
+```markdown
+# Postmortem: API Outage - Database Connection Pool Exhausted
+
+**Date:** 2024-01-15
+**Authors:** Jane Doe (On-call), John Smith (DBA)
+**Status:** Complete
+**Severity:** P1 (Critical)
+
+## Summary
+
+On January 15, 2024, our API experienced a complete outage for 25 minutes (14:32 - 14:57 UTC) affecting 100% of users. The root cause was database connection pool exhaustion triggered by a connection leak introduced in deployment v2.3.4.
+
+**Impact:**
+
+- Duration: 25 minutes
+- Users affected: ~50,000
+- Requests failed: ~125,000
+- Revenue impact: ~$15,000
+
+## Timeline (All times UTC)
+
+| Time  | Event                                            |
+| ----- | ------------------------------------------------ |
+| 14:15 | v2.3.4 deployed to production                    |
+| 14:32 | First CloudWatch alarm: HighErrorRate            |
+| 14:33 | PagerDuty alert sent to on-call (Jane)           |
+| 14:35 | Jane acknowledges, begins investigation          |
+| 14:38 | Identified: Database connection pool at 100%     |
+| 14:40 | Attempted: Kill long-running queries (no effect) |
+| 14:43 | Decision: Rollback to v2.3.3                     |
+| 14:45 | Rollback initiated                               |
+| 14:47 | Rollback complete, connections dropping          |
+| 14:50 | Error rate returning to normal                   |
+| 14:57 | All systems recovered, incident closed           |
+| 15:30 | Postmortem meeting scheduled                     |
+
+## Root Cause
+
+A code change in v2.3.4 introduced a connection leak in the user profile endpoint. The new caching layer was not properly releasing database connections after queries completed.
+
+**Code diff:**
+\`\`\`diff
+
+- await prisma.user.findUnique({ where: { id } });
+
+* const client = await pool.connect();
+* const user = await client.query('SELECT \* FROM users WHERE id = $1', [id]);
+* // Missing: client.release() ❌
+  \`\`\`
+
+## Contributing Factors
+
+1. **Insufficient testing:** Load tests didn't catch the leak
+
+   - Tests only ran for 5 minutes
+   - Not enough concurrent connections to exhaust pool
+
+2. **Missing monitoring:** No alerts on connection pool metrics
+
+   - Had alarms for query latency
+   - No alarms for active connections count
+
+3. **Inadequate code review:** Reviewer didn't spot missing release()
+
+   - PR approved without running locally
+   - No checklist for connection management
+
+4. **Deployment process:** No gradual rollout
+   - Deployed to 100% of production immediately
+   - No canary deployment
+
+## What Went Well
+
+1. ✅ **Fast detection:** Alert fired within 3 minutes
+2. ✅ **Clear runbook:** DBA runbook had exact steps to follow
+3. ✅ **Quick decision:** Made rollback decision in 8 minutes
+4. ✅ **Communication:** Status page updated every 5 minutes
+5. ✅ **Rollback capability:** Automated rollback took <2 minutes
+
+## What Went Wrong
+
+1. ❌ **Code review missed bug:** Connection leak not caught
+2. ❌ **Testing gaps:** Load tests insufficient duration
+3. ❌ **No canary:** Deployed to all instances at once
+4. ❌ **Late detection:** 17 minutes between deploy and alert
+
+## Action Items
+
+| Action                                        | Owner   | Due Date   | Priority | Status         |
+| --------------------------------------------- | ------- | ---------- | -------- | -------------- |
+| Add connection pool metrics to dashboards     | Jane    | 2024-01-20 | P0       | ✅ Done        |
+| Create PR checklist for connection management | John    | 2024-01-22 | P0       | ✅ Done        |
+| Extend load tests to 30 minutes minimum       | QA Team | 2024-01-25 | P1       | 🔄 In Progress |
+| Implement canary deployment (10% → 100%)      | DevOps  | 2024-02-01 | P1       | 📋 Planned     |
+| Add connection leak detection to tests        | Jane    | 2024-01-27 | P1       | 🔄 In Progress |
+| Review all DB connection usage patterns       | John    | 2024-02-05 | P2       | 📋 Planned     |
+| Improve alert routing (faster escalation)     | DevOps  | 2024-02-10 | P2       | 📋 Planned     |
+
+## Lessons Learned
+
+1. **Code review checklists work:** Need specific items for common issues
+2. **Load tests need realistic duration:** 5min insufficient for leaks
+3. **Gradual rollouts catch issues:** 10% canary would have limited impact
+4. **Monitoring gaps are dangerous:** Add metrics before you need them
+5. **Runbooks save time:** Clear procedures enabled fast response
+
+## Related Incidents
+
+- [2023-11-20] Database CPU spike (similar connection pool issue)
+- [2023-08-15] Memory leak in cache layer
+
+## Prevention
+
+To prevent similar incidents:
+
+1. ✅ Add connection management to code review checklist
+2. ✅ Monitor connection pool utilization
+3. ✅ Extend load test duration
+4. ✅ Implement canary deployments
+5. ✅ Add automated connection leak detection
+
+## Appendix
+
+### Monitoring Graphs
+
+[Insert graphs of connection pool, error rates, latency during incident]
+
+### Communication Log
+
+[Insert status page updates and customer communication]
+
+### Code Fix
+
+PR #1235: Fix connection leak in user profile endpoint
+\`\`\`typescript
+const client = await pool.connect();
+try {
+const user = await client.query('SELECT \* FROM users WHERE id = $1', [id]);
+return user;
+} finally {
+client.release(); // ✅ Always release
+}
+\`\`\`
+```
+
+## Postmortem Best Practices
+
+```markdown
+# Blameless Postmortem Guidelines
+
+## Do ✅
+
+- Focus on systems and processes, not people
+- Use timeline with exact timestamps
+- Identify contributing factors, not just root cause
+- Create actionable items with owners and dates
+- Document what went well (positive reinforcement)
+- Share widely for organizational learning
+
+## Don't ❌
+
+- Blame individuals or teams
+- Hide or minimize the incident
+- Skip the postmortem (even for small incidents)
+- Create action items without owners
+- Forget to follow up on action items
+- Make it a blame session
+
+## Template Sections
+
+1. **Summary** (2-3 sentences)
+2. **Impact** (numbers: users, revenue, duration)
+3. **Timeline** (chronological events)
+4. **Root Cause** (technical explanation)
+5. **Contributing Factors** (broader context)
+6. **What Went Well** (positive reinforcement)
+7. **What Went Wrong** (improvement areas)
+8. **Action Items** (concrete, owned, dated)
+9. **Lessons Learned** (key takeaways)
+```
+
+## Output Checklist
+
+- [ ] Timeline created
+- [ ] Root cause identified
+- [ ] Contributing factors documented
+- [ ] Action items with owners
+- [ ] Lessons learned captured
+- [ ] Postmortem meeting held
+- [ ] Document shared widely
+- [ ] Follow-up scheduled
+      ENDFILE