@causyne/agent 0.0.0-stage → 1.10.0

package/native-skills/backend/rest-api-design/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: rest-api-design
+description: Design or review an HTTP API. Use when endpoints are being added, when responses are inconsistent, or when clients need to special-case error handling.
+---
+
+# REST API Design
+
+## Workflow
+
+1. Model resources, not actions.
+   - `POST /orders`, not `POST /createOrder`. The verb is the method. When an operation genuinely is not a resource change (`/search`, `/reindex`), say so explicitly rather than contorting a noun.
+   - **Done when:** every path is a noun and every method carries the verb.
+
+2. Use status codes the way clients expect.
+   - 200 with a body, 201 with a `Location`, 204 with none. 400 malformed, 401 unauthenticated, 403 authenticated but not permitted, 404 absent, 409 conflict, 422 semantically invalid, 429 rate-limited.
+   - Never return 200 with an error inside the body. Every client's error handling depends on the status.
+   - **Done when:** no successful-looking status carries an error payload.
+
+3. Give errors one shape.
+   - A stable machine-readable code, a human message, and a field-level detail list where relevant. RFC 9457 problem details is a reasonable default.
+   - Never leak a stack trace or an internal identifier to a client.
+   - **Done when:** every error response validates against one schema.
+
+4. Paginate every collection from day one.
+   - Cursor-based, not offset-based: offset pagination skips and repeats rows when the underlying data changes between pages. An unpaginated list endpoint is an outage waiting for the table to grow.
+   - **Done when:** every collection endpoint has a documented limit and cursor.
+
+5. Version before you need to.
+   - A path prefix (`/v1/`) is the simplest thing that works. Adding a version after clients exist is far harder than starting with one.
+   - **Done when:** every route carries a version.
+
+6. Make writes idempotent.
+   - PUT and DELETE are idempotent by definition. POST needs an `Idempotency-Key` header if a retry must not duplicate the effect — and clients on flaky networks WILL retry.
+   - **Done when:** replaying a write with the same key produces one effect.
+
+## Verification
+
+- An OpenAPI document describes every route and matches the implementation.
+- Every error path returns the shared error shape with the correct status.
+- Replaying a POST with the same idempotency key creates one record.

package/native-skills/backend/webhook-delivery-and-receipt/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: webhook-delivery-and-receipt
+description: Send or receive webhooks. Use when integrating a third-party callback, when webhook handlers time out, or when duplicate deliveries cause duplicate effects.
+---
+
+# Webhook Delivery and Receipt
+
+## Receiving
+
+1. **Verify the signature before parsing.**
+   - Compute the expected signature over the RAW body and compare in constant time. Parsing first means acting on unverified input, and many frameworks mutate the body during parsing so the signature can no longer be checked at all.
+   - **Done when:** an unsigned or wrongly signed request is rejected with 401 before any parsing.
+
+2. **Check the timestamp.**
+   - Reject anything older than a few minutes. Without this, a captured request can be replayed indefinitely.
+   - **Done when:** a replayed old request is rejected.
+
+3. **Acknowledge fast, process later.**
+   - Persist the event and return 200 within a couple of seconds; do the work in a job. Senders time out quickly and retry, and a slow handler turns one event into many.
+   - **Done when:** the handler returns before doing any real work.
+
+4. **Deduplicate on the event id.**
+   - Delivery is at-least-once from every provider. Store the id with a uniqueness constraint and ignore repeats.
+   - **Done when:** delivering the same event twice produces one effect.
+
+5. **Return the right status.**
+   - 200 for accepted, including for a duplicate. 4xx only for something a retry cannot fix — a 4xx usually makes the sender stop permanently. 5xx to ask for a retry.
+   - **Done when:** the status semantics are documented per branch.
+
+## Sending
+
+1. **Sign every request** over the raw body with a shared secret and include a timestamp.
+2. **Retry with exponential backoff and jitter**, for hours, then dead-letter and notify.
+3. **Give each event a stable id** so the receiver can deduplicate.
+4. **Time out fast** — a few seconds — so one slow receiver cannot block the queue.
+   - **Done when:** a receiver that never responds does not degrade delivery to others.
+
+## Verification
+
+- An unsigned request is rejected.
+- The same event delivered twice produces one effect.
+- The handler responds in under two seconds under load.
+- A failing receiver ends up in the dead-letter queue with an alert.

