swe-workflow-skills 0.1.0

package/skills/observability-design/references/logging-patterns.md

@@ -0,0 +1,229 @@
+# Logging and Alerting Patterns
+
+## Contents
+- Structured logging design
+- Log levels guide
+- Correlation patterns
+- Sensitive data handling
+- Alerting design patterns
+- OpenTelemetry instrumentation snippets
+
+## Structured Logging Design
+
+Every log entry should be a JSON object with consistent fields:
+
+```json
+{
+  "timestamp": "2025-03-05T14:30:00.123Z",
+  "level": "error",
+  "message": "Payment processing failed",
+  "service": "payment-service",
+  "environment": "production",
+  "trace_id": "abc123def456",
+  "span_id": "789ghi",
+  "request_id": "req-001-xyz",
+  "user_id": "usr_42",
+  "error": {
+    "type": "StripeCardError",
+    "message": "Card declined",
+    "code": "card_declined"
+  },
+  "context": {
+    "order_id": "ord_123",
+    "amount_cents": 5999,
+    "currency": "USD"
+  },
+  "duration_ms": 342
+}
+```
+
+**Required fields** (every log entry):
+- `timestamp` — ISO 8601 UTC
+- `level` — debug, info, warn, error, fatal
+- `message` — human-readable summary
+- `service` — originating service name
+
+**Recommended fields** (when available):
+- `trace_id`, `span_id` — for correlation with distributed traces
+- `request_id` — for correlating all logs within a single request
+- `user_id` — for investigating user-reported issues
+- `environment` — dev, staging, production
+- `duration_ms` — for operations with measurable duration
+
+**Contextual fields** (operation-specific):
+- Add structured context relevant to the operation (order_id, endpoint, query)
+- Use nested objects for complex context, not flat key collision
+
+## Log Levels Guide
+
+| Level | When to Use | Example | Alerting |
+|-------|-------------|---------|----------|
+| **fatal** | System cannot continue | Unrecoverable startup failure, data corruption detected | Page immediately |
+| **error** | Operation failed, requires attention | Payment declined, database connection failed, unhandled exception | Alert / ticket |
+| **warn** | Unexpected but recoverable | Retry succeeded, deprecated API called, approaching rate limit | Monitor trend |
+| **info** | Normal operations worth noting | Request completed, user logged in, deployment started | None |
+| **debug** | Diagnostic detail | SQL query executed, cache hit/miss, intermediate calculation | Never in prod |
+
+**Rules:**
+- Production should run at `info` level by default
+- `debug` in production only temporarily, for active debugging (turn off after)
+- Every `error` log should include enough context to investigate without reproduction
+- Never log at `error` for expected conditions (user input validation failure = `warn`, not `error`)
+
+## Correlation Patterns
+
+### Request-scoped correlation
+```javascript
+// Middleware that creates a correlation context for every request
+app.use((req, res, next) => {
+  const requestId = req.headers['x-request-id'] || crypto.randomUUID();
+  const traceId = req.headers['traceparent']?.split('-')[1] || requestId;
+
+  // Attach to request context
+  req.context = { requestId, traceId };
+
+  // Include in all logs for this request
+  req.log = logger.child({
+    request_id: requestId,
+    trace_id: traceId,
+    method: req.method,
+    path: req.path,
+  });
+
+  next();
+});
+```
+
+### Cross-service propagation
+When calling another service, propagate the trace context:
+```javascript
+// Include trace headers when making downstream calls
+const response = await fetch('https://payment-service/charge', {
+  headers: {
+    'traceparent': `00-${traceId}-${spanId}-01`,
+    'x-request-id': requestId,
+  },
+  body: JSON.stringify(payload),
+});
+```
+
+This allows tracing a single user request across all services it touches.
+
+## Sensitive Data Handling
+
+**Never log:**
+- Passwords, tokens, API keys, secrets
+- Full credit card numbers (log last 4 digits only)
+- Social Security Numbers, government IDs
+- Personal health information
+- Full request/response bodies containing PII
+
+**Redaction patterns:**
+```javascript
+function redactSensitive(obj) {
+  const sensitiveKeys = ['password', 'token', 'secret', 'authorization', 'ssn', 'credit_card'];
+  const redacted = { ...obj };
+  for (const key of Object.keys(redacted)) {
+    if (sensitiveKeys.some(s => key.toLowerCase().includes(s))) {
+      redacted[key] = '[REDACTED]';
+    }
+  }
+  return redacted;
+}
+```
+
+## Alerting Design Patterns
+
+### Good alert anatomy
+```yaml
+alert: HighErrorRate
+expr: |
+  (sum(rate(http_requests_total{status=~"5.."}[5m]))
+  / sum(rate(http_requests_total[5m]))) > 0.01
+for: 5m    # Must persist for 5 minutes (avoid flapping)
+labels:
+  severity: page
+annotations:
+  summary: "Error rate above 1% for 5 minutes"
+  description: "{{ $labels.service }} error rate is {{ $value | humanizePercentage }}"
+  runbook: "https://runbooks.internal/high-error-rate"
+  dashboard: "https://grafana.internal/d/service-overview"
+```
+
+### Alert quality checklist
+- [ ] **Actionable**: Someone can do something about it right now
+- [ ] **Urgent**: It needs attention now (if not, make it a ticket, not an alert)
+- [ ] **Contextualized**: Includes which service, what metric, and links to dashboards/runbooks
+- [ ] **Not noisy**: Fires less than once per week on average (more frequent = tune or suppress)
+- [ ] **Tested**: Someone has verified it fires correctly and the runbook works
+- [ ] **Has an owner**: Someone is responsible for responding
+
+### Reducing alert fatigue
+- Alert on symptoms (error rate, latency) not causes (CPU, memory)
+- Use burn rate alerting instead of raw thresholds
+- Aggregate related alerts (one "service degraded" instead of five "endpoint X failing")
+- Auto-resolve alerts that recover within the evaluation window
+- Review alerts monthly: if an alert never fires, remove it; if it always fires, fix or tune it
+
+## OpenTelemetry Instrumentation Snippets
+
+### Node.js auto-instrumentation
+```javascript
+// tracing.js — import before any other module
+const { NodeSDK } = require('@opentelemetry/sdk-node');
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-http');
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: 'http://otel-collector:4318/v1/traces' }),
+  metricExporter: new OTLPMetricExporter({ url: 'http://otel-collector:4318/v1/metrics' }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+### Python auto-instrumentation
+```python
+# Run with: opentelemetry-instrument python app.py
+# Or programmatically:
+from opentelemetry import trace, metrics
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+
+provider = TracerProvider()
+processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4317"))
+provider.add_span_processor(processor)
+trace.set_tracer_provider(provider)
+
+# Add custom spans
+tracer = trace.get_tracer(__name__)
+
+with tracer.start_as_current_span("process_order", attributes={"order.id": order_id}):
+    validate_order(order)
+    with tracer.start_as_current_span("charge_payment"):
+        charge_result = process_payment(order)
+```
+
+### Custom metrics
+```python
+from opentelemetry import metrics
+
+meter = metrics.get_meter(__name__)
+
+# Counter — things that only go up
+request_counter = meter.create_counter("http.requests.total", description="Total HTTP requests")
+request_counter.add(1, {"method": "GET", "path": "/api/users", "status": 200})
+
+# Histogram — distributions
+latency_histogram = meter.create_histogram("http.request.duration", unit="ms")
+latency_histogram.record(42.5, {"method": "GET", "path": "/api/users"})
+
+# Gauge (via observable) — point-in-time values
+def get_queue_depth(observer):
+    observer.observe(get_current_queue_size(), {"queue": "orders"})
+
+meter.create_observable_gauge("queue.depth", callbacks=[get_queue_depth])
+```

package/skills/observability-design/references/slo-framework.md

@@ -0,0 +1,151 @@
+# SLO Framework Reference
+
+## Contents
+- Nines table
+- Error budget calculations
+- SLO examples by service type
+- Burn rate alerting
+- Error budget policies
+
+## Nines Table
+
+| Availability | Annual Downtime | Monthly Downtime | Common Name |
+|-------------|-----------------|------------------|-------------|
+| 99% | 3.65 days | 7.3 hours | Two nines |
+| 99.5% | 1.83 days | 3.65 hours | |
+| 99.9% | 8.77 hours | 43.2 minutes | Three nines |
+| 99.95% | 4.38 hours | 21.6 minutes | Three and a half nines |
+| 99.99% | 52.6 minutes | 4.32 minutes | Four nines |
+| 99.999% | 5.26 minutes | 26 seconds | Five nines |
+
+Each additional nine costs roughly 10x more to achieve. Going from 99.9% to 99.99% doesn't sound like much, but it means moving from 43 minutes of monthly downtime to 4 minutes — that requires redundancy, failover, and operational maturity most teams don't have.
+
+## Error Budget Calculations
+
+```
+Error Budget (%) = 100% - SLO (%)
+Error Budget (time) = Error Budget (%) × Time Window
+
+Example:
+  SLO: 99.9% over 30 days
+  Error budget: 0.1% × 30 days = 0.001 × 43,200 minutes = 43.2 minutes
+
+  If an outage lasts 15 minutes:
+  Budget consumed: 15 / 43.2 = 34.7%
+  Budget remaining: 65.3%
+```
+
+For request-based SLOs:
+```
+Error Budget (requests) = Total requests × (1 - SLO)
+
+Example:
+  SLO: 99.9% success rate
+  Monthly requests: 10,000,000
+  Error budget: 10,000,000 × 0.001 = 10,000 failed requests allowed
+```
+
+## SLO Examples by Service Type
+
+### Web API
+```
+SLI: Availability = Requests with status < 500 / Total requests
+SLO: 99.9% over 30 days
+
+SLI: Latency = Requests completing in < 300ms / Total requests
+SLO: 99% over 30 days (at P99)
+```
+
+### Data Pipeline
+```
+SLI: Freshness = Pipeline runs completing within 2 hours of schedule / Total scheduled runs
+SLO: 99.5% over 30 days
+
+SLI: Quality = Records passing validation / Total records processed
+SLO: 99.9% over 30 days
+```
+
+### User-Facing Web Application
+```
+SLI: Availability = Successful page loads / Total page load attempts
+SLO: 99.95% over 30 days
+
+SLI: Latency = Page loads completing in < 2s / Total page loads
+SLO: 95% over 30 days
+```
+
+### Background Job / Queue Consumer
+```
+SLI: Processing success = Jobs completing successfully / Total jobs started
+SLO: 99.9% over 30 days
+
+SLI: Processing latency = Jobs completing within SLA / Total jobs
+SLO: 99% within 5 minutes of enqueue
+```
+
+## Burn Rate Alerting
+
+Raw threshold alerts ("error rate > 1%") are noisy. Burn rate alerts ask: "At the current error rate, how fast are we consuming our error budget?"
+
+```
+Burn rate = (Current error rate / Allowed error rate)
+
+If burn rate = 1: you'll exactly exhaust budget by end of window
+If burn rate = 10: you'll exhaust budget in 1/10th of the window
+If burn rate = 0.5: you're consuming half the allowed rate (healthy)
+```
+
+### Multi-window alerting (Google SRE recommendation)
+
+| Alert Level | Long Window | Short Window | Burn Rate | Budget Consumed |
+|-------------|-------------|--------------|-----------|-----------------|
+| Page (urgent) | 1 hour | 5 minutes | 14.4x | 2% in 1 hour |
+| Page (fast) | 6 hours | 30 minutes | 6x | 5% in 6 hours |
+| Ticket (slow) | 3 days | 6 hours | 1x | 10% in 3 days |
+
+The short window confirms the problem is still happening (not a spike that already resolved). The long window establishes the trend.
+
+## Error Budget Policies
+
+Document these policies and get sign-off from engineering and product leadership:
+
+```markdown
+## Error Budget Policy for [Service Name]
+
+### When budget > 50% remaining
+- Normal development velocity
+- Deploy at normal cadence
+- Standard review process
+
+### When budget 25-50% remaining
+- Review recent incidents for patterns
+- Prioritize reliability-related tech debt
+- Increase test coverage for affected paths
+
+### When budget 10-25% remaining
+- Reduce deployment frequency
+- Require additional review for risky changes
+- Begin reliability sprint planning
+
+### When budget < 10% remaining
+- Freeze all non-critical feature deployments
+- Dedicate engineering capacity to reliability
+- Conduct architecture review for systemic issues
+
+### When budget is exhausted
+- Full feature freeze until budget recovers
+- Post-incident review required for every incident
+- Escalate to leadership for resource allocation
+```
+
+## Common Mistakes in SLO Design
+
+**Setting SLOs too high**: 99.99% sounds great but allows only 4 minutes of downtime per month. If your team can't respond to an incident in 4 minutes, this SLO is aspirational, not achievable.
+
+**Using internal metrics as SLIs**: CPU utilization, memory usage, and queue depth are operational signals, not user experience signals. Users don't care about your CPU — they care about latency and errors.
+
+**No error budget policy**: SLOs without consequences are decorative. Define what happens when the budget runs low.
+
+**Too many SLOs**: 3-5 SLOs per service is sufficient. More than that dilutes focus and creates contradictory pressures.
+
+**SLO = SLA**: Your SLO should be tighter than your SLA. The SLO is your internal early warning. If you only react at SLA boundaries, you're already failing customers.

package/skills/observability-design/templates/slo-document.md

@@ -0,0 +1,80 @@
+# SLO Document Template
+
+```markdown
+# SLO: [Service Name]
+
+**Owner**: [Team / individual]
+**Last reviewed**: [YYYY-MM-DD]
+**Review cadence**: Quarterly
+
+## Service Description
+
+[1-2 sentences: what this service does and who its users are.]
+
+## Critical User Journeys
+
+1. [Journey 1: e.g., "User loads the product catalog"]
+2. [Journey 2: e.g., "User completes checkout"]
+3. [Journey 3: e.g., "User searches for products"]
+
+## SLIs and SLOs
+
+### SLO 1: Availability
+
+**SLI**: Proportion of HTTP requests that return a non-5xx status code
+**Measurement**: Load balancer access logs
+**Window**: 30-day rolling
+**Target**: 99.9%
+
+**Error Budget**: 0.1% = 43.2 minutes of downtime per month
+
+### SLO 2: Latency
+
+**SLI**: Proportion of HTTP requests completing within 300ms
+**Measurement**: Application-side histogram (P99)
+**Window**: 30-day rolling
+**Target**: 99% of requests under 300ms
+
+### SLO 3: [Additional SLO if needed]
+
+**SLI**: [measurement]
+**Measurement**: [data source]
+**Window**: [time window]
+**Target**: [target value]
+
+## Error Budget Policy
+
+| Budget Remaining | Action |
+|-----------------|--------|
+| > 50% | Normal development velocity |
+| 25-50% | Prioritize reliability tech debt |
+| 10-25% | Reduce deployment frequency |
+| < 10% | Freeze non-critical features |
+| Exhausted | Full reliability focus |
+
+## Alerting
+
+| Alert | Condition | Severity | Runbook |
+|-------|-----------|----------|---------|
+| Fast burn | 2% budget consumed in 1 hour | Page | [link] |
+| Slow burn | 5% budget consumed in 6 hours | Page | [link] |
+| Trend | 10% budget consumed in 3 days | Ticket | [link] |
+
+## Dashboard
+
+[Link to the service dashboard]
+
+## Dependencies
+
+| Dependency | Their SLO | Impact if degraded |
+|------------|-----------|-------------------|
+| [Database] | [target] | [what breaks] |
+| [Auth service] | [target] | [what breaks] |
+| [External API] | [target] | [what breaks] |
+
+## Review History
+
+| Date | Change | Rationale |
+|------|--------|-----------|
+| [YYYY-MM-DD] | Initial SLO | Based on historical performance |
+```

package/skills/performance-optimization/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: performance-optimization
+description: "Identify and resolve performance bottlenecks via static analysis — N+1 queries, algorithmic complexity, query optimization, caching, memory leaks, bundle size, connection management. Triggers: this is slow, optimize, performance, N+1, query optimization, caching, bundle size, memory leak, latency, response time, scale, bottleneck."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Performance Optimization
+
+Identify and resolve performance bottlenecks through static analysis and design review. Good performance optimization is measurement-driven — identify the bottleneck first, optimize second.
+
+## Core Rule
+
+**Never optimize without understanding the bottleneck.** Random optimization wastes time and often makes things worse. The workflow is always: measure → identify → optimize → verify.
+
+## Workflow
+
+### Step 1: Understand the Problem
+
+Before touching code, establish baselines:
+
+- **What is slow?** Specific endpoint, page load, batch job, query?
+- **How slow?** Current latency/throughput numbers (or perceived slowness)
+- **What's acceptable?** Target latency, throughput, or response time
+- **When did it start?** Was it always slow, or is this a regression?
+- **Under what conditions?** Load-dependent, data-size-dependent, time-dependent?
+
+If the user doesn't have measurements, help them instrument first (see Step 2). Optimization without measurement is guessing.
+
+### Step 2: Identify the Bottleneck
+
+The bottleneck is almost always in one of these areas. Check in this order (most common first):
+
+1. **Database queries** — N+1 problems, missing indexes, full table scans, unoptimized joins
+2. **External API calls** — Sequential calls that could be parallel, no caching of responses
+3. **Algorithmic complexity** — O(n²) or worse hiding in loops, nested iterations over large datasets
+4. **Memory usage** — Leaks, loading entire datasets into memory, unbounded caches
+5. **Network/I/O** — Large payloads, no compression, chatty protocols, missing CDN
+6. **Serialization** — Expensive JSON parsing/generation, unnecessary data transformation
+7. **Concurrency issues** — Race conditions, lock contention, thread pool exhaustion, async bottlenecks. See [references/concurrency.md](references/concurrency.md) for patterns and common bugs.
+
+See [references/bottleneck-patterns.md](references/bottleneck-patterns.md) for the detailed detection guide.
+
+### Step 3: Analyze and Recommend
+
+For each identified bottleneck:
+
+1. **Explain** what the problem is and why it causes slowness
+2. **Quantify** the impact (e.g., "This makes 50 DB queries per page load instead of 2")
+3. **Propose** a specific fix with expected improvement
+4. **Assess** the complexity and risk of the fix
+
+Order recommendations by impact-to-effort ratio. The best optimizations are high impact and low effort.
+
+### Step 4: Implement the Fix
+
+Apply one optimization at a time. For each:
+
+1. Write or confirm a performance test exists (even a simple timing assertion)
+2. Apply the change
+3. Verify the improvement
+4. Check for regressions (functional tests still pass, other paths not degraded)
+
+### Step 5: Verify and Document
+
+After optimization:
+- Compare before/after metrics
+- Document what was changed and why (this prevents someone from "cleaning up" the optimization later)
+- Set up monitoring to alert if performance regresses
+
+## Anti-patterns
+
+- **Premature optimization**: Don't optimize code that runs once at startup or handles 10 requests/day
+- **Micro-optimization**: Don't optimize individual array operations when the real bottleneck is a database query taking 2 seconds
+- **Caching everything**: Caches add complexity and staleness bugs. Cache only what's measured as slow and frequently accessed
+- **Optimizing the wrong layer**: Frontend optimization won't fix a slow API. Database optimization won't fix a slow algorithm
+- **Sacrificing readability**: If the optimization makes the code unmaintainable, it's a bad trade unless the performance gain is critical
+
+## Principles Applied
+
+- **KISS**: The simplest optimization that meets the target wins. Don't build a distributed cache when a database index will do.
+- **YAGNI**: Optimize for current scale, not hypothetical future scale. Document triggers for when to revisit.
+- **DRY**: Centralize caching logic, query optimization, and connection management — don't optimize the same pattern in 10 places.

package/skills/performance-optimization/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "performance-optimization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our product listing page takes 4 seconds to load. Here's the endpoint:\n\napp.get('/products', async (req, res) => {\n  const products = await db.products.findMany();\n  for (const product of products) {\n    product.category = await db.categories.findById(product.categoryId);\n    product.reviews = await db.reviews.findMany({ where: { productId: product.id } });\n    product.averageRating = product.reviews.reduce((sum, r) => sum + r.rating, 0) / product.reviews.length;\n    product.seller = await db.users.findById(product.sellerId);\n  }\n  res.json(products);\n});",
+      "expected_output": "Should identify the N+1 problem as the primary bottleneck (3 queries per product in a loop), recommend eager loading or batch queries, and note the missing pagination. Should quantify the impact.",
+      "assertions": [
+        "Identifies the N+1 query problem as the primary bottleneck",
+        "Quantifies the impact (if 100 products: 1 + 100 + 100 + 100 = 301 queries)",
+        "Recommends eager loading (include/join) or batch loading (IN clause)",
+        "Identifies missing pagination (loads ALL products)",
+        "Suggests computing averageRating in the database query, not in application code",
+        "Does NOT start with micro-optimizations (variable names, array methods)",
+        "Provides concrete refactored code",
+        "Suggests adding an index on reviews.productId if not present"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our API response times are fine for small accounts but degrade badly for enterprise customers with 50K+ records. The main offender is the search endpoint. How should I approach this?",
+      "expected_output": "Should ask for the current query and indexes, suggest EXPLAIN ANALYZE, and recommend strategies for large dataset search (proper indexing, cursor pagination, search-specific solutions like Elasticsearch for complex search).",
+      "assertions": [
+        "Asks to see the current query and database schema",
+        "Suggests running EXPLAIN ANALYZE on the slow query",
+        "Identifies that OFFSET-based pagination degrades with large datasets",
+        "Recommends cursor-based pagination",
+        "Considers whether a dedicated search index (Elasticsearch, Meilisearch) is appropriate",
+        "Does NOT immediately recommend adding Redis cache as the first solution",
+        "Applies KISS — recommends database-level fixes before adding new infrastructure"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Make this function faster:\n\nfunction findDuplicateEmails(users) {\n  const duplicates = [];\n  for (let i = 0; i < users.length; i++) {\n    for (let j = i + 1; j < users.length; j++) {\n      if (users[i].email.toLowerCase() === users[j].email.toLowerCase()) {\n        if (!duplicates.includes(users[i].email.toLowerCase())) {\n          duplicates.push(users[i].email.toLowerCase());\n        }\n      }\n    }\n  }\n  return duplicates;\n}",
+      "expected_output": "Should identify the O(n²) nested loop plus O(n) includes() check (effectively O(n³) worst case), and refactor to O(n) using a Map/Set.",
+      "assertions": [
+        "Identifies the algorithmic complexity (O(n²) from nested loops, O(n) from includes)",
+        "Explains WHY this is slow for large arrays",
+        "Refactors to O(n) using a Map or object for counting",
+        "Uses a Set for the duplicates result (not includes() on an array)",
+        "Notes the repeated toLowerCase() calls as a secondary optimization",
+        "Provides working refactored code"
+      ]
+    }
+  ]
+}