swe-workflow-skills 0.1.0

package/skills/incident-response/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: incident-response
+description: "Structured production incident workflow — triage, mitigation, investigation, recovery, comms. Triggers: production is down, site is down, incident, outage, users seeing errors, on-call, alert fired, p0, p1, sev1, sev2, broken in prod, rollback, emergency deploy. For active incidents under time pressure."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Incident Response
+
+Resolve production incidents quickly and safely. Under pressure, the instinct to jump to fixes causes more harm than good — this workflow keeps the response structured without slowing it down.
+
+## ⛔ The Iron Law
+
+**Mitigate before you investigate; never declare resolved without verification evidence.**
+
+Stopping user impact and understanding the cause are separate jobs — don't trade the first for the second. And under pressure, a forward fix you haven't reviewed or verified often creates a second incident: prefer the blunt, reversible mitigation now and confirm recovery with data before declaring the incident over.
+
+## Step 1: Triage — Scope and Severity
+
+Spend 2-3 minutes here, not more.
+
+**Determine blast radius:**
+- What is broken? (Specific feature, entire service, dependent services)
+- Who is affected? (All users, subset, specific accounts, internal only)
+- Is data being lost or corrupted? (If yes: severity immediately escalates)
+- Is the issue getting worse over time or stable?
+
+**Classify severity:**
+- **Sev1/P0**: Complete service outage, data loss, security breach. All hands.
+- **Sev2/P1**: Major feature down, significant user impact, degraded performance at scale.
+- **Sev3/P2**: Minor feature broken, small user subset affected, workaround exists.
+
+If you can't classify yet, treat it as Sev2 until proven otherwise.
+
+**Notify the right people now.** Don't wait until you understand the problem. People need lead time to join.
+
+See [references/severity-levels.md](references/severity-levels.md) for team-specific escalation paths.
+
+## Step 2: Mitigate First — Fix Later
+
+The goal is to stop the bleeding, not to understand it. Mitigation and root cause analysis are separate phases.
+
+**Fastest mitigation options (try in order):**
+1. **Feature flag off**: If the broken code is behind a flag, disable it immediately
+2. **Rollback**: If a recent deploy caused this, revert to the previous version
+3. **Traffic shed**: Disable the specific endpoint or functionality that's failing
+4. **Circuit breaker / cache**: Serve stale data while the live system is broken
+5. **Scale up**: If it's a load issue, add capacity before investigating
+
+Apply the first option that will work. Do not spend 20 minutes finding the perfect mitigation — apply the blunt one now, refine later.
+
+Document each action with a timestamp as you go. This builds the post-mortem timeline automatically.
+
+See [references/communication-templates.md](references/communication-templates.md) for status page and stakeholder update templates.
+
+## Step 3: Communicate
+
+A brief status update every 15-30 minutes prevents stakeholders from escalating or interrupting responders. Use the template in [references/communication-templates.md](references/communication-templates.md):
+
+```
+[TIME] Status: [Investigating / Mitigating / Recovering]
+Impact: [What is broken, who is affected]
+Last action: [What was just done]
+Next action: [What's happening next]
+ETA: [Best estimate or "unknown"]
+```
+
+Assign one person as the incident commander (coordinates response) and one as the communications lead (external updates). The same person should not do both under pressure.
+
+## Step 4: Investigate — Rapid Root Cause
+
+Once mitigation is in place and user impact is reduced, find the root cause.
+
+Apply the binary search from `bug-investigating` at high speed:
+1. **When did it start?** Check deployment logs, config changes, dependency changes in the window before the incident.
+2. **What changed?** Compare current state to last-known-good state.
+3. **Reproduce in isolation?** Can you trigger the error on a single request/record?
+4. **Trace the error path**: Follow the error from symptom back to cause using logs, traces, and metrics.
+
+Time-box investigation phases: 15 minutes to identify the probable cause. If not found, escalate or bring in more people.
+
+## Step 5: Recover and Verify
+
+**Deploy the fix:**
+- For rollbacks: verify the previous version is clean, deploy, monitor for 10 minutes
+- For forward fixes: code review is still required (even during incidents, a second set of eyes prevents making things worse)
+- For config changes: change one variable at a time
+
+**Verify recovery:**
+- Error rate returns to baseline
+- Latency returns to normal
+- Affected functionality works end-to-end
+- No secondary issues (cascading failures, queue backlogs)
+
+**Declare the incident resolved** with a timestamp. Send a final status update.
+
+**Schedule the post-mortem** within 48-72 hours while memory is fresh. Use the `retrospective` skill (incident post-mortem format).
+
+## Principles Applied
+
+- **KISS**: Apply the simplest mitigation first. A blunt rollback that works beats an elegant fix that takes an hour.
+- **Blameless culture**: Incidents are caused by systems, not people. Focus on what the system allowed, not who triggered it.
+- **Communication over silence**: Even "we don't know yet" is better than silence. Stakeholders will escalate if they don't hear anything.
+- **Separate mitigation from investigation**: Stopping user impact and understanding root cause are different work. Don't conflate them.
+
+## Rationalizations to reject
+
+Time pressure makes these tempting. Reject them anyway.
+
+| Excuse | Reality |
+|--------|---------|
+| "Let me find the root cause first" | Every minute investigating is a minute users stay broken. Mitigate first. |
+| "I know what's wrong — quick forward fix" | Forward fixes under pressure cause secondary incidents; a rollback is usually faster and safer. |
+| "Skip code review, it's an emergency" | A second set of eyes is cheapest exactly when the stakes are highest. |
+| "Error rate looks better, call it resolved" | "Looks better" is not baseline. Verify error rate, latency, and end-to-end function. |
+| "I'll update people once it's fixed" | Silence makes stakeholders escalate. Send a status even when it's "we don't know yet." |
+
+## Red flags — stop and correct course
+
+- Debugging root cause while users are still impacted and no mitigation is live.
+- Deploying a forward fix you haven't reviewed.
+- Declaring resolved from a single metric or a quick glance.
+- No timestamped action log being kept as you go.
+
+## Cross-Skill References
+
+- `rollback-strategy` — design safe rollback plans before incidents happen
+- `bug-investigating` — use for offline root cause analysis after mitigation
+- `retrospective` — use the incident post-mortem format after the incident resolves
+- `deployment-checklist` — gate future deploys to prevent recurrence