package/native-skills/cloud/cost-optimisation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: cost-optimisation
+description: Reduce cloud spend. Use when a bill grows unexpectedly, before scaling up, or during a cost review.
+---
+
+# Cloud Cost Optimisation
+
+## Where the money usually is
+
+Idle resources, oversized instances, data transfer, and storage nobody deleted. Rarely the thing people assume. Find out before acting.
+
+## Workflow
+
+1. Attribute the spend before changing anything.
+   - Tag everything by team, environment and service, then break the bill down. An unattributed bill cannot be reduced deliberately.
+   - **Done when:** most of the spend is attributed to a named owner.
+
+2. Delete what is not used.
+   - Unattached volumes, old snapshots, idle load balancers, unused addresses, forgotten environments. This is the largest and easiest win in most accounts and requires no architectural change.
+   - **Done when:** every unattached resource is deleted or justified.
+
+3. Right-size from measurement.
+   - Instances provisioned for a peak that never came. Look at actual utilisation over weeks and resize. Under 20% sustained is over-provisioned.
+   - **Done when:** every instance's size is justified by observed utilisation.
+
+4. Match the storage class to the access pattern.
+   - Data read once a year should not sit in the hot tier. Lifecycle rules move it automatically, and this is often a large saving on old logs and backups.
+   - **Done when:** every bucket has a lifecycle policy.
+
+5. Look hard at data transfer.
+   - Cross-zone and cross-region traffic is billed and frequently accidental — a service talking to a database in another zone, or a chatty pattern that should be batched. This line is often larger than compute and almost never examined.
+   - **Done when:** transfer charges are attributed to specific flows.
+
+6. Commit only to a proven baseline.
+   - Reserved capacity or savings plans for load you are certain persists. Committing to a spike locks in the wrong number for a year.
+   - **Done when:** commitments cover only the measured steady-state.
+
+7. Alert on the anomaly, not the total.
+   - A budget alert at month end is too late. Alert on a daily rate change.
+   - **Done when:** a sudden daily increase raises an alert within a day.
+
+## Verification
+
+- Spend is attributed by owner.
+- Before and after monthly figures are reported.
+- Anomaly alerting is in place.

package/native-skills/cloud/iam-least-privilege/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: iam-least-privilege
+description: Configure cloud permissions or service accounts. Use when creating a role, when a policy grants broad access, or during a security review.
+---
+
+# IAM Least Privilege
+
+## The default failure
+
+A wildcard policy attached because something did not work and the error message did not say which permission was missing. It works, so it stays, and it is a full compromise waiting for one leaked credential.
+
+## Workflow
+
+1. Give every workload its own identity.
+   - Shared credentials make it impossible to tell what did something, and impossible to revoke one consumer without breaking the others.
+   - **Done when:** each workload has a distinct identity.
+
+2. Start from deny and add what fails.
+   - Run with no permissions, read the access-denied errors, and grant exactly those. This is slower than starting broad and narrowing, and it is the only approach that actually converges.
+   - **Done when:** the policy contains only permissions the workload demonstrably needs.
+
+3. Scope to resources, not just to actions.
+   - Read on one bucket, not read on all buckets. Most policies get the action right and leave the resource as a wildcard, which is most of the exposure.
+   - **Done when:** no resource field is a bare wildcard.
+
+4. Use short-lived credentials.
+   - Workload identity federation or the platform's instance identity. A long-lived key in an environment variable is a key in every backup, log and image.
+   - **Done when:** no static long-lived credential exists for any workload.
+
+5. Add conditions where they cost nothing.
+   - Source address range, requiring encryption in transit, or requiring multi-factor for sensitive actions. Each closes an avenue at no operational cost.
+   - **Done when:** high-value permissions carry a condition.
+
+6. Review with the analyser and remove unused grants.
+   - Cloud providers report permissions granted but never used. That report is the shortest path to a smaller blast radius.
+   - **Done when:** permissions unused for a stated period are removed.
+
+## Verification
+
+- No policy contains a wildcard action on a wildcard resource.
+- Each workload has its own identity with its own policy.
+- No long-lived static credential exists.
+- The access analyser reports no unused permission older than the review period.

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

