swe-workflow-skills 0.1.0

package/skills/infrastructure-as-code/references/iac-patterns.md

@@ -0,0 +1,179 @@
+# IaC Patterns
+
+## Contents
+- Terraform module pattern
+- State management patterns
+- Security patterns
+- Common anti-patterns
+
+## Terraform Module Pattern
+
+### Module structure
+```
+modules/database/
+├── main.tf          # Resource definitions
+├── variables.tf     # Input variables with descriptions and validation
+├── outputs.tf       # Output values for consumers
+├── versions.tf      # Required provider versions
+└── README.md        # Usage documentation
+```
+
+### Well-defined variables
+```hcl
+variable "instance_class" {
+  description = "RDS instance class"
+  type        = string
+  default     = "db.t3.micro"
+  validation {
+    condition     = can(regex("^db\\.", var.instance_class))
+    error_message = "Instance class must start with 'db.'"
+  }
+}
+
+variable "environment" {
+  description = "Deployment environment"
+  type        = string
+  validation {
+    condition     = contains(["dev", "staging", "production"], var.environment)
+    error_message = "Environment must be dev, staging, or production."
+  }
+}
+```
+
+### Consistent tagging
+```hcl
+locals {
+  common_tags = {
+    Environment = var.environment
+    Project     = var.project_name
+    ManagedBy   = "terraform"
+    Team        = var.team
+  }
+}
+
+resource "aws_db_instance" "main" {
+  # ... configuration ...
+  tags = merge(local.common_tags, {
+    Name = "${var.project_name}-${var.environment}-db"
+  })
+}
+```
+
+## State Management Patterns
+
+### Remote backend (Terraform + AWS)
+```hcl
+terraform {
+  backend "s3" {
+    bucket         = "mycompany-terraform-state"
+    key            = "environments/production/terraform.tfstate"
+    region         = "us-east-1"
+    dynamodb_table = "terraform-locks"
+    encrypt        = true
+  }
+}
+```
+
+Rules:
+- One state file per environment per component. Never share state across environments.
+- Enable encryption on the state bucket (state contains secrets).
+- Enable DynamoDB locking to prevent concurrent applies.
+- Enable versioning on the state bucket for recovery.
+- Never commit `.tfstate` files to git.
+
+### Environment separation
+```
+environments/
+├── dev/
+│   ├── main.tf           # module "db" { source = "../../modules/database" ... }
+│   └── terraform.tfvars  # instance_class = "db.t3.micro"
+├── staging/
+│   ├── main.tf
+│   └── terraform.tfvars  # instance_class = "db.t3.small"
+└── production/
+    ├── main.tf
+    └── terraform.tfvars  # instance_class = "db.r6g.large"
+```
+
+Each environment has its own state, its own tfvars, and composes the same modules with different parameters.
+
+## Security Patterns
+
+### Least-privilege security groups
+```hcl
+# GOOD: Specific port, specific source
+resource "aws_security_group_rule" "api_from_alb" {
+  type                     = "ingress"
+  from_port                = 3000
+  to_port                  = 3000
+  protocol                 = "tcp"
+  source_security_group_id = aws_security_group.alb.id
+  security_group_id        = aws_security_group.api.id
+}
+
+# BAD: Open to the world
+resource "aws_security_group_rule" "bad_example" {
+  type              = "ingress"
+  from_port         = 0
+  to_port           = 65535
+  protocol          = "-1"
+  cidr_blocks       = ["0.0.0.0/0"]  # Never do this
+  security_group_id = aws_security_group.api.id
+}
+```
+
+### Encryption by default
+```hcl
+resource "aws_db_instance" "main" {
+  storage_encrypted = true  # Always
+  # ...
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "main" {
+  bucket = aws_s3_bucket.main.id
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "aws:kms"
+    }
+  }
+}
+```
+
+### No hardcoded secrets
+```hcl
+# BAD
+resource "aws_db_instance" "main" {
+  password = "supersecret123"
+}
+
+# GOOD: Use a secrets manager or variable with sensitive flag
+variable "db_password" {
+  type      = string
+  sensitive = true
+}
+
+# BETTER: Generate and store in secrets manager
+resource "random_password" "db" {
+  length  = 32
+  special = true
+}
+
+resource "aws_secretsmanager_secret_version" "db" {
+  secret_id     = aws_secretsmanager_secret.db.id
+  secret_string = random_password.db.result
+}
+```
+
+## Common Anti-patterns
+
+**Mega-module**: One giant module that creates VPC + RDS + ECS + CloudFront. Split into focused, composable modules.
+
+**Hardcoded values**: Region, account ID, instance sizes baked into resource blocks. Use variables with validation.
+
+**No state locking**: Two engineers running `terraform apply` simultaneously can corrupt state. Always enable locking.
+
+**Local state**: State on someone's laptop means no collaboration and no recovery. Always use remote backends.
+
+**Apply from laptop**: Manual applies bypass code review and audit trails. Apply through CI/CD only. `terraform plan` locally for development, `terraform apply` through pipelines.
+
+**Ignoring plan output**: Applying without reading the plan. Always review what will be created, changed, or destroyed — especially in production.