package/skills/incident-response/evals/evals.json

@@ -0,0 +1,55 @@
+{
+  "skill_name": "incident-response",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Production is down. Users are getting 500 errors on checkout. We deployed 20 minutes ago. What do I do?",
+      "expected_output": "Structured incident response starting with triage (scope/severity assessment), immediate mitigation recommendation (rollback the deploy), communication guidance, and timeline tracking",
+      "assertions": [
+        "Immediately recommends rollback as fastest mitigation given recent deploy",
+        "Asks or addresses scope questions: is it all users or a subset? Is it only checkout or other pages too?",
+        "Recommends notifying stakeholders now, not after root cause is found",
+        "Distinguishes mitigation (stop the bleeding) from investigation (find the cause)",
+        "Does not attempt deep root cause analysis before mitigation is in place",
+        "Suggests monitoring after rollback to verify recovery"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We have an incident where a background job is running but producing incorrect results — all order totals calculated in the last 2 hours are wrong by about 15%. No service is down, users aren't seeing errors. How should we handle this?",
+      "expected_output": "Recognizes this as a data integrity incident (potentially Sev1 despite no downtime), recommends stopping the job immediately, scoping the data impact, and planning data correction before communication",
+      "assertions": [
+        "Recognizes data corruption as a high-severity issue even without service downtime",
+        "Recommends stopping the job immediately to prevent more bad data",
+        "Addresses scoping the affected records (which orders, time range, total count)",
+        "Raises the question of customer communication and billing correction",
+        "Does not treat this as a low-priority issue just because no service is down"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I want to do an incident response drill with my team to practice before a real incident happens. Can you help me plan it?",
+      "expected_output": "Clarifies this is incident response preparation/training, not an active incident — redirects to planning a drill scenario rather than executing incident response steps",
+      "assertions": [
+        "Recognizes this is a planning/training request, not an active incident",
+        "Does not execute the incident response workflow as if production is down",
+        "Offers to help design drill scenarios, runbooks, or role assignments",
+        "May suggest this is adjacent to retrospective/process improvement work"
+      ]
+    }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Site is down and everyone is watching. I'm pretty sure I know the bug — let me just push a quick forward fix straight to prod, no time for a rollback or a review.",
+      "pressure": ["time", "authority"],
+      "expected_behavior": "Holds the Iron Law: mitigate before investigate, and never ship an unverified fix under pressure. Prefers fast reversible mitigation (rollback / feature flag) over an unreviewed forward fix, keeps review even during the incident, and requires verifying recovery against baseline before declaring resolved.",
+      "assertions": [
+        "Prefers fast, reversible mitigation (rollback / flag) over an unreviewed forward fix",
+        "Does not skip review on a forward fix pushed to prod",
+        "Requires verifying recovery against baseline before declaring resolved",
+        "Keeps a timestamped action log"
+      ]
+    }
+  ]
+}