@@ -0,0 +1,43 @@
+---
+name: infrastructure-as-code
+description: Manage cloud infrastructure through code. Use when resources were created by hand, when environments have drifted, or when setting up a new environment.
+---
+
+# Infrastructure as Code
+
+## The rule
+
+If it was created by hand, it does not exist reproducibly. A console change is invisible, unreviewable, and gone when the account is recreated. Every persistent resource is defined in code.
+
+## Workflow
+
+1. Import what already exists before writing anything new.
+   - Most environments have hand-made resources. Import them into state so the code describes reality; writing new code alongside undocumented resources creates conflicts and duplicates.
+   - **Done when:** a plan against the existing environment shows no changes.
+
+2. Make the environment a parameter.
+   - One module, several variable files. Copied directories per environment drift within weeks, and the drift is discovered during an incident.
+   - **Done when:** adding an environment requires only a new variables file.
+
+3. Separate state by blast radius.
+   - Networking, data stores and applications in separate states. One state file for everything means a mistake in the application layer can plan a change to the database.
+   - **Done when:** an application change cannot plan a change to a data store.
+
+4. Review the plan as code review.
+   - The plan output goes on the pull request. Reviewing the source without the plan misses what the provider will actually do — particularly the resources it intends to replace.
+   - **Done when:** every change is reviewed with its plan attached.
+
+5. Guard destructive changes.
+   - Deletion protection on data stores, and a lifecycle rule preventing accidental destruction. A resource replacement that recreates a database is the classic catastrophic apply.
+   - **Done when:** no plan can destroy a data store without an explicit override.
+
+6. Detect drift on a schedule.
+   - A periodic plan that reports differences. Someone will change something in the console; the question is whether you find out in a day or during an incident.
+   - **Done when:** a scheduled drift check reports differences to an owner.
+
+## Verification
+
+- A plan against production shows no unexplained changes.
+- A new environment can be created from code alone.
+- Data stores are protected from accidental destruction.
+- Drift detection runs on a schedule.

package/native-skills/cloud/multi-region-and-failover/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: multi-region-and-failover
+description: Design for regional failure or high availability. Use when planning for an outage, when latency varies by geography, or when a single region is a single point of failure.
+---
+
+# Multi-Region and Failover
+
+## Be honest about the cost
+
+Multi-region multiplies infrastructure cost and operational complexity, and introduces data consistency problems that do not exist in one region. Most systems should first make one region genuinely resilient — multiple availability zones, tested backups, tested restore. Reach for multi-region when the requirement demands it, not by default.
+
+## Workflow
+
+1. State the requirement in numbers.
+   - How much data may be lost, how long recovery may take, and what an hour of downtime costs. These decide whether the complexity is justified.
+   - **Done when:** the recovery objectives and the cost of downtime are written down.
+
+2. Choose the posture deliberately.
+   - Backup and restore: cheapest, hours to recover. Warm standby: minutes, moderate cost. Active-active: seconds, highest cost and hardest consistency.
+   - **Done when:** the posture is chosen against the stated numbers.
+
+3. Solve the data problem first.
+   - This is the hard part, and everything else is easy by comparison. Asynchronous replication means a failover loses the replication lag. Synchronous costs latency on every write. Active-active means conflicts, and you must define the resolution rule.
+   - **Done when:** the replication mode and its data-loss window are stated.
+
+4. Make failover a routine, tested operation.
+   - Automate it, document it, and rehearse it on a schedule. An untested failover fails when it is needed — that is the observed pattern, not a caution.
+   - **Done when:** a failover has been performed in a rehearsal within the last quarter.
+
+5. Do not forget what is regional but invisible.
+   - Certificates, secrets, DNS records, container registries, queues, and scheduled jobs. Failover fails on the one dependency nobody listed.
+   - **Done when:** every regional dependency has a plan.
+
+6. Plan the failback.
+   - Returning to the primary region requires reconciling data written to the secondary. This is frequently harder than the failover and is usually not planned.
+   - **Done when:** failback has been rehearsed and its data reconciliation is defined.
+
+## Verification
+
+- Recovery objectives are stated and the posture meets them.
+- A failover rehearsal has been performed and timed.
+- Every regional dependency is inventoried.
+- Failback has been rehearsed.