package/skills/infrastructure-as-code/templates/terraform-module.md

@@ -0,0 +1,158 @@
+# Terraform Module Template
+
+Standard file structure for a reusable Terraform module. Copy and replace `<MODULE_NAME>`, `<RESOURCE_TYPE>`, and `<DESCRIPTION>` placeholders.
+
+---
+
+## File Structure
+
+```
+modules/<MODULE_NAME>/
+├── main.tf          # Resources
+├── variables.tf     # Inputs
+├── outputs.tf       # Outputs
+├── versions.tf      # Provider and Terraform version constraints
+└── README.md        # Usage, inputs, outputs table
+```
+
+---
+
+## versions.tf
+
+```hcl
+terraform {
+  required_version = ">= 1.6"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+```
+
+---
+
+## variables.tf
+
+```hcl
+variable "environment" {
+  description = "Deployment environment (dev, staging, production)"
+  type        = string
+  validation {
+    condition     = contains(["dev", "staging", "production"], var.environment)
+    error_message = "environment must be dev, staging, or production."
+  }
+}
+
+variable "name" {
+  description = "Base name for resources. Used in naming and tagging."
+  type        = string
+}
+
+variable "tags" {
+  description = "Additional tags to apply to all resources."
+  type        = map(string)
+  default     = {}
+}
+
+# Add module-specific variables below.
+# Pattern: description, type, optional default, optional validation.
+
+variable "instance_count" {
+  description = "Number of instances to provision."
+  type        = number
+  default     = 1
+  validation {
+    condition     = var.instance_count >= 1
+    error_message = "instance_count must be at least 1."
+  }
+}
+```
+
+---
+
+## main.tf
+
+```hcl
+locals {
+  # Merge caller tags with mandatory module tags
+  common_tags = merge(var.tags, {
+    Environment = var.environment
+    Module      = "<MODULE_NAME>"
+    ManagedBy   = "terraform"
+  })
+
+  name_prefix = "${var.name}-${var.environment}"
+}
+
+resource "aws_<RESOURCE_TYPE>" "main" {
+  # Use locals.name_prefix, never hardcode region or environment
+  # Use data sources (aws_vpc, aws_subnets) instead of hardcoding IDs
+
+  tags = local.common_tags
+}
+```
+
+> **Rules:** No hardcoded regions (`us-east-1`). No hardcoded account IDs. Use `data` sources for VPCs, subnets, AMIs. Use `local.common_tags` on every resource — cost attribution and compliance depend on it.
+
+---
+
+## outputs.tf
+
+```hcl
+output "id" {
+  description = "ID of the <RESOURCE_TYPE> resource."
+  value       = aws_<RESOURCE_TYPE>.main.id
+}
+
+output "arn" {
+  description = "ARN of the <RESOURCE_TYPE> resource."
+  value       = aws_<RESOURCE_TYPE>.main.arn
+}
+
+# Mark sensitive outputs appropriately
+output "connection_string" {
+  description = "Connection string for downstream modules."
+  value       = aws_<RESOURCE_TYPE>.main.endpoint
+  sensitive   = true
+}
+```
+
+---
+
+## README.md (Module)
+
+```markdown
+# <MODULE_NAME>
+
+<DESCRIPTION>
+
+## Usage
+
+```hcl
+module "<MODULE_NAME>" {
+  source = "../../modules/<MODULE_NAME>"
+
+  name        = "my-app"
+  environment = "production"
+  tags        = { Team = "platform", CostCenter = "infra" }
+}
+```
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|----------|
+| environment | Deployment environment | `string` | — | yes |
+| name | Base name for resources | `string` | — | yes |
+| tags | Additional tags | `map(string)` | `{}` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| id | Resource ID |
+| arn | Resource ARN |
+```