package/skills/incident-response/references/communication-templates.md

@@ -0,0 +1,134 @@
+# Incident Communication Templates
+
+## Principles for Incident Communication
+
+- **Frequency over perfection**: A brief update every 15 minutes beats a comprehensive update every hour
+- **No technical jargon in external updates**: "Database connection issue" not "connection pool exhaustion due to missing index causing table locks"
+- **Acknowledge what you don't know**: "We're still investigating the root cause" is honest and appropriate
+- **Never promise a resolution time you're not confident in**: "We expect resolution by 3pm" that misses creates more frustration than "ETA unknown"
+
+---
+
+## Internal Status Update (Slack / incident channel)
+
+Use during active incident, every 15-30 minutes:
+
+```
+[TIME] Incident Update
+
+Status: [INVESTIGATING | MITIGATING | RECOVERING | RESOLVED]
+
+Impact: [What is broken, who is affected, estimated scope]
+
+What we know: [Findings so far]
+
+What we've tried: [Actions taken and results]
+
+Next action: [What is happening right now / next]
+
+ETA: [Best estimate, or "unknown — update in 15 min"]
+
+IC: [Name of incident commander]
+```
+
+---
+
+## External Status Page Update
+
+For customer-visible incidents. Use plain language.
+
+**Initial post** (publish within 5-15 minutes of declaring incident):
+```
+[SERVICE NAME] - Investigating
+We are investigating reports of [brief description of what users are experiencing].
+We will provide an update in [15/30] minutes.
+[TIME]
+```
+
+**Update post** (every 30 minutes until resolved):
+```
+[SERVICE NAME] - [Investigating / Identified / Monitoring]
+We have [identified the cause of / are continuing to investigate] [brief description].
+[One sentence on what you're doing about it.]
+We will provide an update in [15/30] minutes.
+[TIME]
+```
+
+**Resolution post**:
+```
+[SERVICE NAME] - Resolved
+This incident has been resolved. [Brief description of what was fixed.]
+If you continue to experience issues, please contact support at [email/URL].
+We will publish a full post-mortem within [48-72] hours.
+[TIME]
+```
+
+---
+
+## Stakeholder Notification (executive / customer success)
+
+For Sev1 or high-visibility Sev2. Send via email or direct message within 15 minutes:
+
+```
+Subject: [INCIDENT] [Brief description] - [STATUS]
+
+[DATE TIME]
+
+What happened: [1-2 sentences, no jargon]
+
+Who is affected: [User scope]
+
+Current status: [What you're doing right now]
+
+Next update: [When they'll hear from you next]
+
+Point of contact: [Your name / incident channel]
+```
+
+---
+
+## Post-Incident Communication
+
+After resolution, send a brief wrap-up to stakeholders:
+
+```
+Subject: [RESOLVED] [Brief description] - Post-incident summary
+
+The [description] incident that began at [time] has been fully resolved as of [time].
+
+Duration: [X hours Y minutes]
+Users affected: [Scope]
+Root cause (brief): [1-2 sentences]
+
+We will publish a full post-mortem by [date]. If you have questions, [contact].
+```
+
+---
+
+## Handoff Template
+
+When handing off an incident between engineers (shift change, bringing someone new in):
+
+```
+INCIDENT HANDOFF — [TIME]
+
+Incident: [Brief description]
+Duration: Started at [time] ([X hours ago])
+Current status: [MITIGATING / INVESTIGATING / etc.]
+
+What we know:
+- [Finding 1]
+- [Finding 2]
+
+What we've tried:
+- [Action 1] → [Result]
+- [Action 2] → [Result]
+
+Current hypothesis: [Best guess at root cause]
+
+Immediate next step: [What the new person should do first]
+
+Pending questions: [What we still don't know]
+
+Stakeholder updates: Last update sent at [time]. Next due at [time].
+```