package/native-skills/cloud/serverless-patterns/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: serverless-patterns
+description: Build or fix serverless functions. Use when cold starts are slow, when a function times out, or when a function exhausts a downstream resource.
+---
+
+# Serverless Patterns
+
+## What is different
+
+The execution environment is created and destroyed outside your control, may be reused, and may run thousands of copies at once. Every problem specific to serverless comes from one of those three.
+
+## Workflow
+
+1. Move initialisation outside the handler.
+   - Code outside the handler runs once per environment and is reused across invocations. Clients, configuration and connection setup belong there. Inside the handler it runs on every single invocation.
+   - **Done when:** no client is constructed inside the handler.
+
+2. Never rely on local state persisting, and never assume it will not.
+   - A warm environment retains its filesystem and memory. Writing a temporary file and not cleaning it up will eventually fill the space; caching in memory works but must tolerate a cold start.
+   - **Done when:** the function is correct whether or not the environment is reused.
+
+3. Bound the concurrency to protect what is downstream.
+   - A thousand concurrent functions each opening a database connection will exhaust the database. Set a reserved concurrency limit, and use a connection proxy or a data API rather than direct connections.
+   - **Done when:** peak concurrency cannot exceed what downstream can serve.
+
+4. Make every handler idempotent.
+   - Event sources deliver at least once. A retry after a timeout means the work may already have happened.
+   - **Done when:** processing the same event twice produces one effect.
+
+5. Set timeouts deliberately, on both ends.
+   - The function timeout must exceed the sum of its outbound call timeouts, and each outbound call must have one. Otherwise the function times out with no useful log.
+   - **Done when:** every outbound call has a timeout shorter than the function's.
+
+6. Handle failure explicitly.
+   - A dead-letter target for every asynchronous invocation, and an alert on its depth. Without one, failures vanish.
+   - **Done when:** failed invocations land somewhere with an alert.
+
+7. Address cold starts only if measured.
+   - Smaller packages, a faster runtime, and provisioned concurrency where the latency genuinely matters. Provisioned concurrency costs money continuously — measure first.
+   - **Done when:** cold start latency is measured and the mitigation is justified.
+
+## Verification
+
+- Clients are created once per environment, not per invocation.
+- A load test does not exhaust downstream connections.
+- The same event delivered twice produces one effect.
+- Failed asynchronous invocations reach a dead-letter target.

package/native-skills/data/data-quality-monitoring/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: data-quality-monitoring
+description: Detect data problems before people act on them. Use when bad data has reached a dashboard, or when setting up a new data source.
+---
+
+# Data Quality Monitoring
+
+## The failure that costs most
+
+Not the pipeline that breaks — that gets noticed. The pipeline that keeps running while the data quietly goes wrong. Those are discovered weeks later, after decisions have been made on the numbers.
+
+## The dimensions worth monitoring
+
+- **Freshness** — is the newest record as recent as it should be.
+- **Volume** — is the row count within its normal band.
+- **Schema** — have columns or types changed upstream.
+- **Distribution** — has a column's shape shifted beyond its normal variation.
+- **Uniqueness and referential integrity** — are keys still unique, do references still resolve.
+
+## Workflow
+
+1. Baseline before alerting.
+   - Measure normal for a few weeks. Alerting on a guessed threshold produces noise, and a noisy alert is an ignored alert.
+   - **Done when:** each check has a threshold derived from observed variation.
+
+2. Check freshness first.
+   - It catches the most failures for the least effort. A stale partition means the pipeline is broken regardless of what else passes.
+   - **Done when:** every dataset has a maximum-age alert.
+
+3. Detect schema change at ingestion.
+   - An upstream column rename or type change is silent and corrupting. Compare the incoming schema to the expected one and fail on an unexpected difference.
+   - **Done when:** a schema change stops the pipeline rather than propagating.
+
+4. Monitor distributions on the columns that matter.
+   - Null rate, distinct count, and the quantiles of numeric columns. A null rate moving from 1% to 40% is a broken upstream field, and no error will be raised.
+   - **Done when:** key columns have distribution checks with bands.
+
+5. Route alerts to an owner.
+   - Every dataset has a name attached. An alert to a shared channel with no owner is an alert nobody acts on.
+   - **Done when:** each dataset's alerts have a named owner.
+
+6. Surface the check results next to the data.
+   - A dashboard reading a dataset that failed its checks should say so. Otherwise the consumer cannot know.
+   - **Done when:** consumers can see the freshness and check status of what they are reading.
+
+## Verification
+
+- A deliberately stale partition raises an alert.
+- An upstream column rename stops the pipeline.
+- A spike in the null rate is detected.
+- Every alert has an owner.