package/skills/metrics-and-okrs/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: metrics-and-okrs
+description: "Define OKRs, KPIs, success metrics, and engineering health metrics (DORA). Triggers: OKR, KPI, metrics, success metrics, key results, objectives, measure success, DORA metrics, engineering metrics, velocity, cycle time, deployment frequency, how do we measure, what should we track."
+model: haiku
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Metrics & OKRs
+
+Define meaningful metrics that drive decisions and OKRs that align engineering work with business outcomes. Good metrics answer "are we succeeding?" Bad metrics create busywork.
+
+## Core Rule
+
+**Every metric must drive a decision.** If knowing the metric's value wouldn't change what you do, stop tracking it. Metrics without decisions are vanity metrics.
+
+## Workflow: OKRs
+
+### Step 1: Understand the Context
+
+Before writing OKRs:
+
+- **What's the time horizon?** Quarterly is standard. Annual is too long for engineering.
+- **What level?** Company → Team → Individual? Start with team-level.
+- **What's the business priority?** Growth? Retention? Reliability? Cost reduction?
+- **What did we learn from last quarter?** What OKRs were hit, missed, and why?
+
+### Step 2: Write Objectives
+
+An Objective is a qualitative, inspiring goal that answers "where do we want to go?"
+
+**Good Objectives:**
+- "Make the checkout experience delightfully fast"
+- "Build a platform our enterprise customers trust"
+- "Eliminate the deployment bottleneck"
+
+**Bad Objectives:**
+- "Improve latency by 40%" (this is a Key Result, not an Objective)
+- "Complete the Q3 roadmap" (this is output, not outcome)
+- "Increase revenue" (too vague, not actionable by engineering)
+
+Rules: 3-5 objectives per team per quarter. Each should be ambitious but achievable. If you hit 100% of all OKRs, you aimed too low. 70% achievement is healthy.
+
+### Step 3: Write Key Results
+
+Key Results are quantitative measures that prove the Objective is being met.
+
+**Good Key Results:**
+- "Reduce checkout page load time from 3.2s to under 1.5s at P95"
+- "Achieve 99.95% API availability (up from 99.8%)"
+- "Reduce time from PR merge to production from 4 hours to 30 minutes"
+
+**Bad Key Results:**
+- "Launch the new checkout page" (this is output, not outcome)
+- "Improve performance" (not measurable)
+- "No production incidents" (not realistic and incentivizes hiding incidents)
+
+Each Objective should have 2-4 Key Results. Each Key Result needs:
+- **Current value** (baseline)
+- **Target value** (goal)
+- **How it's measured** (data source, calculation)
+
+### Step 4: Validate the OKRs
+
+Check each OKR against these criteria:
+- [ ] Is the Objective inspiring and clearly directional?
+- [ ] Are Key Results measurable with a specific number?
+- [ ] Can we actually measure this today? (If not, first KR might be "instrument X")
+- [ ] Do Key Results measure outcomes, not outputs?
+- [ ] Is 70% achievement of all KRs realistic with focused effort?
+- [ ] Are there perverse incentives? (Reducing errors by not logging them)
+
+### Step 5: Produce the OKR Document
+
+Use the template at [templates/okr-document.md](templates/okr-document.md).
+
+## Workflow: Project Success Metrics
+
+For any project or feature, define metrics in three categories:
+
+**Leading indicators** (early signals during development):
+- Sprint velocity, burndown trend, scope change rate
+- Test coverage of new code, CI pipeline pass rate
+
+**Lagging indicators** (results after launch):
+- User adoption (DAU, feature usage rate)
+- Performance metrics (latency, error rate, availability)
+- Business metrics (conversion rate, revenue, support ticket volume)
+
+**Health indicators** (ongoing system health):
+- DORA metrics (see below)
+- Technical debt metrics (code quality trends, dependency freshness)
+
+See [references/metric-catalog.md](references/metric-catalog.md) for a catalog of useful metrics by category.
+
+## Workflow: DORA Engineering Metrics
+
+The four DORA metrics are the industry standard for measuring engineering team effectiveness:
+
+| Metric | What It Measures | Elite | High | Medium | Low |
+|--------|-----------------|-------|------|--------|-----|
+| **Deployment Frequency** | How often you deploy | Multiple/day | Weekly | Monthly | Quarterly |
+| **Lead Time for Changes** | PR merge to production | < 1 hour | < 1 day | < 1 week | > 1 month |
+| **Change Failure Rate** | % of deploys causing incidents | < 5% | < 10% | < 15% | > 30% |
+| **Mean Time to Recover** | Incident to resolution | < 1 hour | < 1 day | < 1 week | > 1 month |
+
+These four metrics together tell you if your team is delivering quickly and reliably. Optimizing one at the expense of another is a trap (deploying fast but breaking things, or never breaking things but never shipping).
+
+## Principles Applied
+
+- **KISS**: 3-5 OKRs per team, 2-4 KRs each. More means none get attention.
+- **Outcomes over outputs**: Measure "user checkout time reduced" not "new checkout page shipped."
+- **YAGNI**: Don't build a metrics dashboard for 50 KPIs. Start with the 5 that would actually change a decision.
+- **Leading over lagging**: Prefer metrics you can act on now over metrics you can only measure after the fact.

