@synapta/skills 0.1.0 → 0.1.2

package/skills/deploy-vercel/resources/deploy.sh

@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script (via claimable deploy endpoint)
+# Usage: ./deploy.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://claude-skills-deploy.vercel.com/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+    local pkg_json="$1"
+
+    if [ ! -f "$pkg_json" ]; then
+        echo "null"
+        return
+    fi
+
+    local content=$(cat "$pkg_json")
+
+    # Helper to check if a package exists in dependencies or devDependencies.
+    # Use exact matching by default, with a separate prefix matcher for scoped
+    # package families like "@remix-run/".
+    has_dep_exact() {
+        echo "$content" | grep -q "\"$1\""
+    }
+
+    has_dep_prefix() {
+        echo "$content" | grep -q "\"$1"
+    }
+
+    # Order matters - check more specific frameworks first
+
+    # Blitz
+    if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+    # Next.js
+    if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+    # Gatsby
+    if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+    # Remix
+    if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+    # React Router (v7 framework mode)
+    if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+    # TanStack Start
+    if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+    # Astro
+    if has_dep_exact "astro"; then echo "astro"; return; fi
+
+    # Hydrogen (Shopify)
+    if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+    # SvelteKit
+    if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+    # Svelte (standalone)
+    if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+    # Nuxt
+    if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+    # Vue with Vitepress
+    if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+    # Vue with Vuepress
+    if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+    # Gridsome
+    if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+    # SolidStart
+    if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+    # Docusaurus
+    if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+    # RedwoodJS
+    if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+    # Hexo
+    if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+    # Eleventy
+    if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+    # Angular / Ionic Angular
+    if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+    if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+    # Ionic React
+    if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+    # Create React App
+    if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+    # Ember
+    if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+    # Dojo
+    if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+    # Polymer
+    if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+    # Preact
+    if has_dep_exact "preact"; then echo "preact"; return; fi
+
+    # Stencil
+    if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+    # UmiJS
+    if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+    # Sapper (legacy Svelte)
+    if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+    # Saber
+    if has_dep_exact "saber"; then echo "saber"; return; fi
+
+    # Sanity
+    if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+    if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+    # Storybook
+    if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+    # NestJS
+    if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+    # Elysia
+    if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+    # Hono
+    if has_dep_exact "hono"; then echo "hono"; return; fi
+
+    # Fastify
+    if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+    # h3
+    if has_dep_exact "h3"; then echo "h3"; return; fi
+
+    # Nitro
+    if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+    # Express
+    if has_dep_exact "express"; then echo "express"; return; fi
+
+    # Vite (generic - check last among JS frameworks)
+    if has_dep_exact "vite"; then echo "vite"; return; fi
+
+    # Parcel
+    if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+    # No framework detected
+    echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+    if [ "$CLEANUP_TEMP" = true ]; then
+        rm -rf "$TEMP_DIR"
+    fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+    # Input is already a tarball, use it directly
+    echo "Using provided tarball..." >&2
+    TARBALL="$INPUT_PATH"
+    CLEANUP_TEMP=false
+    # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+    # Input is a directory, need to tar it
+    PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+    # Detect framework from package.json
+    FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+    # Stage files into a temporary directory to avoid mutating the source tree.
+    mkdir -p "$STAGING_DIR"
+    echo "Staging project files..." >&2
+    tar -C "$PROJECT_PATH" \
+        --exclude='node_modules' \
+        --exclude='.git' \
+        --exclude='.env' \
+        --exclude='.env.*' \
+        -cf - . | tar -C "$STAGING_DIR" -xf -
+
+    # Check if this is a static HTML project (no package.json)
+    if [ ! -f "$PROJECT_PATH/package.json" ]; then
+        # Find HTML files in root
+        HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+        HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+        # If there's exactly one HTML file and it's not index.html, rename it
+        if [ "$HTML_COUNT" -eq 1 ]; then
+            HTML_FILE=$(echo "$HTML_FILES" | head -1)
+            BASENAME=$(basename "$HTML_FILE")
+            if [ "$BASENAME" != "index.html" ]; then
+                echo "Renaming $BASENAME to index.html..." >&2
+                mv "$HTML_FILE" "$STAGING_DIR/index.html"
+            fi
+        fi
+    fi
+
+    # Create tarball from the staging directory
+    echo "Creating deployment package..." >&2
+    tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+    echo "Error: Input must be a directory or a .tgz file" >&2
+    exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+    echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+    ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+    echo "Error: $ERROR_MSG" >&2
+    exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+    echo "Error: Could not extract preview URL from response" >&2
+    echo "$RESPONSE" >&2
+    exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60  # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+    HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+    if [ "$HTTP_STATUS" -eq 200 ]; then
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    elif [ "$HTTP_STATUS" -ge 500 ]; then
+        # 5xx means still building/deploying
+        echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+        sleep 5
+        ATTEMPT=$((ATTEMPT + 1))
+    elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+        # 4xx might be an error or the app itself returns 4xx - it's responding
+        echo "" >&2
+        echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+        break
+    else
+        # Any other status, assume it's ready
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+    echo "" >&2
+    echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL:   $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"

