swe-workflow-skills 0.1.0 → 0.2.0

package/skills/data-quality/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: data-quality
+description: "Keep warehouse and pipeline data trustworthy — dbt tests, expectations (Great Expectations/Soda), data contracts with upstream producers, source freshness, schema-drift and volume anomaly detection, lineage and blast radius, severity and alerting. Triggers: data quality, bad data in dashboards, data validation, dbt tests, data contract, schema drift, stale data, freshness check, duplicate rows, nulls in the warehouse, data lineage, data SLA, upstream schema change broke us. Generating test/synthetic data → test-data-strategy; schema design → data-modeling."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Data Quality
+
+Make bad data **loud**: caught at the boundary where it enters, blocking what
+must not ship, alerting someone who owns the fix — instead of being discovered
+by a stakeholder in a dashboard. Boundaries: *generating* fake/test data is
+`test-data-strategy`; *designing* the schema is `data-modeling`; this skill
+keeps the real data flowing through pipelines trustworthy.
+
+## Workflow
+
+### Step 1: Start From Incidents, Not Inventory
+
+Don't blanket every column with tests. List the recent data incidents (wrong
+dashboard numbers, silent breakage) and the tables where an error costs real
+money or trust — revenue marts, ML features, anything an exec reads. Each
+known symptom maps to a check: nulls → `not_null`, duplicates → `unique`,
+staleness → freshness, broken joins → `relationships`. Wins from day one, and
+the suite grows the same way tests do after bugs — every new incident adds a
+check that would have caught it.
+
+### Step 2: Check at the Right Layer — Boundary First
+
+Where a check runs matters as much as what it checks:
+
+- **Ingestion boundary (sources)**: schema, freshness, volume, primary-key
+  integrity — catch bad inputs *before* transforms consume them. One failed
+  source check beats fifty downstream test failures at 6 a.m.
+- **Transform layers (staging → marts)**: uniqueness/not-null on the grain of
+  each model, relationship tests on joins, accepted values on enums.
+- **Consumer edge (marts/metrics)**: business-rule assertions — "revenue is
+  never negative", "row count within N% of the 7-day average".
+
+In dbt this is: source `freshness` + source tests, generic tests on models
+(`unique`, `not_null`, `relationships`, `accepted_values`), singular SQL tests
+for business rules. Dedicated tools (Great Expectations, Soda) earn their keep
+outside dbt-land or when non-engineers must own the rules:
+[references/tooling.md](references/tooling.md).
+
+### Step 3: Assign Severity — What Blocks vs What Warns
+
+A suite where everything fails the build gets muted within a month; a suite
+where nothing blocks is decoration. Decide per check:
+
+- **error** — data is unusable or contaminating (duplicate keys in a revenue
+  mart, failed contract at ingestion): the pipeline stops, downstream models
+  don't build on poisoned input.
+- **warn** — degraded but usable (slightly stale, volume dip within reason):
+  alert, keep flowing.
+
+dbt: `severity:` config with `error_if`/`warn_if` thresholds. Revisit
+severities after each incident and each false alarm.
+
+### Step 4: Route Failures to an Owner
+
+A failing check nobody sees is identical to no check. Every table (or domain)
+has a named owner; alerts go where that owner works (Slack channel per domain,
+pager only for `error`-severity on critical marts), and each alert says what
+failed, on which table, and the blast radius (Step 5). Track
+time-to-detection and time-to-fix for data incidents — that's the metric this
+whole skill improves (`observability-design` for the SLO framing).
+
+### Step 5: Use Lineage to Scope Blast Radius
+
+When a check fails, the first question is "what downstream is now wrong?" —
+lineage (dbt's DAG, `dbt ls --select my_model+`, or a catalog tool) answers
+which models, dashboards, and consumers sit downstream of the failure. Use it
+to: prioritize fixes by consumer impact, notify affected dashboard owners
+proactively, and decide what to rebuild after the fix. If you can't answer
+"what breaks if this table is wrong?", invest in lineage before more checks.
+
+### Step 6: Contract the Upstream Boundary
+
+Downstream tests detect what upstream producers break; **contracts prevent
+it.** When an external team owns the source: agree schema + semantics + SLA
+explicitly (a versioned artifact — dbt model contracts, JSON Schema/protobuf in
+a registry), enforce at ingestion so violations fail loudly at entry, and shift
+left — contract validation in the *producer's* CI, so a breaking rename fails
+their build, not your 6 a.m. run. Breaking changes get a version bump and a
+deprecation window, coordinated like an API change
+(`dependency-impact-analysis` thinking, applied to data). Back it with
+schema-drift detection and volume/distribution anomaly checks for what
+enforcement can't see.
+
+## Principles Applied
+
+- **YAGNI**: checks earn their place by a failure mode you've seen or can't
+  afford — blanket-testing every column produces alert fatigue, the failure
+  mode that kills quality programs.
+- **Fail loudly at the boundary**: the cost of bad data grows with every layer
+  it flows through undetected.
+- **DRY**: one contract at the source replaces N teams' defensive checks
+  against the same breakage.
+
+## Cross-Skill References
+
+- `data-pipeline-design` — the pipeline these checks are embedded in
+- `data-modeling` — constraints and grain the checks assert (unique keys exist by design)
+- `test-data-strategy` — generating synthetic/fixture data for testing pipelines
+- `observability-design` — alerting design, SLOs, avoiding alert fatigue
+- `incident-response` — when bad data has already reached production consumers

package/skills/data-quality/evals/evals.json

@@ -0,0 +1,39 @@
+{
+  "skill_name": "data-quality",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Stakeholders keep finding bad numbers in our dashboards — null customer IDs, duplicated orders, and data that's a day stale. We're on dbt + Snowflake. Set up data quality checks.",
+      "expected_output": "Maps each symptom to a concrete check (not_null/unique dbt tests, source freshness), places checks at the ingestion boundary first and critical marts second, assigns severity (error blocks, warn alerts), routes failures to an owner, and uses lineage to scope which downstream models and dashboards a failure affects",
+      "assertions": [
+        "Maps each reported symptom to a concrete check: not_null/unique dbt tests for the IDs and duplicates, and source freshness checks for the staleness",
+        "Places checks at the right layers: the source/ingestion boundary first, then critical marts — not only on the final dashboards",
+        "Assigns severity levels (error vs warn) and defines what blocks the pipeline versus what only alerts",
+        "Sets up alerting and ownership so failures reach someone who acts, instead of failing silently",
+        "Uses lineage to scope blast radius — which downstream models or dashboards a failing check affects"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "An upstream team owns the events we ingest and keeps renaming columns and changing types without telling us. Our pipeline breaks silently every few weeks. What should we put in place?",
+      "expected_output": "Proposes a producer/consumer data contract (schema, types, semantics, SLA) enforced at the ingestion boundary so violations fail loudly at entry; shifts validation left into the producer's CI or publish path; adds versioning/deprecation windows for breaking changes; and backstops enforcement with schema-drift and volume/distribution anomaly detection",
+      "assertions": [
+        "Proposes an explicit data contract between producer and consumer (schema, types, semantics, SLAs), not just more downstream tests",
+        "Enforces the schema at the ingestion boundary so violations fail loudly at entry instead of propagating silently",
+        "Shifts checks left: contract validation in the producer's CI or at publish time",
+        "Covers change management for breaking changes: contract versioning or a deprecation window",
+        "Adds detection for what enforcement misses: schema-drift alerts or anomaly checks on volume/distributions"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We need realistic but fake customer data to seed staging so QA can test the checkout flow — GDPR means we can't copy production.",
+      "expected_output": "Recognizes this as generating synthetic/test data, not validating production data — hands off to test-data-strategy (factories, synthetic generation, anonymization) rather than proposing expectations, contracts, or freshness checks",
+      "assertions": [
+        "Recognizes this is about generating test/synthetic data, not validating production data quality",
+        "Refers to the test-data-strategy skill for factories, synthetic data generation, and GDPR-safe anonymization",
+        "Does not answer with data-quality machinery (expectations, contracts, freshness checks) as the solution"
+      ]
+    }
+  ]
+}

package/skills/data-quality/references/tooling.md

@@ -0,0 +1,45 @@
+# Data Quality Tooling — Selection Notes
+
+Tool capabilities shift quickly; verify against current docs. The placement
+logic is stable.
+
+## Picking the enforcement layer
+
+| Tool | Shape | Choose when |
+|---|---|---|
+| **dbt tests** | YAML generic tests + singular SQL tests, run with the transforms | You're already on dbt. Zero new infrastructure; tests version with the models; severity/thresholds built in. The default. |
+| **dbt model contracts** | Enforced column names/types on a model; breaks the *producer's* build | A dbt model is consumed across team boundaries — the contract fails the producing project's CI, which is the shift-left goal. |
+| **Great Expectations** | Python expectation suites + data docs, runs anywhere | Checks must run outside the warehouse/dbt (files, in-flight DataFrames, non-dbt pipelines), or you need its rich expectation vocabulary and generated documentation. Heavier to operate. |
+| **Soda (Core/Cloud)** | Declarative checks YAML (SodaCL), CLI + SaaS | Non-engineers own quality rules, or checks span multiple stores with one syntax; Cloud adds anomaly detection and incident routing. |
+| **Elementary / observability platforms (Monte Carlo, Metaplane…)** | Monitor the warehouse from metadata: freshness, volume, schema drift, distribution anomalies | You want detection you didn't hand-write — anomaly monitoring across many tables — and (platforms) column-level lineage + incident management. Elementary is the dbt-native OSS entry point. |
+
+Layering that works in practice: **dbt tests + source freshness** as the
+foundation; **contracts** at team boundaries; **one anomaly/observability
+layer** for the unknown-unknowns. Adding a second tool in the same layer buys
+maintenance, not coverage.
+
+## Contract mechanics by boundary type
+
+- **Event streams**: schema registry (Avro/Protobuf/JSON Schema) with
+  compatibility mode set (backward at minimum); producers can't publish a
+  breaking schema. The strongest enforcement available — use it if events are
+  the interface.
+- **Warehouse-to-warehouse (dbt ↔ dbt)**: dbt model contracts + versioned
+  models (`v2` with a deprecation window) on the shared models.
+- **API/file drops from another org**: JSON Schema validated at ingestion;
+  reject-and-alert (dead-letter the bad batch) rather than best-effort
+  parsing.
+- The social half matters as much: a named producer contact, a change-notice
+  channel, and the contract in a repo both teams can PR.
+
+## Anomaly checks worth having before "ML-powered" anything
+
+- Row count vs trailing 7/28-day window (volume drops are the most common
+  silent failure).
+- Freshness vs declared SLA per source.
+- Schema diff vs last run (added/removed/retyped columns) with an explicit
+  allowlist flow.
+- Null-rate and distinct-count drift on business-critical columns.
+
+These four catch the large majority of real incidents; statistical/ML anomaly
+detection is a refinement, not a starting point.

package/skills/deployment-checklist/SKILL.md

@@ -69,7 +69,7 @@ Walk through each section. Check items by reading code, running commands, and ve
 #### Documentation
 - [ ] README updated if setup steps changed
 - [ ] API documentation updated for new/changed endpoints
-- [ ] CHANGELOG updated (if project uses one)
+- [ ] Release cut correctly, if this deploy ships one — version, changelog, tag consistent (see `release-management`)
 - [ ] Breaking changes are clearly communicated
 
 ### Step 3: Report
@@ -126,6 +126,7 @@ See [references/pre-deploy-gates.md](references/pre-deploy-gates.md) for environ
 
 ## Cross-Skill References
 
+- `release-management` — cutting the versioned release (semver, changelog, tag, publish) that this checklist deploys
 - `rollback-strategy` — design the rollback plan before deploying (required for High-risk changes)
 - `configuration-strategy` — verify all environment variables and feature flags are configured correctly
 - `incident-response` — use if the deployment causes a production incident

package/skills/dx-audit/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: dx-audit
+description: "Audit and improve developer experience — inner-loop feedback (build/test/reload times), CI wait and queue times, flaky tests, local environment setup, onboarding time-to-first-PR, tooling friction, docs discoverability; produce a prioritized remediation plan. Triggers: developer experience, DX audit, devex, builds are slow, CI takes forever, flaky tests, onboarding takes weeks, tooling friction, developer productivity, engineers are frustrated. Code health/debt hotspots → technical-debt-review; designing one pipeline → cicd-pipeline."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# DX Audit
+
+Find and fix the friction that taxes every engineer, every day. Developer
+experience compounds: a 10-minute CI queue on a 20-person team burns weeks of
+engineering time per month, and worse, it changes *behavior* — engineers batch
+changes, skip test runs, and avoid touching areas with slow feedback.
+Boundary: `technical-debt-review` audits the *code's* health; this skill audits
+the *workflow around* the code — loops, tooling, environments, and onboarding.
+
+## Workflow
+
+### Step 1: Measure the Loops — Numbers Before Anecdotes
+
+Quantify the feedback loops before collecting opinions, so the audit ranks by
+data and the improvement is provable later:
+
+- **Inner loop**: cold build, incremental build, single-test run, hot-reload —
+  time them yourself in the actual repo.
+- **Outer loop**: CI wall-clock (queue + run, from real recent pipelines), PR
+  time-to-first-review and time-to-merge, deploy lead time (DORA overlap —
+  `metrics-and-okrs`).
+- **Flake rate**: retries and "re-run job" clicks per week; a 5%-flaky suite
+  means engineers already ignore red.
+- **Onboarding**: time from laptop to first merged PR for recent joiners.
+
+### Step 2: Collect the Friction Log
+
+Then ask the engineers — a lightweight survey or five 15-minute conversations:
+"what wastes your time every day?", "what do you avoid doing because it's
+painful?", "what would you fix first?". The second question matters most:
+avoidance signals (never running the full suite locally, dreading a service's
+local setup, batching deploys) reveal costs the timers can't see. Recurring
+themes + Step-1 numbers = the finding list.
+
+### Step 3: Audit the Inner Loop
+
+The highest-frequency loop gets the deepest look: Is the dev environment
+reproducible in one command (or is setup a wiki page of drift-prone steps)?
+Can you run one test in seconds without the world? Does hot-reload actually
+work? Is the IDE experience functional (types, go-to-def, lint-on-save)? Are
+common tasks (reset DB, seed data, run service X) scripted or tribal
+knowledge? Every manual step here multiplies by invocations-per-day.
+
+### Step 4: Audit the Outer Loop
+
+- **CI**: queue time vs run time (capacity vs speed problems differ), cache
+  hit rates, test parallelization/sharding, whether PRs run only affected
+  targets — delegate pipeline redesign to `cicd-pipeline`.
+- **Flakes**: quarantine policy (a flaky test in the merge gate is a tax on
+  everyone), ownership for fixing, `test-suite-design` for structural causes.
+- **Review latency**: are PRs waiting on people or on process (required
+  approvals, codeowner bottlenecks)?
+- **Docs**: can an engineer answer "how do I X here?" without interrupting a
+  senior — README freshness, runbooks, `project-documentation`.
+
+### Step 5: Prioritize by Tax, Not by Annoyance
+
+Score each finding as **time-cost × frequency × people affected** (daily
+10-second cuts beat monthly 10-minute ones), weighted by behavior distortion
+(anything that makes engineers *skip verification* is top-tier regardless of
+seconds). Produce the remediation list: quick wins first (cache config, test
+sharding, a `make dev` script) to build credibility, structural items
+(environment overhaul, CI capacity) as scheduled work with owners.
+
+### Step 6: Prove It and Keep It
+
+Re-measure the Step-1 numbers after the fixes — DX work is uniquely easy to
+verify, so verify it. Then keep the loop honest: track 2–3 DX metrics
+continuously (CI p50/p95, flake rate, onboarding time), set a budget
+("CI > 10 min is a defect"), and re-run the friction survey a couple of times
+a year. DX decays by default — every new service adds setup steps and CI
+minutes unless something pushes back.
+
+## Principles Applied
+
+- **Frequency beats magnitude**: optimize the loop that runs 50×/day before
+  the one that runs weekly.
+- **Avoidance is the loudest signal**: what engineers won't do reveals more
+  than what they complain about.
+- **Measured before and after**: a DX improvement that can't show the numbers
+  moved is an opinion.
+
+## Cross-Skill References
+
+- `technical-debt-review` — the code-health complement to this workflow audit
+- `cicd-pipeline` — redesigning the pipeline the audit flagged
+- `test-suite-design` — structural fixes for slow or flaky suites
+- `project-documentation` — the docs/onboarding gaps surfaced in Step 4
+- `metrics-and-okrs` — DORA metrics and making DX goals measurable
+- `retrospective` — mining recurring friction from team retros

package/skills/dx-audit/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "dx-audit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our 25-person engineering team feels slow. CI takes ~35 minutes, people complain about local setup, and new hires seem to take forever to become productive. Run a DX audit and tell us what to fix.",
+      "expected_output": "Measures the loops first (inner-loop timings, CI queue vs run time, flake rate, PR cycle time, onboarding time-to-first-merge), collects a friction log from engineers with attention to avoidance behavior, audits inner loop (one-command env, single-test speed) and outer loop (CI caching/sharding, flake quarantine, review latency, docs), prioritizes by time-cost × frequency × people with quick wins first, and commits to re-measuring the same numbers after fixes",
+      "assertions": [
+        "Quantifies the feedback loops with real measurements (build/test times, CI queue vs run, flake rate, PR cycle, onboarding time) before prescribing fixes",
+        "Collects friction from the engineers themselves (survey/interviews) and pays attention to avoidance behavior, not just complaints",
+        "Audits both the inner loop (env setup, single-test runs, hot reload, scripted common tasks) and the outer loop (CI caching/parallelization, flaky-test policy, review latency, docs)",
+        "Prioritizes findings by frequency × time-cost × people affected, sequencing quick wins before structural work, with owners",
+        "Plans to re-measure the baseline numbers after remediation and keep 2–3 DX metrics tracked continuously"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Management says our DX is fine because nobody's complaining, but I notice engineers never run the full test suite locally, deploys pile up on Fridays, and everyone SSHes into a shared staging box to test things. Is there a DX problem here?",
+      "expected_output": "Reads the avoidance signals as the loudest DX evidence: skipping the local suite implies it's too slow/flaky (verification is being skipped — top-tier severity), deploy batching implies the deploy loop is painful or risky, shared-staging testing implies local environments can't reproduce reality; quantifies each to confirm, and explains why absence of complaints doesn't mean absence of tax (normalized friction becomes invisible)",
+      "assertions": [
+        "Identifies the described behaviors as avoidance signals that indicate DX problems despite the absence of complaints",
+        "Infers the likely underlying causes: local suite too slow or flaky, painful/risky deploy loop, local environments unable to reproduce reality",
+        "Flags that engineers skipping verification (not running tests locally) is especially severe because it distorts quality behavior",
+        "Proposes measuring to confirm (suite runtime, flake rate, deploy lead time, env setup) rather than acting on inference alone",
+        "Explains why normalized friction stops generating complaints (habituation), so surveys must ask about avoidance, not just satisfaction"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our checkout module is a nightmare of spaghetti code — cyclomatic complexity through the roof, no tests, God classes everywhere. Audit it and give us a prioritized cleanup roadmap.",
+      "expected_output": "Recognizes this as a code-health/debt assessment, not a workflow-friction audit — refers to technical-debt-review for the hotspot analysis and remediation roadmap, stating the boundary: dx-audit covers the workflow around the code (loops, tooling, environments); technical-debt-review covers the code itself",
+      "assertions": [
+        "Recognizes the request as a code-health/technical-debt assessment, not a developer-workflow audit",
+        "Refers to the technical-debt-review skill for the hotspot analysis and cleanup roadmap",
+        "Does not produce a DX workflow audit (CI timings, onboarding, tooling friction) as the answer",
+        "States or implies the boundary: dx-audit audits the workflow around the code; technical-debt-review audits the code's health"
+      ]
+    }
+  ]
+}