package/native-skills/data/etl-pipeline-reliability/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: etl-pipeline-reliability
+description: Build or fix a data pipeline. Use when a scheduled job fails silently, when a rerun duplicates data, or when downstream numbers are wrong.
+---
+
+# ETL Pipeline Reliability
+
+## The two properties
+
+Idempotence and observability. A pipeline that cannot be safely re-run cannot be fixed after a failure, and one that fails silently produces wrong numbers that people act on for weeks.
+
+## Workflow
+
+1. Make every run idempotent.
+   - Re-running for the same period must produce the same result, not double it. Partition the output by period and replace the partition wholesale, rather than appending.
+   - **Done when:** running the same period twice yields identical output.
+
+2. Partition by logical time, not by run time.
+   - A job for yesterday should produce yesterday's partition whenever it runs. Keying on the run time makes a backfill impossible and a late run wrong.
+   - **Done when:** the output partition is determined by the data's period.
+
+3. Validate at every boundary.
+   - Row counts within an expected range, no unexpected nulls in required columns, keys unique, and totals reconciling with the source. Fail the run rather than writing bad data — downstream consumers cannot tell the difference.
+   - **Done when:** each stage has assertions that stop the pipeline on violation.
+
+4. Quarantine bad records, do not drop them.
+   - Write rejects with the reason to a separate location. Silently dropping rows makes numbers wrong with no trace.
+   - **Done when:** every rejected record is retrievable with its reason.
+
+5. Alert on staleness and on volume, not only on errors.
+   - The dangerous failure is the job that succeeds while producing nothing, or a tenth of the usual rows. Alert if the newest partition is older than expected, or the volume moves outside its band.
+   - **Done when:** an empty successful run raises an alert.
+
+6. Make backfill a normal operation.
+   - Parameterise the period and support running a range. A pipeline that cannot backfill cannot recover from an outage.
+   - **Done when:** a range backfill runs with one command and produces correct partitions.
+
+## Verification
+
+- Re-running a period produces identical output.
+- A deliberately corrupted input fails the run rather than writing.
+- An empty run triggers an alert.
+- A backfill over a week produces correct partitions.

package/native-skills/data/exploratory-analysis/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: exploratory-analysis
+description: Analyse an unfamiliar dataset. Use when receiving new data, before modelling, or when a metric looks wrong.
+---
+
+# Exploratory Data Analysis
+
+## The order
+
+Understand the data before asking it questions. An analysis built on a misunderstood column produces a confident wrong answer, and nothing downstream will catch it.
+
+## Workflow
+
+1. Establish the shape and provenance.
+   - Row count, column count, types, and where the data came from — including what was filtered before you received it. Data that arrives pre-filtered has a selection bias you must know about.
+   - **Done when:** you can state what one row represents, precisely.
+
+2. Profile every column.
+   - Missing rate, cardinality, range, and the most frequent values. For dates, the minimum and maximum — future dates and epoch-zero dates are both common and both indicate a bug upstream.
+   - **Done when:** every column has been profiled and anomalies are noted.
+
+3. Ask what the missing values mean.
+   - Missing at random is very different from missing because the field only applies to some rows, and different again from missing because a system failed for a period. The three demand different handling and only investigation distinguishes them.
+   - **Done when:** each column with missing values has a stated explanation.
+
+4. Check the identifiers.
+   - Are the keys unique? Do foreign keys resolve? Duplicate rows from a bad join are the most common silent corruption in an analysis, and they inflate every aggregate.
+   - **Done when:** key uniqueness and referential integrity have been verified.
+
+5. Plot the distributions before summarising them.
+   - A mean describes a unimodal distribution. On a bimodal or heavy-tailed one it describes nothing real. Look at the shape first.
+   - **Done when:** every variable you will summarise has been plotted.
+
+6. Look for the seams.
+   - A step change in a time series usually means an instrumentation change, not a real change in the world. Check deploy dates before writing a conclusion.
+   - **Done when:** discontinuities have been explained or flagged.
+
+## Verification
+
+- The meaning of one row is stated.
+- Every column is profiled and every anomaly explained or flagged.
+- Key uniqueness is verified.
+- Conclusions name their caveats.