package/skills/docs-runbooks/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: docs-runbooks
+synapta_original_name: postmortem-writing
+triggers: [synapta runbook, postmortem, blameless review, RCA writeup, incident doc]
+network: off
+source:
+  origin: https://github.com/wshobson/agents
+  path: plugins/incident-response/skills/postmortem-writing
+  commit: 112197c6bfd0
+  license: MIT (Seth Hobson)
+  adapted: light-touch
+description: Write effective blameless postmortems with root cause analysis, timelines, and action items. Use when conducting incident reviews, writing postmortem documents, or improving incident response processes.
+---
+
+# Postmortem Writing
+
+Comprehensive guide to writing effective, blameless postmortems that drive organizational learning and prevent incident recurrence.
+
+## When to Use This Skill
+
+- Conducting post-incident reviews
+- Writing postmortem documents
+- Facilitating blameless postmortem meetings
+- Identifying root causes and contributing factors
+- Creating actionable follow-up items
+- Building organizational learning culture
+
+## Core Concepts
+
+### 1. Blameless Culture
+
+| Blame-Focused            | Blameless                         |
+| ------------------------ | --------------------------------- |
+| "Who caused this?"       | "What conditions allowed this?"   |
+| "Someone made a mistake" | "The system allowed this mistake" |
+| Punish individuals       | Improve systems                   |
+| Hide information         | Share learnings                   |
+| Fear of speaking up      | Psychological safety              |
+
+### 2. Postmortem Triggers
+
+- SEV1 or SEV2 incidents
+- Customer-facing outages > 15 minutes
+- Data loss or security incidents
+- Near-misses that could have been severe
+- Novel failure modes
+- Incidents requiring unusual intervention
+
+## Quick Start
+
+### Postmortem Timeline
+
+```
+Day 0: Incident occurs
+Day 1-2: Draft postmortem document
+Day 3-5: Postmortem meeting
+Day 5-7: Finalize document, create tickets
+Week 2+: Action item completion
+Quarterly: Review patterns across incidents
+```
+
+## Templates
+
+### Template 1: Standard Postmortem
+
+```markdown
+# Postmortem: [Incident Title]
+
+**Date**: 2024-01-15
+**Authors**: @alice, @bob
+**Status**: Draft | In Review | Final
+**Incident Severity**: SEV2
+**Incident Duration**: 47 minutes
+
+## Executive Summary
+
+On January 15, 2024, the payment processing service experienced a 47-minute outage affecting approximately 12,000 customers. The root cause was a database connection pool exhaustion triggered by a configuration change in deployment v2.3.4. The incident was resolved by rolling back to v2.3.3 and increasing connection pool limits.
+
+**Impact**:
+
+- 12,000 customers unable to complete purchases
+- Estimated revenue loss: $45,000
+- 847 support tickets created
+- No data loss or security implications
+
+## Timeline (All times UTC)
+
+| Time  | Event                                           |
+| ----- | ----------------------------------------------- |
+| 14:23 | Deployment v2.3.4 completed to production       |
+| 14:31 | First alert: `payment_error_rate > 5%`          |
+| 14:33 | On-call engineer @alice acknowledges alert      |
+| 14:35 | Initial investigation begins, error rate at 23% |
+| 14:41 | Incident declared SEV2, @bob joins              |
+| 14:45 | Database connection exhaustion identified       |
+| 14:52 | Decision to rollback deployment                 |
+| 14:58 | Rollback to v2.3.3 initiated                    |
+| 15:10 | Rollback complete, error rate dropping          |
+| 15:18 | Service fully recovered, incident resolved      |
+
+## Root Cause Analysis
+
+### What Happened
+
+The v2.3.4 deployment included a change to the database query pattern that inadvertently removed connection pooling for a frequently-called endpoint. Each request opened a new database connection instead of reusing pooled connections.
+
+### Why It Happened
+
+1. **Proximate Cause**: Code change in `PaymentRepository.java` replaced pooled `DataSource` with direct `DriverManager.getConnection()` calls.
+
+2. **Contributing Factors**:
+   - Code review did not catch the connection handling change
+   - No integration tests specifically for connection pool behavior
+   - Staging environment has lower traffic, masking the issue
+   - Database connection metrics alert threshold was too high (90%)
+
+3. **5 Whys Analysis**:
+   - Why did the service fail? → Database connections exhausted
+   - Why were connections exhausted? → Each request opened new connection
+   - Why did each request open new connection? → Code bypassed connection pool
+   - Why did code bypass connection pool? → Developer unfamiliar with codebase patterns
+   - Why was developer unfamiliar? → No documentation on connection management patterns
+
+### System Diagram
+```
+
+[Client] → [Load Balancer] → [Payment Service] → [Database]
+↓
+Connection Pool (broken)
+↓
+Direct connections (cause)
+
+```
+
+## Detection
+
+### What Worked
+- Error rate alert fired within 8 minutes of deployment
+- Grafana dashboard clearly showed connection spike
+- On-call response was swift (2 minute acknowledgment)
+
+### What Didn't Work
+- Database connection metric alert threshold too high
+- No deployment-correlated alerting
+- Canary deployment would have caught this earlier
+
+### Detection Gap
+The deployment completed at 14:23, but the first alert didn't fire until 14:31 (8 minutes). A deployment-aware alert could have detected the issue faster.
+
+## Response
+
+### What Worked
+- On-call engineer quickly identified database as the issue
+- Rollback decision was made decisively
+- Clear communication in incident channel
+
+### What Could Be Improved
+- Took 10 minutes to correlate issue with recent deployment
+- Had to manually check deployment history
+- Rollback took 12 minutes (could be faster)
+
+## Impact
+
+### Customer Impact
+- 12,000 unique customers affected
+- Average impact duration: 35 minutes
+- 847 support tickets (23% of affected users)
+- Customer satisfaction score dropped 12 points
+
+### Business Impact
+- Estimated revenue loss: $45,000
+- Support cost: ~$2,500 (agent time)
+- Engineering time: ~8 person-hours
+
+### Technical Impact
+- Database primary experienced elevated load
+- Some replica lag during incident
+- No permanent damage to systems
+
+## Lessons Learned
+
+### What Went Well
+1. Alerting detected the issue before customer reports
+2. Team collaborated effectively under pressure
+3. Rollback procedure worked smoothly
+4. Communication was clear and timely
+
+### What Went Wrong
+1. Code review missed critical change
+2. Test coverage gap for connection pooling
+3. Staging environment doesn't reflect production traffic
+4. Alert thresholds were not tuned properly
+
+### Where We Got Lucky
+1. Incident occurred during business hours with full team available
+2. Database handled the load without failing completely
+3. No other incidents occurred simultaneously
+
+## Action Items
+
+| Priority | Action | Owner | Due Date | Ticket |
+|----------|--------|-------|----------|--------|
+| P0 | Add integration test for connection pool behavior | @alice | 2024-01-22 | ENG-1234 |
+| P0 | Lower database connection alert threshold to 70% | @bob | 2024-01-17 | OPS-567 |
+| P1 | Document connection management patterns | @alice | 2024-01-29 | DOC-89 |
+| P1 | Implement deployment-correlated alerting | @bob | 2024-02-05 | OPS-568 |
+| P2 | Evaluate canary deployment strategy | @charlie | 2024-02-15 | ENG-1235 |
+| P2 | Load test staging with production-like traffic | @dave | 2024-02-28 | QA-123 |
+
+## Appendix
+
+### Supporting Data
+
+#### Error Rate Graph
+[Link to Grafana dashboard snapshot]
+
+#### Database Connection Graph
+[Link to metrics]
+
+### Related Incidents
+- 2023-11-02: Similar connection issue in User Service (POSTMORTEM-42)
+
+### References
+- [Connection Pool Best Practices](internal-wiki/connection-pools)
+- [Deployment Runbook](internal-wiki/deployment-runbook)
+```
+
+### Template 2: 5 Whys Analysis
+
+```markdown
+# 5 Whys Analysis: [Incident]
+
+## Problem Statement
+
+Payment service experienced 47-minute outage due to database connection exhaustion.
+
+## Analysis
+
+### Why #1: Why did the service fail?
+
+**Answer**: Database connections were exhausted, causing all new requests to fail.
+
+**Evidence**: Metrics showed connection count at 100/100 (max), with 500+ pending requests.
+
+---
+
+### Why #2: Why were database connections exhausted?
+
+**Answer**: Each incoming request opened a new database connection instead of using the connection pool.
+
+**Evidence**: Code diff shows direct `DriverManager.getConnection()` instead of pooled `DataSource`.
+
+---
+
+### Why #3: Why did the code bypass the connection pool?
+
+**Answer**: A developer refactored the repository class and inadvertently changed the connection acquisition method.
+
+**Evidence**: PR #1234 shows the change, made while fixing a different bug.
+
+---
+
+### Why #4: Why wasn't this caught in code review?
+
+**Answer**: The reviewer focused on the functional change (the bug fix) and didn't notice the infrastructure change.
+
+**Evidence**: Review comments only discuss business logic.
+
+---
+
+### Why #5: Why isn't there a safety net for this type of change?
+
+**Answer**: We lack automated tests that verify connection pool behavior and lack documentation about our connection patterns.
+
+**Evidence**: Test suite has no tests for connection handling; wiki has no article on database connections.
+
+## Root Causes Identified
+
+1. **Primary**: Missing automated tests for infrastructure behavior
+2. **Secondary**: Insufficient documentation of architectural patterns
+3. **Tertiary**: Code review checklist doesn't include infrastructure considerations
+
+## Systemic Improvements
+
+| Root Cause    | Improvement                       | Type       |
+| ------------- | --------------------------------- | ---------- |
+| Missing tests | Add infrastructure behavior tests | Prevention |
+| Missing docs  | Document connection patterns      | Prevention |
+| Review gaps   | Update review checklist           | Detection  |
+| No canary     | Implement canary deployments      | Mitigation |
+```
+
+### Template 3: Quick Postmortem (Minor Incidents)
+
+```markdown
+# Quick Postmortem: [Brief Title]
+
+**Date**: 2024-01-15 | **Duration**: 12 min | **Severity**: SEV3
+
+## What Happened
+
+API latency spiked to 5s due to cache miss storm after cache flush.
+
+## Timeline
+
+- 10:00 - Cache flush initiated for config update
+- 10:02 - Latency alerts fire
+- 10:05 - Identified as cache miss storm
+- 10:08 - Enabled cache warming
+- 10:12 - Latency normalized
+
+## Root Cause
+
+Full cache flush for minor config update caused thundering herd.
+
+## Fix
+
+- Immediate: Enabled cache warming
+- Long-term: Implement partial cache invalidation (ENG-999)
+
+## Lessons
+
+Don't full-flush cache in production; use targeted invalidation.
+```
+
+## Facilitation Guide
+
+### Running a Postmortem Meeting
+
+```markdown
+## Meeting Structure (60 minutes)
+
+### 1. Opening (5 min)
+
+- Remind everyone of blameless culture
+- "We're here to learn, not to blame"
+- Review meeting norms
+
+### 2. Timeline Review (15 min)
+
+- Walk through events chronologically
+- Ask clarifying questions
+- Identify gaps in timeline
+
+### 3. Analysis Discussion (20 min)
+
+- What failed?
+- Why did it fail?
+- What conditions allowed this?
+- What would have prevented it?
+
+### 4. Action Items (15 min)
+
+- Brainstorm improvements
+- Prioritize by impact and effort
+- Assign owners and due dates
+
+### 5. Closing (5 min)
+
+- Summarize key learnings
+- Confirm action item owners
+- Schedule follow-up if needed
+
+## Facilitation Tips
+
+- Keep discussion on track
+- Redirect blame to systems
+- Encourage quiet participants
+- Document dissenting views
+- Time-box tangents
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern            | Problem                    | Better Approach                 |
+| ----------------------- | -------------------------- | ------------------------------- |
+| **Blame game**          | Shuts down learning        | Focus on systems                |
+| **Shallow analysis**    | Doesn't prevent recurrence | Ask "why" 5 times               |
+| **No action items**     | Waste of time              | Always have concrete next steps |
+| **Unrealistic actions** | Never completed            | Scope to achievable tasks       |
+| **No follow-up**        | Actions forgotten          | Track in ticketing system       |
+
+## Best Practices
+
+### Do's
+
+- **Start immediately** - Memory fades fast
+- **Be specific** - Exact times, exact errors
+- **Include graphs** - Visual evidence
+- **Assign owners** - No orphan action items
+- **Share widely** - Organizational learning
+
+### Don'ts
+
+- **Don't name and shame** - Ever
+- **Don't skip small incidents** - They reveal patterns
+- **Don't make it a blame doc** - That kills learning
+- **Don't create busywork** - Actions should be meaningful
+- **Don't skip follow-up** - Verify actions completed