package/skills/feature-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-planning
-description: "Break features into well-scoped tasks with acceptance criteria, risk assessment, and dependency mapping. Triggers: plan this, break this down, scope this feature, create tasks for, sprint planning, how should I implement this feature, user stories, acceptance criteria, dependency mapping, feature breakdown."
+description: "Break features into well-scoped tasks with acceptance criteria, risk assessment, and dependency mapping. Triggers: plan this, break this down, scope this feature, create tasks for, sprint planning, how should I implement this feature, user stories, acceptance criteria, dependency mapping, feature breakdown. Creates the plan — executing an already-approved plan checkpoint by checkpoint → plan-execution."
 model: sonnet
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
@@ -82,3 +82,7 @@ Output the complete plan using the template at [templates/plan.md](templates/pla
 If the feature involves architectural decisions (new services, database changes, API design), suggest using the `architecture-design` skill before finalizing the plan.
 
 If the feature requires data model changes, suggest using the `data-modeling` skill for that portion.
+
+If the idea itself is still fuzzy — the user is exploring what to build rather than how — run `brainstorming` first; this skill converges, that one diverges.
+
+Once the plan is approved and execution begins, the `plan-execution` skill takes over: checkpointed batches, verification evidence per checkpoint, and drift-triggered re-planning (which loops back here).

package/skills/finops-cost-optimization/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: finops-cost-optimization
+description: "Understand and reduce cloud spend — cost visibility and allocation (tagging, ownership), unit economics, rightsizing, autoscaling, commitment discounts (reserved instances, savings plans), storage/egress traps, architecture cost review, budgets and anomaly alerts. Triggers: cloud costs, AWS bill, cut costs, cost optimization, FinOps, why is our bill so high, rightsizing, reserved instances, savings plan, egress fees, cost per customer. Whether to build or buy a capability → build-vs-buy; making code faster → performance-optimization."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash, WebFetch, WebSearch
+---
+
+# FinOps & Cost Optimization
+
+Treat cloud cost as an engineering metric — observable, attributed, and
+optimized with the same rigor as latency. The failure mode this skill counters:
+nobody owns the bill, so it only gets attention as a quarterly surprise, and
+the response is a panicked freeze instead of systematic reduction. Boundaries:
+`performance-optimization` makes code faster (sometimes cheaper as a side
+effect); `build-vs-buy` decides whether to run the capability at all; this
+skill optimizes what you *do* run.
+
+## Workflow
+
+### Step 1: Visibility Before Optimization
+
+You can't cut what you can't attribute. Establish first:
+
+- **Allocation**: tag/label resources by service, team, and environment;
+  measure the untagged remainder and drive it down — an 40%-unattributed bill
+  makes every later step guesswork.
+- **The big rocks**: rank spend by service and by resource type. Cloud bills
+  follow a power law; the top 5 line items usually carry most of the total.
+  Optimizing anything outside them is procrastination with charts.
+- **Trend vs events**: is spend growing with usage (fine, if unit costs hold),
+  or did it step-change with a deploy (an incident with a dollar signature)?
+
+Pull real billing data (cost explorer exports, `infracost` on IaC diffs, the
+provider CLIs) — never optimize from memory of last quarter's bill.
+
+### Step 2: Define Unit Economics
+
+Total spend is noise; **cost per unit of value** — per customer, per request,
+per GB processed, per model inference — is signal. A bill that doubles while
+customers triple is a win. Pick 1–3 unit metrics with the team, compute them
+from the Step-1 allocation, and make them the number optimization is judged by.
+This is also what connects engineering to the business conversation
+(`metrics-and-okrs`).
+
+### Step 3: Harvest the Waste (no architecture changes)
+
+The reliable first wins, in typical order of return:
+
+- **Orphans**: unattached volumes/IPs, forgotten environments, snapshots-forever,
+  idle dev clusters running nights and weekends (schedule them off).
+- **Rightsizing**: instances/databases provisioned for imagined peak — check
+  actual utilization (single-digit CPU on a large instance is a purchase order
+  for the cloud provider, not capacity planning).
+- **Storage classes & lifecycle**: hot-tier data nobody has read in a year;
+  logs and backups with no expiry — lifecycle policies are one-line fixes.
+- **Non-prod parity**: staging doesn't need production's instance sizes,
+  replica counts, or retention.
+
+### Step 4: Buy Commitment for the Stable Baseline
+
+After rightsizing (never before — you'd lock in the waste): cover the stable,
+predictable baseline with reserved instances / savings plans / committed-use
+discounts, and keep the spiky remainder on-demand or spot (spot for
+interruption-tolerant work: batch, CI, stateless workers). Start conservative
+(cover well under 100% of the baseline) and ratchet up as forecasts prove out —
+over-commitment converts a variable cost into a fixed regret.
+
+### Step 5: Review the Architecture's Cost Shape
+
+Some spend is structural, and only architecture changes move it:
+
+- **Egress and cross-zone/region chatter** — the classic invisible line item;
+  co-locate chatty services, cache at the edge, compress.
+- **Per-invocation pricing at scale** — serverless that grew past the
+  crossover where instances are cheaper (and vice versa: idle instances that
+  should be serverless).
+- **Managed-premium vs ops-burden** — the managed service's markup is often
+  worth it (that's a `build-vs-buy` call when it gets big).
+- **Data pipelines** — scan-based pricing (warehouse queries over unpartitioned
+  tables) and always-on streaming for hourly-batch needs (`data-pipeline-design`).
+
+Cost these with current provider pricing (verify live — pricing changes), and
+record significant trade-offs as ADRs (`architecture-design`).
+
+### Step 6: Keep It Continuous
+
+- **Budgets + anomaly alerts** per team/service, routed to the owning team —
+  a cost regression is a defect, detected in days not quarters.
+- **Cost in the deploy loop**: IaC cost diffs (e.g. infracost) in PRs makes
+  cost visible at decision time.
+- **A monthly 30-minute review** of the unit metrics and top movers beats an
+  annual cost-cutting project.
+
+## Principles Applied
+
+- **Attribution before optimization** — unowned costs never stay cut.
+- **Unit economics over totals** — growth should raise the bill; only rising
+  *unit* cost is a problem.
+- **Biggest line item first** — a 10% cut of the top item beats a 90% cut of
+  the tenth.
+
+## Cross-Skill References
+
+- `build-vs-buy` — whether to run the capability at all; managed-vs-self-hosted TCO
+- `performance-optimization` — efficiency work that reduces compute per request
+- `architecture-design` — recording cost-driven structural decisions as ADRs
+- `observability-design` — the metrics/alerting machinery cost signals ride on
+- `data-pipeline-design` — cost-shaping batch/streaming and warehouse workloads
+- `metrics-and-okrs` — tying unit economics to business metrics

package/skills/finops-cost-optimization/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "finops-cost-optimization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our AWS bill jumped from $18k to $31k/month over the last two quarters and leadership wants it 'fixed'. Where do we start?",
+      "expected_output": "Starts with visibility, not cuts: attribute the spend (tagging/allocation), rank the top line items, and separate usage-driven growth from step-change regressions; defines unit economics (cost per customer/request) as the real judge; then harvests waste in order of return (orphans, rightsizing from actual utilization, storage lifecycle, non-prod schedules), only then commitment discounts on the post-rightsizing baseline, plus budgets/anomaly alerts so the next jump is caught in days",
+      "assertions": [
+        "Establishes visibility and attribution first (tagging/allocation, ranking top line items from real billing data) before proposing any cuts",
+        "Distinguishes usage-driven growth from step-change regressions and/or introduces unit economics (cost per customer/request) rather than treating the total as the metric",
+        "Proposes concrete waste harvesting: orphaned resources, rightsizing based on actual utilization, storage lifecycle policies, or scheduling non-prod environments off",
+        "Recommends commitment discounts (RIs/savings plans) only after rightsizing, covering a conservative stable baseline",
+        "Sets up continuous guardrails: budgets and anomaly alerts routed to owning teams, and/or cost checks in the deploy loop"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our bill is dominated by data transfer: about 40% is inter-AZ traffic and NAT gateway charges between our microservices, and the rest of the top items are a Kafka cluster and a data warehouse where queries scan whole tables. Rightsizing won't move these. What are our options?",
+      "expected_output": "Recognizes structural/architectural cost shape: co-locating chatty services or reworking cross-AZ topology (weighing the availability trade-off), VPC endpoints / NAT alternatives, compression; warehouse scan costs via partitioning/clustering and incremental models; evaluates whether always-on streaming matches the actual latency need; recommends costing options with live pricing and recording the trade-offs as ADRs since these decisions trade resilience/latency for money",
+      "assertions": [
+        "Recognizes these as architecture-shaped costs that rightsizing cannot fix and addresses the egress/inter-AZ problem specifically (co-location, topology, VPC endpoints, compression)",
+        "Notes the availability/resilience trade-off in reducing cross-AZ traffic rather than recommending single-AZ blindly",
+        "Addresses the warehouse scan costs structurally (partitioning, clustering, incremental models) rather than only suggesting fewer queries",
+        "Questions whether the always-on streaming infrastructure matches the actual latency requirement (batch vs streaming)",
+        "Recommends verifying costs against current provider pricing and/or recording significant cost-driven decisions as ADRs"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our checkout API's p99 latency is 4 seconds and profiling shows an N+1 query pattern plus a missing index. Can you help optimize it?",
+      "expected_output": "Recognizes this as code/query performance work, not cloud-spend optimization — refers to performance-optimization for the N+1 and indexing work, noting the boundary: performance-optimization makes code faster (sometimes cheaper as a side effect); finops-cost-optimization attributes and reduces cloud spend",
+      "assertions": [
+        "Recognizes the request as application performance optimization, not cloud cost management",
+        "Refers to the performance-optimization skill for the N+1/indexing work",
+        "Does not produce a FinOps workflow (tagging, rightsizing, commitments) as the answer",
+        "States or implies the boundary: performance-optimization owns making code fast; finops-cost-optimization owns understanding and reducing spend"
+      ]
+    }
+  ]
+}

package/skills/git-workflow/SKILL.md

@@ -52,6 +52,10 @@ Use the Conventional Commits format — see [references/conventions.md](referenc
 - Breaking changes: `BREAKING CHANGE: description`
 - Co-authors: `Co-authored-by: Name <email>`
 
+Commit types are not just style — in automated release flows they drive the version:
+`fix` → PATCH, `feat` → MINOR, `feat!`/`BREAKING CHANGE:` → MAJOR. A mislabeled type
+mis-versions the next release (see `release-management`).
+
 ### Step 3: Validate
 
 Before committing, check:
@@ -125,3 +129,9 @@ See [references/conventions.md](references/conventions.md) for branch naming con
 - **KISS**: One commit = one logical change. Don't bundle unrelated changes.
 - **DRY**: If you're writing the same commit message pattern repeatedly, you might be making commits too granular or too broad.
 - **Functional Independence**: Each PR should be independently deployable when possible. Avoid PRs that depend on other unmerged PRs.
+
+## Cross-Skill References
+
+- `release-management` — cutting the release these commits accumulate into: semver, changelog, tagging, publishing
+- `code-reviewing` — reviewing the PR the description introduces
+- `verification-before-completion` — run the proving commands before pushing or opening the PR

package/skills/llm-app-engineering/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: llm-app-engineering
+description: "Design and build LLM-powered applications — prompt and context engineering, RAG architecture (chunking, hybrid retrieval, reranking, grounded prompts), agent design (tool surfaces, planning, sub-agents), and memory. Triggers: build a chatbot, LLM app, AI assistant, prompt engineering, system prompt, RAG design, chunking, embeddings, vector database, semantic search, AI agent, tool calling, agent memory, context window, hallucinations. Measuring quality → ai-evaluation; model serving/inference infra → ml-model-deployment."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# LLM App Engineering
+
+Design LLM applications as **systems, not prompts**: what goes into the context
+window, what the model is allowed to do, and what happens when it's wrong. The
+model is the one component you don't control — engineer everything around it.
+This skill designs and builds; proving a change helped is `ai-evaluation`'s job,
+and no design below is "done" until it has an eval harness.
+
+## Workflow
+
+### Step 1: Choose the Simplest Sufficient Architecture
+
+Escalate only when the previous rung measurably fails:
+
+1. **Single prompt** — the task fits in one call with instructions + input.
+2. **+ RAG** — the answer needs knowledge that doesn't fit in the prompt or
+   changes independently of deploys.
+3. **+ Tools** — the model must act (query, search, write) — not just answer.
+4. **Agent loop** — the path to the goal is genuinely unpredictable in advance.
+   Most "agents" that fail are workflows that should have been a fixed pipeline
+   with one or two LLM steps.
+
+### Step 2: Engineer the Prompt as an Interface
+
+- Structure: role and constraints → domain context → task → output format.
+  Put stable content first (prompt caching) and the volatile input last.
+- State what to do on failure: "if the context doesn't contain the answer, say
+  so" — the unhappy path is where LLM apps lose user trust.
+- Version prompts in git like code; a prompt change is a deploy and goes
+  through the same eval gate (`ai-evaluation`).
+
+### Step 3: RAG — Design Retrieval Before Generation
+
+Most bad RAG answers are retrieval failures wearing a generation costume.
+
+- **Chunking**: split on document structure (headings, sections, one
+  ticket+resolution per chunk), not fixed character counts; attach metadata
+  (source, date, product area) for filtering and citations.
+- **Retrieval**: hybrid (BM25 + vector) as the default — pure vector search
+  misses exact identifiers, SKUs, and error codes; filter by metadata, then
+  **rerank** the candidate set (retrieve ~20–50, keep the top 5–10).
+- **Context budget** (decide, don't default): how many chunks fit, in what
+  order (most relevant near the question), the relevance floor below which a
+  chunk is dropped, and the behavior when nothing clears it — say "I don't
+  know" rather than pad the context with noise.
+- **Grounding prompt**: answer only from the provided context, cite which
+  source supports each claim, refuse when unsupported.
+
+### Step 4: Agents — Design the Tool Surface and the Loop
+
+- **Tools**: few and sharply distinct beat many and overlapping — every tool
+  description competes for the model's attention on every step. Name by
+  intent (`search_orders`, not `api_call`); make each tool's failure return a
+  message the model can act on, not a stack trace.
+- **Decomposition**: long tasks fail as one monolithic loop with 25 tools;
+  split into phases or sub-agents, each with a scoped toolset, and pass
+  structured summaries between them — not raw transcripts.
+- **Guardrails**: cap iterations, budget tokens per task, and validate
+  side-effecting tool calls (or require confirmation) — an agent retrying a
+  failed write in a loop is the classic production incident.
+
+### Step 5: Memory — Externalize State
+
+The context window is a scarce cache, not a database. For long-horizon work:
+keep a plan/scratchpad file the agent re-reads and updates; summarize or
+compact stale history instead of letting it scroll off; store durable facts
+(user preferences, decisions) outside the window and retrieve them like RAG.
+
+### Step 6: Wire In Evaluation Before Shipping
+
+Hand the design to `ai-evaluation`: a golden dataset (including unanswerable
+and adversarial cases), RAG-stage metrics (retrieval vs generation scored
+separately), agent task-success rate, and a CI regression gate. "The answers
+feel better" is not evidence; a design without an eval harness is a prototype.
+
+Deeper pattern detail (chunking table, reranking, memory patterns, failure
+modes): [references/patterns.md](references/patterns.md).
+
+## Principles Applied
+
+- **KISS**: every architecture rung you skip is a class of failure you never
+  have to debug. Workflows beat agents when the path is predictable.
+- **YAGNI**: no vector DB before checking whether the corpus fits in the
+  prompt; no agent framework before a plain loop with 3 tools fails.
+- **SRP for tools**: one tool, one capability — overlapping tools force the
+  model to guess, and it will guess differently each run.
+
+## Cross-Skill References
+
+- `ai-evaluation` — golden datasets, RAG metrics, judges, eval gates (the
+  measurement half of every step above)
+- `ml-model-deployment` — serving, monitoring, and drift once the app ships
+- `api-design` — the contract around the LLM feature (streaming, errors, timeouts)
+- `security-audit` — prompt injection, data exfiltration via tools, output handling
+- `architecture-design` — ADRs for costly-to-reverse choices (vector store, framework)