package/native-skills/data/metric-definition/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: metric-definition
+description: Define a business or product metric. Use when two teams report different numbers for the same thing, or before building a dashboard.
+---
+
+# Metric Definition
+
+## Why the same metric gives two answers
+
+Because it was never defined. "Active users" has a dozen reasonable readings, and every team picks one implicitly. The disagreement is discovered in a meeting, months later, after decisions have been made on both numbers.
+
+## Workflow
+
+1. Write the definition in a sentence a non-engineer can check.
+   - Include the population, the event, the window, and the exclusions. "Users who performed at least one search in the trailing 28 days, excluding internal accounts and bots, counted by account not by device."
+   - **Done when:** two people can independently implement it and agree.
+
+2. Decide the time semantics explicitly.
+   - Which timezone, event time or ingestion time, and how late-arriving data is handled. These three choices change the number and are almost never written down.
+   - **Done when:** all three are stated.
+
+3. Name the exclusions.
+   - Internal users, test accounts, bots, refunded orders, deleted records. Each one is a decision, and a metric that excludes nothing is usually wrong.
+   - **Done when:** every exclusion is listed with a reason.
+
+4. Define it once, in one place.
+   - A semantic layer or a shared model that every dashboard queries. The same metric computed in three dashboards will give three answers within a quarter.
+   - **Done when:** every consumer reads the same definition.
+
+5. State the expected range and alert outside it.
+   - A metric with no expected range cannot be sanity-checked. If it doubles overnight, is that success or an instrumentation bug? Usually the latter.
+   - **Done when:** an expected band exists and a breach raises a question.
+
+6. Version the definition.
+   - When it changes, the historical series changes. Record when and why, and never silently restate history.
+   - **Done when:** definition changes are dated and visible on the chart.
+
+## Verification
+
+- Two independent implementations produce the same number.
+- The definition names population, event, window, timezone, and exclusions.
+- Every dashboard reads one definition.

package/native-skills/data/notebook-to-production/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: notebook-to-production
+description: Turn analysis code into something that runs reliably. Use when a notebook needs to become a scheduled job, or when analysis results cannot be reproduced.
+---
+
+# Notebook to Production
+
+## What breaks in the move
+
+Hidden state. A notebook's output depends on which cells were run and in what order, and that order is not recorded. Code that works in a notebook frequently does not work when run top to bottom — which is what any scheduler will do.
+
+## Workflow
+
+1. Prove it runs top to bottom first.
+   - Restart the kernel and run all. If it fails, the notebook depended on state that no longer exists, and the analysis result is not reproducible either.
+   - **Done when:** a fresh kernel produces the same result end to end.
+
+2. Extract logic into functions in a module.
+   - The notebook becomes a thin caller. Functions can be tested, imported and reused; cells cannot.
+   - **Done when:** the notebook contains calls and plots, not logic.
+
+3. Replace every hardcoded path and credential.
+   - Paths, dates and credentials become parameters or configuration. A hardcoded date silently produces stale results forever.
+   - **Done when:** nothing environment-specific is embedded in the code.
+
+4. Pin the environment.
+   - A lock file. Analysis results depend on library versions, and a silent upgrade changes numbers without changing code.
+   - **Done when:** a fresh environment built from the lock file reproduces the result.
+
+5. Add validation and make failure loud.
+   - Assertions on row counts, ranges and key uniqueness. A scheduled job that fails silently produces wrong numbers that people act on.
+   - **Done when:** a bad input fails the run visibly.
+
+6. Test the extracted functions.
+   - Start with the transformations that carry business logic. These are where a wrong result is both most likely and most costly.
+   - **Done when:** the core transformations have tests with known inputs and outputs.
+
+## Verification
+
+- A fresh environment reproduces the result exactly.
+- The module runs from a scheduler with no notebook.
+- Corrupt input fails loudly.
+- The core transformations have tests.

