@ericrisco/rsc 0.1.44 → 0.1.46

package/skills/csharp-dotnet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: csharp-dotnet
-description: "Use when writing, reviewing, testing, or shipping C# / .NET code, ASP.NET Core APIs, or EF Core data access — editing .cs/.csproj/.sln files, designing minimal APIs vs controllers, fixing async correctness, or structuring a dotnet solution. Triggers: 'build a .NET API', 'is this idiomatic C#', 'should this DTO be a record', 'my endpoint hangs/deadlocks under load' (sync-over-async), 'EF query hits the DB once per row' (N+1), 'set up xUnit + WebApplicationFactory', 'crea una API en .NET', 'revisa este código C# antes de hacer deploy'. NOT a Java/Spring backend (that is spring-boot), NOT a Node/TypeScript backend (that is nestjs)."
+description: "Use when writing, reviewing, testing, or shipping C# / .NET code — ASP.NET Core APIs (minimal APIs vs controllers), EF Core data access, async correctness, solution layout in .cs/.csproj/.sln. NOT a Java/Spring backend (that is spring-boot), NOT a Node/TypeScript backend (that is nestjs), NOT framework-neutral REST naming (that is api-design)."
 tags: [csharp, dotnet, aspnetcore, efcore, async]
 recommends: [postgresdb, secure-coding, deployment]
 origin: risco
@@ -20,17 +20,6 @@ support but shorter-lived. Features gate on the target framework moniker (TFM):
 use a C# 14 feature (`field`, extension members, null-conditional assignment), say
 which TFM it requires.
 
-## When to use
-
-- Authoring/reviewing/refactoring any `.cs`, `.csproj`, or `.sln`.
-- ASP.NET Core: minimal APIs vs controllers, route groups, endpoint filters,
-  validation, ProblemDetails, OpenAPI.
-- EF Core: `DbContext` design, LINQ queries, migrations, tracking, N+1.
-- async/await correctness: `CancellationToken` plumbing, `async void`, deadlocks,
-  `IAsyncEnumerable`, `ValueTask`.
-- `dotnet` CLI workflow, solution layout, NuGet, central package management.
-- Idiom review: records, pattern matching, nullable reference types (NRT).
-
 ## When NOT to use — delegate
 
 | Situation | Route to |
@@ -45,29 +34,7 @@ which TFM it requires.
 
 The .NET *expression* of an API contract and async correctness live HERE. Resource
 naming theory lives in `api-design`; the JVM and Node counterparts are `spring-boot`
-and `nestjs`. Only `secure-coding`, `postgresdb`, `deployment`, and `harness` exist on
-disk as siblings, so only those are linked as `../<id>/SKILL.md`.
-
-## Decision rules — apply on every C# edit
-
-1. **NRT on.** `<Nullable>enable</Nullable>` in the csproj. Why: the compiler turns
-   whole classes of `NullReferenceException` into build-time warnings. Never disable it
-   to silence a warning — fix the nullability.
-2. **Async all the way, flow the token.** I/O methods are `async Task`, every call is
-   `await`ed, and a `CancellationToken` threads from the endpoint down to
-   `SaveChangesAsync`/queries/HTTP calls. Why: a dropped token means requests keep
-   running after the client gives up.
-3. **Records for DTOs and immutable data.** `public record ProductDto(int Id, string Name);`.
-   Why: value equality + `with` expressions + concise; never reuse an EF entity as the
-   wire DTO (see anti-patterns).
-4. **Parameterize every query.** EF LINQ and `FromSql` interpolation parameterize for
-   you; never string-concatenate SQL. Why: SQL injection.
-5. **Deterministic disposal.** `using`/`await using` (or `using` declarations) for
-   anything `IDisposable`/`IAsyncDisposable`. Why: leaked connections/handles.
-6. **One `DbContext` per request (scoped).** Why: `DbContext` is not thread-safe;
-   sharing across requests corrupts change tracking.
-7. **Minimal APIs for new services** unless you need MVC features (views, model
-   binders, action filters at scale). Why: less ceremony, first-class in .NET 10.
+and `nestjs`.
 
 ## Project & solution layout + dotnet CLI
 
@@ -101,6 +68,10 @@ Central package management: turn it on with `<ManagePackageVersionsCentrally>tru
 and list versions once in `Directory.Packages.props`. Why: one source of truth, no
 version drift across projects.
 
+NRT on for every project — `<Nullable>enable</Nullable>` in `Directory.Build.props`.
+Why: the compiler turns whole classes of `NullReferenceException` into build-time
+warnings. Never disable it to silence a warning — fix the nullability.
+
 ## Modern C# idioms (C# 14 / .NET 10)
 
 DTO as a record, not a class:
@@ -113,6 +84,9 @@ public class ProductDto { public int Id { get; set; } public string Name { get;
 public record ProductDto(int Id, string Name, decimal Price);
 ```
 
+Why: value equality, `with` expressions, no boilerplate — and never reuse an EF entity
+as the wire DTO (see anti-patterns).
+
 Pattern matching over if-chains:
 
 ```csharp
@@ -154,6 +128,9 @@ Prefer NRT annotations over defensive null checks: declare `string? note` when n
 valid and let the compiler force callers to handle it, instead of `if (x == null)`
 guards scattered everywhere.
 
+Dispose deterministically: `using` / `await using` (or `using` declarations) for
+anything `IDisposable`/`IAsyncDisposable`. Why: leaked connections and handles.
+
 ## async/await correctness
 
 This is the highest-leverage area to get right. Core rules in body; the full catalog
@@ -173,7 +150,9 @@ public IActionResult Get() => Ok(_svc.LoadAsync().Result);
 public async Task<IActionResult> Get(CancellationToken ct) => Ok(await _svc.LoadAsync(ct));
 ```
 