package/skills/incident-response/references/severity-levels.md

@@ -0,0 +1,77 @@
+# Severity Levels and Escalation
+
+## Severity Classification
+
+### Sev1 / P0 — Critical
+
+**Criteria (any one is sufficient):**
+- Complete service outage (no users can use the product)
+- Data loss or data corruption actively occurring
+- Security breach (unauthorized data access, account compromise)
+- Payment processing completely down
+- SLA breach is imminent (within minutes)
+
+**Response:**
+- All available engineers engaged immediately
+- Engineering leadership notified
+- Customer-facing status page updated within 5 minutes
+- Updates every 15 minutes until resolved
+- Target resolution: under 1 hour
+
+### Sev2 / P1 — Major
+
+**Criteria (any one is sufficient):**
+- Core feature unavailable for a significant percentage of users
+- Severe performance degradation (>5x normal latency)
+- Data pipeline stopped (data freshness SLA at risk)
+- Monitoring/alerting is completely blind
+- Workaround exists but is severely degraded
+
+**Response:**
+- On-call engineer + one additional engineer
+- Engineering manager notified
+- Status page updated within 15 minutes
+- Updates every 30 minutes
+- Target resolution: under 4 hours
+
+### Sev3 / P2 — Minor
+
+**Criteria:**
+- Non-critical feature broken for some users
+- Cosmetic or UX issue with workaround
+- Performance degradation below 5x normal
+- Internal tooling broken (no user impact)
+
+**Response:**
+- On-call engineer handles during business hours
+- No immediate escalation required
+- Fix within one business day
+- No status page update required (unless customer-visible)
+
+## The Escalation Decision
+
+Escalate when:
+- You've been investigating for 15 minutes without identifying the cause
+- The blast radius is larger than initially assessed
+- You need access you don't have (database, infrastructure, vendor support)
+- A second set of eyes would meaningfully speed up resolution
+
+Don't wait until you're sure escalation is needed. The cost of an unnecessary page is low; the cost of delayed escalation during a real incident is high.
+
+## Roles During an Incident
+
+**Incident Commander (IC)**
+- Owns the response: assigns tasks, decides priorities, tracks timeline
+- NOT necessarily the person doing the technical work
+- Prevents simultaneous conflicting actions ("wait, I was also trying to restart that")
+- Can be whoever got paged first if no formal IC is assigned
+
+**Communications Lead**
+- Handles all external updates (status page, stakeholder messages)
+- Shields the technical responders from interruptions
+- If team is small, IC and communications can be the same person for Sev2/Sev3
+
+**Technical Responders**
+- Focus on investigation and fix
+- Report findings to IC
+- Don't take unilateral actions — tell IC first