package/native-skills/database/backup-and-recovery/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: backup-and-recovery
+description: Set up or verify database backups. Use when a system has no tested restore, before a risky migration, or when planning for data loss.
+---
+
+# Backup and Recovery
+
+## The only thing that counts
+
+A backup that has never been restored is not a backup. It is an untested hypothesis with a storage bill. The restore is the deliverable.
+
+## Workflow
+
+1. State the two numbers first.
+   - Recovery point objective: how much data may be lost. Recovery time objective: how long recovery may take. Everything else follows from these, and without them the design is arbitrary.
+   - **Done when:** both numbers are written down and agreed.
+
+2. Choose the mechanism to meet them.
+   - Nightly dump: hours of potential loss, simple. Continuous archiving with point-in-time recovery: seconds of loss, more moving parts. A replica is high availability, NOT a backup — it replicates the bad DELETE faithfully and instantly.
+   - **Done when:** the mechanism demonstrably meets both numbers.
+
+3. Store copies where a single failure cannot reach them.
+   - A different region and a different credential. Ransomware and a compromised account both reach anything the production credential can write, which is why immutable or write-once storage matters.
+   - **Done when:** a compromised production credential cannot delete the backups.
+
+4. Restore on a schedule, into a real environment.
+   - Automate it, time it, and check row counts and a few known records. Do this monthly at minimum.
+   - **Done when:** a restore has been performed and timed within the last month.
+
+5. Back up more than the rows.
+   - Schema, roles and grants, extensions, sequence positions, and any encryption keys. A restored database nobody can log into is not recovered.
+   - **Done when:** a restore into an empty instance produces a working system with no manual steps.
+
+6. Write the runbook.
+   - Exact commands, in order, for someone who did not build the system, under pressure, possibly at night.
+   - **Done when:** someone else has followed the runbook successfully without help.
+
+## Verification
+
+- A restore into a clean environment has been performed and timed.
+- The restore time meets the recovery time objective.
+- The data loss window meets the recovery point objective.
+- Someone other than the author has run the runbook.

package/native-skills/database/connection-pooling/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: connection-pooling
+description: Configure database connections for a service. Use when the database refuses connections, when latency spikes under load, or when a serverless function exhausts connections.
+---
+
+# Connection Pooling
+
+## The counterintuitive part
+
+A bigger pool is usually slower. A database has a finite number of cores and disks; connections beyond that queue INSIDE the database, where you cannot see them, instead of in your pool where you can. A pool of ten often outperforms a pool of a hundred on the same hardware.
+
+## Workflow
+
+1. Size from the database, not from the traffic.
+   - A reasonable starting point is a small multiple of the database's core count, divided across all application instances. Then measure.
+   - **Done when:** the total connections across every instance is below the database's limit with headroom.
+
+2. Count every consumer.
+   - Application instances, background workers, migration jobs, admin tools, and monitoring. The limit is shared, and the job that fails to connect is usually the one that runs during a traffic peak.
+   - **Done when:** the sum of all configured pools plus reserved superuser slots fits the limit.
+
+3. Set every timeout.
+   - Connection acquisition, socket, and statement timeouts. A missing statement timeout lets one runaway query hold a connection indefinitely, and the pool drains one connection at a time until the service is down.
+   - **Done when:** no query can run unbounded.
+
+4. Add an external pooler for serverless or high instance counts.
+   - Each function invocation opening its own connection exhausts the database immediately. A transaction-mode pooler in front is the standard answer — with the caveat that it breaks session-level features like prepared statements and advisory locks.
+   - **Done when:** the pooling mode is chosen and its limitations are accounted for in the code.
+
+5. Return connections deterministically.
+   - Acquire and release in a `finally` or an equivalent scope guard. A leaked connection on an error path drains the pool slowly and the symptom appears hours later.
+   - **Done when:** every acquisition has a guaranteed release.
+
+6. Instrument the pool.
+   - Active, idle, and waiting counts. A rising wait count is the earliest signal of saturation, well before latency shows it.
+   - **Done when:** pool saturation is visible on a dashboard.
+
+## Verification
+
+- A load test shows stable latency with no connection errors.
+- Total configured connections are within the database limit.
+- A deliberately slow query is terminated by the statement timeout.