package/skills/metrics-and-okrs/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill_name": "metrics-and-okrs",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write OKRs for our backend engineering team for Q2. Our priorities are: improve API reliability (we had 3 outages last quarter), reduce deployment friction (deploys take 4 hours), and ship the new billing system. Team of 6 engineers.",
+      "expected_output": "Should produce 3 objectives with 2-4 measurable key results each, using baselines where available, targeting realistic improvements, and flagging that 'ship billing system' needs to be reframed as an outcome.",
+      "assertions": [
+        "Frames objectives as inspiring goals, not tasks",
+        "Reframes 'ship billing system' as an outcome (e.g., 'billing accuracy' or 'customer billing complaints reduced')",
+        "Key results are measurable with specific numbers",
+        "Includes baseline values where the user provided data (outage count, deploy time)",
+        "Targets are ambitious but not absurd (not 'zero outages ever')",
+        "Reliability KRs use SLO-like framing (availability %, MTTR)",
+        "Deployment KRs use DORA metrics (lead time, frequency)",
+        "Produces a complete OKR document"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We launched a new search feature 2 weeks ago. My PM is asking 'how do we know if it's successful?'. Help me define the success metrics.",
+      "expected_output": "Should define leading and lagging indicators, distinguish between product metrics and technical metrics, and establish measurement timelines.",
+      "assertions": [
+        "Defines product metrics (search usage rate, click-through, zero-result rate)",
+        "Defines technical metrics (search latency, error rate)",
+        "Establishes baselines (what was the old search doing?)",
+        "Distinguishes leading (this week) from lagging (30 days) indicators",
+        "Suggests a timeframe for evaluation (not 'check once and declare victory')",
+        "Warns against vanity metrics (total searches without context is meaningless)"
+      ]
+    }
+  ]
+}

package/skills/metrics-and-okrs/references/metric-catalog.md

@@ -0,0 +1,90 @@
+# Metric Catalog
+
+## Contents
+- Product metrics
+- Engineering metrics
+- Reliability metrics
+- Business metrics
+- Anti-metrics (what NOT to measure)
+
+## Product Metrics
+
+| Metric | Formula | Good For |
+|--------|---------|----------|
+| Daily Active Users (DAU) | Unique users performing a core action / day | Growth tracking |
+| Feature Adoption Rate | Users who used feature / Total active users | Feature success |
+| Task Completion Rate | Successful completions / Attempts | UX quality |
+| Time to Value | Time from signup to first meaningful action | Onboarding quality |
+| Retention (Day N) | Users active on day N / Users who signed up N days ago | Product-market fit |
+| NPS | % Promoters - % Detractors | Customer satisfaction |
+| Churn Rate | Users lost / Total users (per period) | Retention health |
+
+## Engineering Metrics
+
+### DORA Metrics (team effectiveness)
+| Metric | How to Measure | Target |
+|--------|---------------|--------|
+| Deployment Frequency | Count deploys per week/day | Multiple per day (elite) |
+| Lead Time for Changes | Median time from commit to production | < 1 day |
+| Change Failure Rate | Deploys causing incidents / Total deploys | < 5% |
+| Mean Time to Recover | Median incident duration (detection → resolution) | < 1 hour |
+
+### Development Health
+| Metric | How to Measure | Warning Signal |
+|--------|---------------|----------------|
+| Cycle Time | Median time from "in progress" to "done" | Increasing over time |
+| PR Review Time | Median time from PR open to first review | > 24 hours |
+| PR Size | Median lines changed per PR | > 400 lines regularly |
+| Build Time | CI pipeline duration | > 15 minutes |
+| Test Coverage | Lines covered / Total lines (of new code) | Declining trend |
+| Flaky Test Rate | Tests with inconsistent results / Total tests | > 2% |
+| Dependency Freshness | Packages more than 1 major version behind | Increasing count |
+
+## Reliability Metrics
+
+| Metric | Formula | Typical SLO |
+|--------|---------|------------|
+| Availability | Successful requests / Total requests | 99.9% - 99.99% |
+| Latency (P50) | Median response time | < 200ms |
+| Latency (P99) | 99th percentile response time | < 1s |
+| Error Rate | 5xx responses / Total responses | < 0.1% |
+| Saturation | Resource utilization (CPU, memory, connections) | < 80% |
+| Error Budget Remaining | Budget consumed / Total budget | > 50% is healthy |
+
+## Business Metrics
+
+| Metric | Formula | Good For |
+|--------|---------|----------|
+| Revenue per Feature | Revenue attributable to a feature / Cost to build | ROI of features |
+| Cost per Transaction | Infrastructure cost / Number of transactions | Efficiency |
+| Support Ticket Volume | Tickets per feature area per week | Quality signal |
+| Time to Market | Idea to production for a typical feature | Organizational speed |
+
+## Anti-Metrics (What NOT to Measure)
+
+**Lines of Code**: More lines ≠ more value. Incentivizes bloat over simplicity.
+
+**Number of Commits**: More commits ≠ more productivity. Incentivizes tiny meaningless commits.
+
+**Story Points Completed (as individual performance)**: Points measure task size, not person performance. Using them for individual evaluation destroys team dynamics.
+
+**100% Test Coverage**: Incentivizes writing shallow tests to hit the number rather than meaningful tests for real behavior.
+
+**Bug Count (as a quality metric)**: More bugs found can mean better testing, not worse code. Punishing bug count discourages reporting.
+
+**Hours Worked**: Measures input, not output. Incentivizes presence over results.
+
+## Choosing the Right Metrics
+
+Ask three questions for every metric:
+
+1. **Does it drive a decision?** If the metric changes, would you do something differently? If not, stop tracking it.
+
+2. **Can it be gamed?** If someone optimizes purely for this metric, would the overall system get worse? If yes, add a counterbalancing metric.
+
+3. **Is it a leading or lagging indicator?** Leading indicators (cycle time, build time) let you act before problems grow. Lagging indicators (revenue, churn) tell you what already happened.
+
+For every primary metric, consider a counterbalance:
+- Deployment frequency ↔ Change failure rate (deploy fast BUT safely)
+- Feature velocity ↔ Support ticket volume (ship features BUT quality ones)
+- Cost reduction ↔ Performance metrics (reduce spend BUT maintain SLOs)