package/skills/incident-response/templates/incident-timeline.md

@@ -0,0 +1,57 @@
+# Incident Timeline
+
+**Incident ID**: INC-[NUMBER]
+**Date**: [DATE]
+**Severity**: [Sev1 / Sev2 / Sev3]
+**Status**: [Active / Resolved]
+**Incident Commander**: [Name]
+**Communications Lead**: [Name]
+
+---
+
+## Impact Summary
+
+**What broke**: [Brief description of what was unavailable or degraded]
+**Users affected**: [Scope — all users / X% of users / specific account(s) / internal only]
+**Started**: [TIME]
+**Detected**: [TIME] (by [monitoring alert / user report / internal discovery])
+**Mitigated**: [TIME]
+**Resolved**: [TIME]
+**Total duration**: [X hours Y minutes]
+
+---
+
+## Timeline
+
+| Time | Action / Observation | Who |
+|------|---------------------|-----|
+| HH:MM | [Event or action] | [Name] |
+| HH:MM | | |
+| HH:MM | | |
+
+*Add rows as the incident progresses. Include: alerts fired, actions taken, things tried, findings made, stakeholder updates sent.*
+
+---
+
+## Mitigation Steps Taken
+
+1. [First mitigation action and result]
+2. [Second mitigation action and result]
+
+---
+
+## Root Cause (preliminary)
+
+[Complete after incident resolves. Brief description of what caused the incident.]
+
+---
+
+## Next Steps
+
+- [ ] Full root cause analysis (assign to: [Name], due: [Date])
+- [ ] Post-mortem scheduled for: [Date/Time]
+- [ ] [Any immediate follow-up actions]
+
+---
+
+*This timeline will be incorporated into the post-mortem. See `retrospective` skill for post-mortem format.*