-- **Flow `CancellationToken`** from the endpoint into every async call.
+- **Flow `CancellationToken`** from the endpoint down into every async call —
+  `SaveChangesAsync`, queries, outbound HTTP. Why: a dropped token means the request
+  keeps running after the client gives up.
 - **`ValueTask` only for hot paths** that usually complete synchronously; default to
   `Task`. Never `await` a `ValueTask` twice.
 - **`IAsyncEnumerable<T>` for streaming** results instead of materializing a huge list.
@@ -182,6 +161,7 @@ public async Task<IActionResult> Get(CancellationToken ct) => Ok(await _svc.Load
 
 Decision: **minimal API** for new services; **controllers** only when you need MVC
 machinery (model binding conventions, action filters at scale, views). Both can coexist.
+Why minimal by default: less ceremony, first-class in .NET 10.
 
 Production minimal API shape — route group + DataAnnotations validation (built in for
 minimal API parameters in .NET 10) + ProblemDetails + OpenAPI 3.1:
@@ -215,7 +195,8 @@ app.Run();
 ```
 
 DI lifetimes: `Singleton` (one for the app), `Scoped` (one per request — `DbContext`
-lives here), `Transient` (new each resolve). Never inject a `Scoped` service into a
+lives here; it is not thread-safe, so sharing one across requests corrupts change
+tracking), `Transient` (new each resolve). Never inject a `Scoped` service into a
 `Singleton` (captive dependency — see anti-patterns). Middleware ordering, endpoint
 filters, the options pattern, and auth defaults are in **references/aspnetcore.md**.
 
@@ -252,7 +233,7 @@ Keep only the .NET-specific controls here; threat modeling and OWASP review go t
 `../secure-coding/SKILL.md`.
 
 - **Parameterized data access** — EF LINQ / parameterized `FromSql` / ADO.NET
-  `SqlParameter`. Never concatenate user input into SQL.
+  `SqlParameter`. Never concatenate user input into SQL. Why: SQL injection.
 - **Secrets** — `dotnet user-secrets` in dev, Key Vault / environment in prod. Never in
   `appsettings.json` or source.
 - **Antiforgery** for cookie-auth browser POSTs; **Data Protection** for cookies/tokens

package/skills/customer-support/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: customer-support
-description: "Use when a support ticket, email, or chat lands and you must handle it well and fast — triage it (priority + queue + intent), draft a reply that does not read like a template, decide whether to escalate to a human, and keep the SLA clock from blowing. Also when an angry or churn-risk customer needs a de-escalation reply, when you need a canned-response library, or when you must set or audit first-response and resolution SLA targets. Triggers: 'a customer says our app is down and they're losing money', 'this user is threatening to cancel and leave a bad review, draft a reply', 'give me canned replies for common questions', 'what response times should we promise', 'redacta una respuesta para un cliente enfadado', 'tracta aquest ticket de suport'. NOT writing the help-center article the ticket links to (that is technical-writing), not the new-customer welcome flow (that is client-onboarding), not a win-back program (that is retention), and not building the auto-answer bot (that is chatbot)."
+description: "Use when a live support ticket needs triage (intent, P1–P4 priority, SLA clock), an on-voice reply, not a raw template, de-escalation of an angry or churn-risk customer, or escalation with a handoff packet. NOT the help-center article it links to (that is `technical-writing`), a win-back program (`retention`), or the auto-answer bot (`chatbot`)."
 tags: [customer-support, helpdesk, ticket-triage, sla, escalation, macros, de-escalation, csat]
 recommends: [technical-writing, client-onboarding, retention, chatbot, rag, brand-voice]
 origin: risco
@@ -8,22 +8,8 @@ origin: risco
 
 # Customer Support — Run the Desk on a Live Ticket
 
-*A ticket just came in. Triage it, answer it on-voice, escalate it if it needs a human, and keep the SLA from blowing. This skill handles the live ticket — it does not write the article the ticket links to.*
-
 You own the **support desk as an operation**: take an incoming ticket, assign priority and intent, start the SLA clock, draft the reply (macro or bespoke), enforce tone, and decide escalation with a clean handoff. The output is a triaged, answered ticket — human judgment, not a code artifact.
 
-## What this owns vs. what it does not
-
-| You reach for this when | Route elsewhere when |
-|---|---|
-| A ticket needs triage, a reply, an escalation call | Authoring the KB / help-center article a ticket links to → `technical-writing` |
-| One churn-risk ticket needs de-escalation **now** | Running a win-back / renewal **program** → `retention` |
-| You need macros, SLA targets, a handoff packet | Onboarding a brand-new customer (welcome, activation) → `client-onboarding` |
-| A human (or assisted) reply against the brand voice | Building the autonomous auto-answer bot → `chatbot` + `rag` |
-| Applying the voice to this reply | Authoring the voice guide itself → [`../brand-voice/SKILL.md`](../brand-voice/SKILL.md) |
-
-The line: **writing the help-center article a ticket links to is `technical-writing`'s job; `customer-support` only handles the live ticket.** This skill *consumes* the KB to answer; it never writes the docs.
-
 ## The triage-to-reply loop (the spine)
 
 Run every ticket through these six steps in order. Skipping triage to "just reply fast" is how you send the wrong tone to a P1.
@@ -37,29 +23,22 @@ Run every ticket through these six steps in order. Skipping triage to "just repl
 6 Escalate or send  →  trigger met? hand off with the packet. else send + log.
 ```
 
-The branch is at step 6. Use this table to decide priority and the first-response target, then whether the ticket leaves your hands:
+## Priority, SLA, and the escalation call
 
-| Signal in the ticket | Priority | First-response target | Escalate? |
-|---|---|---|---|
-| Production down / data loss / many users blocked | P1 | 15–30 min | Yes → tier-2/eng + the packet |
-| Enterprise/VIP account, or "cancel / refund / lawyer / unacceptable" | P1–P2 | 30 min – 1 h | Yes → owner + tier-2 |
-| One user blocked, no workaround | P2 | 1–2 h | Only if unresolved past target |
-| Question with a workaround, billing query | P3 | 4–8 h | No, unless policy claim is unverifiable |
-| FAQ, cosmetic, feature request | P4 | ~1 business day | No |
+The branch is at step 6. This table sets priority, both SLA clocks, and whether the ticket leaves your hands:
 
-**Why pick the FRT target before drafting:** the SLA decides your tone and length. A P1 gets a two-line acknowledgment in 20 minutes, not a polished essay in two hours.
+| Signal in the ticket | Priority | First response (FRT) | Resolution target | Escalate? |
+|---|---|---|---|---|
+| Production down / data loss / payments broken / many users blocked | P1 critical | 15–30 min | ASAP, status updates every 30–60 min | Yes → tier-2/eng + the packet |
+| Enterprise/VIP account, or "cancel / refund / lawyer / unacceptable" | P1–P2 | 30 min – 1 h | Same business day | Yes → owner + tier-2 |
+| One user blocked, no workaround | P2 high | 1–2 h | Same business day | Only if unresolved past target |
+| Question with a workaround, billing query | P3 medium | 4–8 h | 1–2 business days | No, unless policy claim is unverifiable |
+| FAQ, cosmetic, feature request | P4 low | ~1 business day | Best effort | No |
 
-## Priority and SLA
+**Why pick the FRT target before drafting:** the SLA decides your tone and length. A P1 gets a two-line acknowledgment in 20 minutes, not a polished essay in two hours.
 
 Use **3–4 priority tiers, never a flat SLA.** Too many tiers confuse the desk; too few don't differentiate the outage from the typo (Emailmeter / Hiver, 2026-06-02).
 
-| Priority | Meaning | First-response (FRT) | Resolution target |
-|---|---|---|---|
-| P1 critical | Outage, data loss, payments broken | 15–30 min | ASAP, status updates every 30–60 min |
-| P2 high | One user blocked, no workaround | 1–2 h | Same business day |
-| P3 medium | Workaround exists, billing/how-to | 4–8 h | 1–2 business days |
-| P4 low | Cosmetic, FAQ, feature request | ~1 business day | Best effort |
-
 **Acknowledge fast even when you cannot resolve fast.** First-response and resolution are *separate, linked* SLAs: FRT sets the expectation, resolution is the outcome. 89% of customers feel valued by a fast first response even when the full fix takes longer (getMonetizely / Hiver, 2026-06-02). So: acknowledge inside the FRT window with an honest "here's what I know and when I'll update you," then resolve honestly. Never go silent to wait for a perfect answer.
 
 Full P1–P4 matrix by channel (email/chat/phone) lives in [`references/macros-and-sla.md`](references/macros-and-sla.md).
@@ -126,6 +105,8 @@ Banned phrases — they escalate, not de-escalate:
 
 Checklist before send: feeling acknowledged · first-person ownership · one timed next step · no banned phrase · no `{{placeholder}}` left.
 
+De-escalating *this* ticket is the job here; running a win-back or renewal **program** is `retention`.
+
 ## Escalation
 
 Escalate on **explicit conditions, not vibes.** Standard tiers: T1 frontline/common, T2 specialist/complex, T3 engineering or exec/critical (Kapture / Hiver, 2026-06-02). Hand off when any trigger fires:
@@ -158,7 +139,7 @@ The full escalation matrix (trigger → tier → owner) is in [`references/macro
 - If it is not in the KB, say "let me confirm" and escalate — do not fill the gap with a plausible guess.
 - Deflection is **bounded by KB quality.** Triage-only without a strong KB deflects ~20–30%; well-organized KBs push assisted/auto resolution to 50–80% (Zendesk / Intercom / Fini Labs, 2026-06-02). A bad answer fast is worse than a correct answer slightly slower.
 
-If the article the customer needs does not exist, that is a `technical-writing` job — flag the gap, don't write the doc inside the ticket.
+This skill *consumes* the KB; it never writes it. If the article the customer needs does not exist, flag the gap — authoring it is a `technical-writing` job, and building the autonomous auto-answer bot on top of the KB is `chatbot` + `rag`.
 
 ## Metrics — what to watch and when
 
@@ -187,7 +168,3 @@ Rule of thumb: optimize **FRT** for reassurance (the customer feeling handled),
 | "Please calm down" / "as I said" | Tells them their feeling is the fault | De-escalation moves; banned-phrase swaps |
 | Promise a fix you can't verify | Breaks trust when it slips | Promise the *next update time*, not the fix |
 | Chase NPS off a single ticket | Wrong altitude metric | CSAT/FCR per ticket; NPS at relationship level |
-
-## References
-
-- [`references/macros-and-sla.md`](references/macros-and-sla.md) — the full macro skeleton library (10+ ready replies), the complete P1–P4 SLA matrix by channel, and the escalation matrix with the handoff-packet template. Pulled out because it is long, branch-specific lookup material you reach for mid-ticket, not flow you read top-to-bottom.

package/skills/dashboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dashboard
-description: "Use when building or fixing a KPI dashboard that decision-makers will actually open and act on within one screen — arranging which metrics earn a tile, framing each tile so it answers a decision at a glance, and picking the right chart per metric. Triggers: 'build a KPI dashboard for leadership', 'exec dashboard on one screen', 'nobody opens the dashboard we built', '20 tiles and I still can't tell if the business is healthy', 'which chart for each of these metrics', 'munta un dashboard de KPIs per a direcció amb el north-star a dalt', 'el dashboard tiene demasiados gráficos y nadie lo mira'. NOT defining the metrics or their targets (that is kpi-framework), wiring the data (that is analytics), or writing a narrative status report (that is reporting)."
+description: "Use when building or fixing a KPI dashboard decision-makers must read in one screen: which metrics earn a tile, how each tile is framed to answer a decision, and which chart fits it. NOT defining the metrics or their targets (that is kpi-framework), wiring the data (that is analytics), or writing a narrative status report (that is reporting)."
 tags: [kpi-dashboard, data-visualization, executive-dashboard, chart-selection, dashboard-design, at-a-glance]
 recommends: [kpi-framework, analytics, reporting, forecasting, business-intelligence, ab-testing, design, spreadsheet-ops]
 origin: risco
@@ -15,19 +15,11 @@ A dashboard is read in **5 seconds by someone who will not scroll**. If a busy r
 
 You do **not** decide which metrics matter (that is [kpi-framework](../kpi-framework/SKILL.md)) and you do **not** wire the data source (that is [analytics](../analytics/SKILL.md)). You take a metric set that already exists and make it readable at a glance.
 
-Run `scripts/verify.sh dashboard.yaml` before you hand off. It checks shape and discipline (tile budget, one north-star, required keys, banned charts) — never whether the numbers are correct.
-
-## The one rule: the 5-second read
-
-A dashboard is a **glance, not a report**. The reader looks at the top-left, gets the headline, and decides whether anything needs their attention. Everything you do serves that.
-
-- One north-star tile, read first, top-left. Why: a screen with no clear entry point forces the reader to hunt, and they won't.
-- If a tile does not change a decision, it is decoration. Cut it (Decision Test below).
-- A bare number is not actionable. Every number carries a comparison.
+Run `scripts/verify.sh dashboard.yaml` before you hand off. It checks shape and discipline — tile count 1-9, exactly one `north_star: true`, the required keys on every tile, no banned charts — never whether the numbers are correct.
 
 ## The Decision Test gate
 
-No tile exists until its metric names the **action it drives**. Ask: *what does someone do differently based on this number?* If the answer is vague ("good to know", "shows we're growing"), the metric is vanity — cut it or convert it.
+No tile exists until its metric names the **action it drives**. Ask: *what does someone do differently based on this number?* If the answer is vague ("good to know", "shows we're growing"), the metric is vanity — cut it or convert it. A tile that changes no decision is decoration.
 
 | Vanity metric (Bad) | Actionable conversion (Good) | Decision it drives |
 | --- | --- | --- |
@@ -94,12 +86,7 @@ Choose the chart from the **shape of the question**, not from what looks impress
 | Correlation | Scatter | Shows relationship between two measures |
 | Distribution | Histogram | Shape of spread, not just average |
 
-Kill-list (verify.sh enforces the first two):
-
-- No `pie` beyond 5 categories — slices become unreadable. Use a sorted bar.
-- No `gauge` / `dial` — they waste space and resist comparison. Use a **bullet chart**.
-- No dual-axis trickery — two y-axes invent correlations that aren't there.
-- No 3D, no donut-with-center-number gimmicks.
+Kill-list: no `pie` beyond 5 categories (sorted bar instead) and no `gauge` / `dial` (bullet chart instead) — verify.sh rejects both; no dual-axis, which invents correlations that aren't there; no 3D and no donut-with-center-number gimmicks.
 
 ## Layout & data-ink
 
@@ -177,7 +164,7 @@ layout:
   groups: [growth, revenue, health]
 ```
 
-verify.sh parses this, counts tiles (must be 1-9), checks exactly one `north_star: true`, requires `metric/chart/comparison/owner/refresh/decision` on every tile, and rejects banned charts.
+The keys verify.sh requires on every tile: `metric`, `chart`, `comparison`, `owner`, `refresh`, `decision`.
 
 ## Anti-patterns
 
@@ -195,11 +182,4 @@ verify.sh parses this, counts tiles (must be 1-9), checks exactly one `north_sta
 
 ## Handoff
 
-- Metrics undefined? Define the north-star, metric tree, targets and owners first → [kpi-framework](../kpi-framework/SKILL.md).
-- No data behind the tiles? Instrument events, funnels, attribution → [analytics](../analytics/SKILL.md).
-- Need a written status with commentary on *why* a number moved → [reporting](../reporting/SKILL.md).
-- Projecting a metric forward under scenarios → [forecasting](../forecasting/SKILL.md).
-- Self-serve slice-and-dice / semantic layer → [business-intelligence](../business-intelligence/SKILL.md).
-- Reading out an experiment / variant significance → [ab-testing](../ab-testing/SKILL.md).
-- Visual polish, spacing, type scale of the rendered screen → [design](../design/SKILL.md).
-- Pulling/joining the underlying numbers in a sheet → [spreadsheet-ops](../spreadsheet-ops/SKILL.md).
+Beyond the routes named above: reading out an experiment or variant significance → [ab-testing](../ab-testing/SKILL.md); visual polish, spacing and type scale of the rendered screen → [design](../design/SKILL.md); pulling or joining the underlying numbers in a sheet → [spreadsheet-ops](../spreadsheet-ops/SKILL.md).

package/skills/data-cleaning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-cleaning
-description: "Use when a raw dataset is too dirty to trust — nulls and sentinels (-1, 999, \"N/A\"), duplicate rows, inconsistent categories (USA / U.S. / United States), mixed types in one column, junk whitespace/encoding, out-of-range numbers or malformed dates — and you need it cleaned the same way every time, with a schema that fails loud on bad input. Triggers: 'clean and dedupe this CSV', 'normalize these messy categories', 'why did my integer column turn into floats', 'build a repeatable cleaning pipeline', 'add a validation gate before this feeds my model', 'quarantine the bad rows instead of dropping them', 'limpiar y deduplicar este dataset', 'normalitzar dades brutes abans d''analitzar', 'mis fechas se parsean mal y unas filas se duplican'. NOT producing or repairing a spreadsheet/formula/.xlsx (that is spreadsheet-ops), NOT scraping rows off a website (that is data-scraper), NOT parsing fields out of PDFs/HTML (that is structured-extraction)."
+description: "Use when a raw table is too dirty to trust — nulls, sentinels, duplicate rows, category sprawl, mixed types, bad dates — and you need a re-runnable clean() plus a schema gate that fails loud. NOT emitting .xlsx (that is spreadsheet-ops), NOT acquiring rows (that is data-scraper), NOT parsing PDF/HTML into rows (that is structured-extraction)."
 tags: [data-cleaning, data-quality, pandas, pandera, validation, deduplication, reproducibility, polars]
 recommends: [duckdb, spreadsheet-ops, structured-extraction, data-scraper, analytics, business-intelligence, forecasting, python]
 profiles: []
@@ -16,28 +16,17 @@ the same input always yields the same output: versions pinned, sorts determinist
 a seed. If you can't re-run it tomorrow and get the identical result, you haven't cleaned the data — you've
 edited a snapshot.
 
-Current stack (verified 2026-06-02): **pandas 3.0.x** (3.0.0 shipped 2026-01-21). Two 3.0 facts shape how you
-read and assert: the default `str` dtype is **PyArrow-backed when PyArrow is installed, NumPy-object-backed
-otherwise** (PDEP-14 deliberately kept the object fallback to avoid a hard PyArrow dependency — PyArrow is
-*recommended, not required*), and the new string dtype uses **`NaN` missing-value semantics** like every other
-default dtype, so test for null with `pd.isna()`, not by comparing against a specific token. Install PyArrow
-to get the faster backed path. **pandera 0.31.1** (supports pandas ≥ 3) for in-pipeline schema validation.
-**Polars** and **DuckDB** when pandas runs out of RAM. Pin them: `pandas==3.0.3`, `pandera==0.31.1`.
+Cleaning **starts** once you hold tabular rows and **ends** at a validated table/DataFrame/Parquet. Before
+that boundary the job is acquisition ([`data-scraper`](../data-scraper/SKILL.md),
+[`structured-extraction`](../structured-extraction/SKILL.md)); after it, consumption
+([`spreadsheet-ops`](../spreadsheet-ops/SKILL.md), [`analytics`](../analytics/SKILL.md),
+[`business-intelligence`](../business-intelligence/SKILL.md),
+[`forecasting`](../forecasting/SKILL.md)). Multi-GB analytical SQL is an engine choice, not a cleaning one
+— [`duckdb`](../duckdb/SKILL.md).
 
-## Do you need this skill? (decide first)
-
-| Your situation | Reach for |
-| --- | --- |
-| Rows are dirty (nulls, dupes, mixed types, bad dates) and you want a re-runnable clean + a gate | **data-cleaning** (this skill) |
-| You need an `.xlsx` / formula / styled sheet / chart *out* | [`spreadsheet-ops`](../spreadsheet-ops/SKILL.md) |
-| The data is still on a website — you have to *acquire* it | [`data-scraper`](../data-scraper/SKILL.md) |
-| Fields are trapped in PDF/HTML/free text and must be *parsed into rows* | `structured-extraction` |
-| Multi-GB analytical SQL / heavy groupby-join is the actual bottleneck | [`duckdb`](../duckdb/SKILL.md) |
-| The table is already clean and you want charts / KPIs / a model | [`analytics`](../analytics/SKILL.md), `business-intelligence`, `forecasting` |
-
-Cleaning **starts** once you hold tabular rows and **ends** at a validated table/DataFrame/Parquet. The
-boundary with every consumer sibling is that validated table. (Some routed siblings may not be built in
-this collection yet; the routing decision still holds.)
+Current stack (verified 2026-06-02): **pandas 3.0.x** (3.0.0 shipped 2026-01-21) and **pandera 0.31.1**
+(supports pandas ≥ 3) for in-pipeline schema validation; **Polars** and **DuckDB** when pandas runs out of
+RAM. Pin them: `pandas==3.0.3`, `pandera==0.31.1`.
 
 ## The pipeline shape
 
@@ -73,18 +62,19 @@ df = pd.read_csv("raw.csv")
 # GOOD — explicit, deterministic, real nullable types
 df = pd.read_csv(
     "raw.csv",
-    dtype_backend="pyarrow",          # real nullable ints/strings; no silent float-cast — REQUIRES pyarrow installed; use "numpy_nullable" if it isn't
+    dtype_backend="pyarrow",          # real nullable ints/strings; no silent float-cast
     na_values=["", "N/A", "NA", "null", "-1", "999"],  # YOUR sentinels become real NA
     keep_default_na=True,             # keep pandas' default NA tokens too
     encoding="utf-8",                 # state it; don't let locale decide
 )
 ```
 
-pandas 3.0 notes that matter here: `dtype_backend="pyarrow"` only works if pyarrow is actually installed —
-it's recommended but *not* a hard pandas dependency, so install it (`pip install pyarrow`) or fall back to
-`dtype_backend="numpy_nullable"` when it's absent. The default `str` dtype is PyArrow-backed when pyarrow is
-present and NumPy-object-backed otherwise, but either way it uses `NaN` missing-value semantics — so assert
-nullability with `pd.isna()`, never by comparing against which null token appeared.
+Two pandas 3.0 facts that read depends on. `dtype_backend="pyarrow"` only works if pyarrow is actually
+installed — PDEP-14 deliberately kept a NumPy-object fallback so PyArrow stays *recommended, not required*
+— so `pip install pyarrow` for the faster backed path, or pass `dtype_backend="numpy_nullable"` when it is
+absent. And the default `str` dtype (PyArrow-backed when pyarrow is present, NumPy-object-backed otherwise)
+uses **`NaN` missing-value semantics** like every other default dtype: test for null with `pd.isna()`, never
+by comparing against whichever null token happened to appear.
 
 ## Profile before you fix
 
@@ -146,6 +136,10 @@ assert bad.sum() == 0, f"{bad.sum()} dates failed the expected format — inspec
 df["signup"] = parsed
 ```
 
+Copy-paste versions of all of these — category mapping with unmapped→quarantine, a robust date parser,
+unicode/encoding repair, a sentinel→NA table, numeric clip-vs-reject, plus Polars equivalents — are in
+[references/normalization-recipes.md](references/normalization-recipes.md).
+
 ## Dedupe
 
 `drop_duplicates(keep="first")` is meaningless without a defined key and a stable sort — "first" of what
@@ -210,14 +204,16 @@ except pa.errors.SchemaErrors as e:
 
 `coerce=True` fixes types the contract expects; `nullable` states which columns may hold NA; field
 `Check`s (`ge`, `le`, `isin`, `unique`) are the allowed-value rules. `strict` catches columns that
-shouldn't be there. Together they are the data contract in code.
+shouldn't be there. Together they are the data contract in code. Log the row-count diff on every run —
+`in`, `out`, coerced, quarantined — so what the pipeline changed is an auditable record, not an assumption.
 
 When to escalate beyond pandera: reach for **GX Core 1.0** (Great Expectations' rebranded OSS — Data
 Context → Data Source → Expectation Suite → Validation Definition → Checkpoint) when you need a *shared
 data-quality platform* across many datasets and teams with a results store and docs. Use **dbt model
 contracts** (enforced at build) plus **dbt tests** (post-materialization) when the cleaning lives in a
-SQL warehouse, not Python. Full pandera patterns, the GX checkpoint sketch, the dbt YAML, and the
-"which validator" chooser are in [references/validation-patterns.md](references/validation-patterns.md).
+SQL warehouse, not Python. The full `DataFrameModel` (custom `@pa.check`, lazy `SchemaErrors` report,
+valid/quarantine split helper), the GX checkpoint sketch, the dbt model-contract + `data_tests` YAML, and
+the "which validator" chooser are in [references/validation-patterns.md](references/validation-patterns.md).
 
 ## Scale — when pandas hurts
 
@@ -226,28 +222,15 @@ that, or when a groupby/join dominates the runtime, switch the *mechanics* (not
 
 - **Polars** for clean-at-scale: `pl.scan_csv(...)` (lazy, parallel, Rust), then `.unique()`,
   `.drop_nulls()`, `.fill_null(...)`, `.str.*` — the same profile→normalize→dedupe→validate shape, faster.
-  pandera validates Polars frames too.
+  pandera validates Polars frames too, and the
+  [recipes reference](references/normalization-recipes.md) has the Polars equivalent of every fix above.
 - **DuckDB** when the bottleneck is analytical SQL over multi-GB files — point heavy joins/aggregations
   there: [`duckdb`](../duckdb/SKILL.md). It is an *engine* choice; correctness/normalization is still this
   skill's job.
 
-Polars equivalents for every recipe above are in
-[references/normalization-recipes.md](references/normalization-recipes.md).
-
-## Reproducibility checklist
-
-- [ ] Library versions pinned (`pandas==3.0.3`, `pandera==0.31.1`) — same input → same output.
-- [ ] Read with explicit `dtype_backend` + `na_values`; no silent int→float cast.
-- [ ] Dedupe has an explicit `subset` key AND a deterministic `sort_values(..., kind="stable")` before it.
-- [ ] No `random` / sampling without a fixed seed; stable tie-breaks everywhere.
-- [ ] Raw source untouched; output written to a NEW artifact.
-- [ ] Schema validated on output; `lazy=True` so all violations surface together.
-- [ ] Failing rows **quarantined**, not silently dropped.
-- [ ] Row-count diff logged (`in`, `out`, coerced, quarantined) — an auditable record of what changed.
-
 ## Anti-patterns
 
-| Rationalization | Reality → STOP |
+| Anti-pattern | Why it breaks |
 | --- | --- |
 | "`fillna(0)` to get rid of the nulls" | Zero is a value; it distorts every mean/sum/model. Impute deliberately and add a `_was_missing` flag. |
 | "`drop_duplicates()` — done" | No `subset`, no sort → which row survives is nondeterministic. Define the key, `sort_values(kind="stable")`, set `keep`. |
@@ -259,27 +242,18 @@ Polars equivalents for every recipe above are in
 | "Validation passed, so we're good" | A gate that never fails is a no-op. Feed it a known-bad row and confirm it *rejects*. |
 | "It's slow, rewrite everything in Polars" | Switch the engine, not the discipline — profile→normalize→dedupe→validate still applies. |
 
-## References
-
-- [references/validation-patterns.md](references/validation-patterns.md) — full pandera `DataFrameModel`
-  (coerce, custom `@pa.check`, lazy `SchemaErrors` report, valid/quarantine split helper), GX Core 1.0
-  checkpoint sketch, dbt model-contract + `data_tests` YAML, and the "which validator" chooser.
-- [references/normalization-recipes.md](references/normalization-recipes.md) — copy-paste recipes: category
-  mapping with unmapped→quarantine, robust date parser, unicode/encoding repair, sentinel→NA table, numeric
-  clip-vs-reject, and Polars equivalents (`unique`, `drop_nulls`, `fill_null`, `str.*`) for scale.
-
 ## Verify
 
-Run `scripts/verify.sh` from anywhere. It does static structure checks on this skill (frontmatter keys,
-references present) always, and — when pandas + pandera are installed — extracts the documented pattern,
-feeds it one clearly-good row and one clearly-bad row, and asserts the good row PASSES validation while the
-bad row is FLAGGED/quarantined, proving the gate is not a no-op. If pandas/pandera aren't installed it
-prints SKIP for the runtime check and still passes the static checks. No network.
+`scripts/verify.sh` runs from anywhere, no network. It does static structure checks on this skill
+(frontmatter keys, references present) always, and — when pandas + pandera are installed — extracts the
+documented pattern, feeds it one clearly-good row and one clearly-bad row, and asserts the good row PASSES
+validation while the bad row is FLAGGED/quarantined, proving the gate is not a no-op. Without
+pandas/pandera it prints SKIP for the runtime check and still passes the static checks.
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
 In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), record this dataset's
 cleaning decisions — the schema/contract, the category mapping tables, the dedupe key, the quarantine
-location, version pins — in `02-DOCS/wiki/data/<dataset>.md` and link it from the root `CLAUDE.md`
-`## Knowledge map`. Read it first on every re-run so the contract stays consistent. No `02-DOCS/`? Skip
+location, version pins — in `02-DOCS/wiki/data/<dataset>.md`, link it from the root `CLAUDE.md`
+`## Knowledge map`, and read it first on every re-run so the contract stays consistent. No `02-DOCS/`? Skip
 silently. Conventions are recorded, never gated.

package/skills/data-policy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-policy
-description: "Use when an operator needs the internal data-governance machinery a business runs on — a retention schedule (how long each data category is kept and what happens at expiry), the lawful basis per activity, a Record of Processing Activities (ROPA), or a consent capture/withdrawal model; symptoms include 'how long can we keep this', a paper policy that never runs in systems, or data still in backups past its retention. Triggers: 'write our data retention policy', 'how long can we keep customer/HR/support/log data', 'set up a ROPA', 'lawful basis consent or legitimate interest', 'design our consent capture and withdrawal flow', 'auto-deletion with legal-hold exceptions', 'we delete from prod but backups still have it', 'política de conservación de datos', 'cuánto tiempo guardamos los datos'. NOT the public-facing privacy notice or DSAR handling (that is gdpr-privacy), NOT SOC 2 audit posture (that is compliance), and NOT the database TTL/partition-drop mechanics (that is db-migrations)."
+description: "Use when building internal data-governance machinery: a retention schedule (period, lawful basis, expiry action, system where deletion runs), an Art. 6 lawful-basis register, an Art. 30 ROPA, or a consent capture/withdrawal model. NOT the public privacy notice or DSAR handling (that is `gdpr-privacy`), NOT SOC 2 posture (that is `compliance`)."
 tags: [data-governance, retention, gdpr, ropa, consent, lawful-basis, privacy, data-minimization]
 recommends: [gdpr-privacy, compliance, contracts, secure-coding, db-migrations, postgresdb]
 origin: risco
@@ -8,9 +8,7 @@ origin: risco
 
 # Data policy
 
-You build the **internal governance machinery** a business runs on: a retention schedule, a lawful-basis register, a Record of Processing Activities (ROPA), and a consent model. You produce structured artifacts that engineering and ops can implement — not the public-facing privacy notice users read (that is `../gdpr-privacy/SKILL.md`). You are not a DPO and you never claim to be one.
-
-One rule sits above everything else.
+You produce the structured governance artifacts engineering and ops implement — a retention schedule, a lawful-basis register, a Record of Processing Activities (ROPA), a consent model — not the public-facing notice users read (that is `../gdpr-privacy/SKILL.md`). You are not a DPO and you never claim to be one.
 
 **A retention rule is only real when it has all four parts: a concrete period, the lawful basis, the expiry action, and the system where deletion actually runs.** A policy that names a period but never deletes anything is a paper policy — and a paper policy is precisely what regulators fine. Cumulative GDPR fines hit ~EUR 5.65B across ~2,245 actions by March 2025, and the two failures that recur are *no systematic data classification* and *no automated deletion capability* (Secure Privacy / CMS Enforcement Tracker, 2025). Every schedule you emit ends with the DPO/counsel sign-off boundary below.
 
@@ -26,7 +24,7 @@ Map the request to one artifact before writing anything. Each routes to a sectio
 | "Design consent capture / withdrawal" | Consent matrix | Consent model |
 | "Auto-delete but keep legal holds / backups still have data" | Deletion workflow | Make it real in systems |
 
-If the operator wants the public privacy notice, the DPA contract clauses, or SOC 2 readiness, stop and route them — see the boundary section. Those are different skills.
+If they want the public privacy notice, DPA clauses, or SOC 2 readiness instead, stop and route them — see the boundary below.
 
 ## Build the retention schedule
 
@@ -88,7 +86,7 @@ Security:    RBAC, encryption at rest, access logging
 Lawful basis: Art. 6(1)(b) contract  ← log it even though Art. 30 doesn't demand it
 ```
 
-The full template with a second worked row is in `references/consent-and-ropa.md`.
+The full ROPA template with a second worked row — plus the consent-matrix template and the withdrawal/refresh workflow — is in `references/consent-and-ropa.md`.
 
 ## Consent model
 
@@ -109,7 +107,7 @@ One note so you don't over-promise on cookies: the **ePrivacy Regulation was for
 
 ## Make it real in systems
 
-This is the section that earns the skill. The policy is worthless until deletion runs in the systems that actually hold the data — *including backups and archives*, which is exactly where regulators find data that should be gone.
+The policy is worthless until deletion runs in the systems that actually hold the data — *including backups and archives*, which is exactly where regulators find data that should be gone.
 
 Checklist:
 
@@ -134,17 +132,11 @@ State explicitly in the policy whether production data may be reused for **AI/mo
 
 For cross-border transfers, name the mechanism in the ROPA row (e.g. SCCs) and point to `../gdpr-privacy/SKILL.md` for the SCC/notice depth — that is its territory, not yours.
 
-## The boundary (non-negotiable)
-
-Retention periods are jurisdiction- and sector-specific. **You produce governance drafts, not legal sign-off.** Every policy you emit ends with a line stating a qualified DPO or privacy counsel must validate the schedule and lawful-basis register before adoption, and that this is not legal advice. You never assert a period is universally lawful.
+## The boundary
 
-Hand off the edges:
+Retention periods are jurisdiction- and sector-specific, so a period you assert as final is legal advice you are not qualified to give — that is why this line has no exceptions. **You produce governance drafts, not legal sign-off.** Every policy you emit ends with a statement that a qualified DPO or privacy counsel must validate the schedule and lawful-basis register before adoption, and that this is not legal advice. You never assert a period is universally lawful.
 
-- Public-facing privacy notice + data-subject access/erasure (DSAR) handling -> `../gdpr-privacy/SKILL.md`.
-- Audit posture, SOC 2 / ISO 27001, control mapping -> `../compliance/SKILL.md`.
-- A negotiated DPA's contractual clauses or a two-party data contract -> `../contracts/SKILL.md`.
-- Encryption, access hardening, threat controls on the systems -> `../secure-coding/SKILL.md`.
-- The actual deletion mechanics in the database -> `../db-migrations/SKILL.md` / `../postgresdb/SKILL.md`.
+Hand off the edges: public-facing privacy notice + data-subject access/erasure (DSAR) handling -> `../gdpr-privacy/SKILL.md`; audit posture, SOC 2 / ISO 27001, control mapping -> `../compliance/SKILL.md`; a negotiated DPA's contractual clauses or a two-party data contract -> `../contracts/SKILL.md`; encryption, access hardening, threat controls on the systems -> `../secure-coding/SKILL.md`; the actual deletion mechanics in the database -> `../db-migrations/SKILL.md` / `../postgresdb/SKILL.md`.
 
 ## Anti-patterns
 
@@ -156,8 +148,3 @@ Hand off the edges:
 | No legal-hold exception in the auto-deletion job | The job destroys data under litigation hold — spoliation | Flag held rows; skip them; document the hold basis |
 | Copy a generic retention template unchanged | Periods are jurisdiction/sector-specific; a copied period can be unlawful | Tag every period "validate vs local + sector law"; adjust |
 | Emit the policy as final / "compliant" | Crosses into legal advice you can't give | End with DPO/counsel sign-off + not-legal-advice line |
-
-## References
-
-- `references/retention-schedule.md` — fillable schedule template (data category, purpose, lawful basis, period, expiry action, system of record, legal-hold flag, review date) + a populated example across HR, finance/tax, CRM, marketing, support, logs, with the delete-vs-anonymize-vs-archive note and the local + sector law validation checklist.
-- `references/consent-and-ropa.md` — consent matrix template + worked example, the Art. 30 ROPA template + worked rows, the legitimate-interest balancing-test worksheet, and the consent withdrawal/refresh workflow.

package/skills/data-scraper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-scraper
-description: "Use when you need data that lives on a website with no usable API — listings, prices, public records, directories — and the scrape must stay legal and not get blocked. Triggers: 'scrape this site', 'extract data from a webpage', 'build a crawler', 'pull all the prices off this catalog', 'my scraper keeps getting 429s / IP-banned', 'the selectors break every time the site redesigns', 'is it legal to scrape this without getting sued', 'extreure dades d'una web', 'scrapear una página sin que me bloqueen'. NOT parsing HTML/PDF you already have into fields (that is structured-extraction), NOT a site that already exposes a documented API or key (that is api-connector-builder)."
+description: "Use when data lives on a website with no usable API — listings, prices, public records — and the scrape must stay legal and not get blocked: legal gate, extraction path, durable selectors, pacing, resilience. NOT parsing bytes you already hold into fields (that is structured-extraction), NOT a documented API or key (that is api-connector-builder)."
 tags: [web-scraping, crawler, anti-bot, robots-txt, gdpr-compliance, playwright, rate-limiting]
 recommends: [api-connector-builder, structured-extraction, data-cleaning, gdpr-privacy, webhooks]
 origin: risco
@@ -125,10 +125,4 @@ A recurring crawler must survive crashes, redeploys, and the target's schema dri
 | Hardcoding one User-Agent forever | Stale UA is an easy bot tell | Current full header set; rotate when justified |
 | Retrying with no backoff | Lockstep retries self-DDoS the host | Exponential backoff + jitter; honor `Retry-After` |
 
-## References
-
-- **`references/legal-compliance.md`** — robots.txt + ai.txt parsing, ToS red-flag list, GDPR lawful-basis decision flow, minimization/retention checklist, and the 2024-2025 case summaries (Meta v. Bright Data, hiQ v. LinkedIn, Reddit v. Perplexity).
-- **`references/anti-bot.md`** — `curl_cffi` impersonation profiles with an example, realistic header sets, Playwright launch/stealth config, the proxy taxonomy (datacenter / residential / mobile) and when each is justified, and the CAPTCHA line you do not cross.
-- **`references/frameworks.md`** — copy-paste resilient starters: Crawlee Python (`RequestQueue` + router + per-host concurrency), Playwright direct, Scrapy AUTOTHROTTLE, and an `httpx` + `selectolax` static template.
-
 When in doubt about whether a scrape is defensible, the answer is the gate. Run it, write down the outcome, and only then send a request.