package/skills/metrics-and-okrs/templates/okr-document.md

@@ -0,0 +1,61 @@
+# OKR Document Template
+
+```markdown
+# OKRs: [Team Name] — [Quarter/Period]
+
+**Author**: [Name]
+**Period**: [Q1 2025 / Jan-Mar 2025]
+**Last updated**: [YYYY-MM-DD]
+
+---
+
+## Objective 1: [Inspiring qualitative goal]
+
+| Key Result | Baseline | Target | Current | Status |
+|-----------|----------|--------|---------|--------|
+| [Measurable outcome] | [Starting value] | [Goal value] | [Now] | 🟢🟡🔴 |
+| [Measurable outcome] | [Starting value] | [Goal value] | [Now] | 🟢🟡🔴 |
+| [Measurable outcome] | [Starting value] | [Goal value] | [Now] | 🟢🟡🔴 |
+
+**How measured**: [Data source, dashboard link, calculation method]
+**Owner**: [Person accountable for driving this objective]
+
+---
+
+## Objective 2: [Inspiring qualitative goal]
+
+| Key Result | Baseline | Target | Current | Status |
+|-----------|----------|--------|---------|--------|
+| [Measurable outcome] | [Starting value] | [Goal value] | [Now] | 🟢🟡🔴 |
+| [Measurable outcome] | [Starting value] | [Goal value] | [Now] | 🟢🟡🔴 |
+
+**How measured**: [Data source]
+**Owner**: [Person]
+
+---
+
+## Objective 3: [Inspiring qualitative goal]
+
+| Key Result | Baseline | Target | Current | Status |
+|-----------|----------|--------|---------|--------|
+| [Measurable outcome] | [Starting value] | [Goal value] | [Now] | 🟢🟡🔴 |
+| [Measurable outcome] | [Starting value] | [Goal value] | [Now] | 🟢🟡🔴 |
+
+**How measured**: [Data source]
+**Owner**: [Person]
+
+---
+
+## Status Key
+
+- 🟢 On track (≥ 70% of target)
+- 🟡 At risk (40-70% of target)
+- 🔴 Off track (< 40% of target)
+
+## End-of-Quarter Review
+
+**Overall score**: [0-1.0 average across all KRs]
+**Key wins**: [What went well]
+**Key misses**: [What didn't work and why]
+**Learnings for next quarter**: [What to carry forward]
+```