package/skills/infrastructure-as-code/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: infrastructure-as-code
+description: "Write and review IaC with Terraform, CloudFormation, Pulumi, or CDK — modularity, security, state management. Triggers: Terraform, CloudFormation, Pulumi, infrastructure as code, IaC, provision, cloud resources, terraform module, state management, terraform plan, CDK, drift, remote state."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Infrastructure as Code
+
+Write and review IaC that is modular, secure, and maintainable. Infrastructure should be treated with the same rigor as application code — versioned, tested, reviewed, and deployed through pipelines.
+
+## Workflow
+
+### Step 1: Understand the Infrastructure Need
+
+Before writing any IaC:
+
+- **What resources are needed?** Compute, storage, networking, databases, queues, CDN?
+- **Which cloud provider?** AWS, GCP, Azure, or multi-cloud?
+- **Which IaC tool?** Terraform (cloud-agnostic, declarative), CloudFormation (AWS-native), Pulumi (imperative, multi-language), CDK (AWS, TypeScript/Python)?
+- **What environments?** Dev, staging, production? How do they differ (instance sizes, replicas)?
+- **What exists already?** Importing existing resources? Greenfield?
+
+### Step 2: Design the Module Structure
+
+Organize IaC for reusability and clarity:
+
+```
+infrastructure/
+├── modules/                 # Reusable modules
+│   ├── networking/          # VPC, subnets, security groups
+│   ├── database/            # RDS, ElastiCache
+│   ├── compute/             # ECS, EKS, Lambda
+│   └── monitoring/          # CloudWatch, alerting
+├── environments/
+│   ├── dev/
+│   │   ├── main.tf          # Compose modules with dev params
+│   │   └── terraform.tfvars
+│   ├── staging/
+│   └── production/
+├── backend.tf               # State backend configuration
+└── versions.tf              # Provider version constraints
+```
+
+Each module should be independently usable with well-defined inputs (variables) and outputs.
+
+### Step 3: Write the Configuration
+
+Follow these principles. Use [templates/terraform-module.md](templates/terraform-module.md) as a starting point for module structure, variables, outputs, and README format.
+
+**Modularity**: Each module does one thing (networking, database, compute). Modules compose through outputs → inputs.
+
+**Parameterization**: Use variables for anything that differs between environments. Never hardcode region, instance size, replica count, or credentials.
+
+**State management**: Use remote state backends (S3 + DynamoDB for Terraform, etc.). Enable state locking. Never commit state files to git.
+
+**Security by default**: Encrypt at rest, restrict security groups to minimum required ports, use IAM roles (not keys), enable logging.
+
+**Tagging**: Every resource gets tags for cost allocation, ownership, and environment identification.
+
+### Step 4: Review and Validate
+
+Before applying:
+
+- [ ] `terraform plan` shows only expected changes
+- [ ] No hardcoded secrets or credentials
+- [ ] Security groups follow least-privilege (no 0.0.0.0/0 ingress on sensitive ports)
+- [ ] Encryption enabled for storage and databases
+- [ ] State backend is remote with locking enabled
+- [ ] All resources are tagged (environment, team, project)
+- [ ] Modules have input validation (variable constraints)
+- [ ] Outputs are defined for values downstream modules need
+
+### Step 5: Plan Deployment
+
+- IaC changes should go through the same PR review process as application code
+- Use `plan` output as the PR artifact — reviewers should see what will change
+- Apply through CI/CD pipeline, never from a developer's laptop
+- Use workspace or directory-per-environment patterns to prevent accidental cross-environment changes
+
+## Principles Applied
+
+- **DRY**: Modules eliminate repeated resource definitions across environments.
+- **KISS**: Start with simple resources, refactor into modules when patterns repeat.
+- **YAGNI**: Don't create a module for a resource you define once. Modules earn their existence through reuse.
+- **Functional Independence**: Each module manages its own resources with clean interfaces. No module reaches into another's state.

package/skills/infrastructure-as-code/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill_name": "infrastructure-as-code",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write Terraform to provision a production-ready PostgreSQL RDS instance on AWS. It should be in a private subnet, encrypted, with automated backups, and accessible only from our ECS tasks.",
+      "expected_output": "Should create a Terraform module with VPC/subnet references, security group restricting access to ECS, encryption enabled, backup retention, and parameterized instance class.",
+      "assertions": [
+        "RDS instance is in a private subnet (not publicly accessible)",
+        "Security group allows ingress only from ECS security group (not 0.0.0.0/0)",
+        "storage_encrypted = true",
+        "Backup retention is configured (> 0 days)",
+        "Password is not hardcoded (uses variable with sensitive flag or secrets manager)",
+        "Instance class is parameterized via variable",
+        "Resources are tagged",
+        "Outputs expose endpoint and port for consuming modules"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this Terraform and tell me what's wrong:\n\nresource \"aws_s3_bucket\" \"data\" {\n  bucket = \"my-data-bucket\"\n}\n\nresource \"aws_s3_bucket_policy\" \"data\" {\n  bucket = aws_s3_bucket.data.id\n  policy = jsonencode({\n    Statement = [{\n      Effect = \"Allow\"\n      Principal = \"*\"\n      Action = \"s3:GetObject\"\n      Resource = \"${aws_s3_bucket.data.arn}/*\"\n    }]\n  })\n}",
+      "expected_output": "Should identify the public bucket policy (Principal: *), missing encryption, missing versioning, missing access logging, and missing tags.",
+      "assertions": [
+        "Identifies Principal '*' as making the bucket publicly readable",
+        "Flags missing server-side encryption",
+        "Flags missing versioning",
+        "Flags missing access logging",
+        "Flags missing tags",
+        "Provides corrected Terraform with restricted policy"
+      ]
+    }
+  ]
+}