@ericrisco/rsc 0.1.43 → 0.1.45

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.

package/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: "Use when something is broken and the impulse is to start patching — a bug, a failing or flaky test, a crash, an exception, a wrong result, a regression, or behavior nobody can explain — and you want the root cause found BEFORE any fix is proposed. The on-demand rsc-sdd diagnosis discipline, callable from inside implement (or any phase) the moment a check fails for a reason you don't understand. Triggers: 'debug this', 'why is this failing', 'this test is flaky', 'find the root cause', 'it works locally but not in CI', 'this used to work', 'track down this bug', 'the fix didn't stick', 'figure out why', 'NullPointer/segfault/500 out of nowhere', 'intermittent failure'. Fixes the ONE confirmed cause, then hands back. NOT writing a planned feature (that is `implement`), NOT the lint/test gate (that is `verify`), NOT adversarial diff reading (that is `review`). Honors the harness accompaniment dial."
+description: "Use when something is broken — a failing or flaky test, crash, wrong result or regression — and the root cause must be reproduced and proven before any fix. On-demand; callable mid-`implement`. NOT a feature to spec or build (that is `specify`/`implement`), NOT the lint/test gate (that is `verify`), NOT adversarial diff reading (that is `review`)."
 tags: [debug, bug, troubleshoot]
 recommends: []
 profiles: [core, full]
@@ -20,31 +20,9 @@ The one rule everything else serves: **no fix before a reproduced, isolated, con
 you cannot make the bug happen on demand, you cannot know you fixed it — you can only know the
 symptom stopped showing, which is not the same thing.
 
-This is a process skill. It does not own the test runner, the debugger, or the profiler — the
-**stack skills do** (`../fastapi/SKILL.md`, `../go/SKILL.md`, `../nextjs/SKILL.md`,
-`../flutter/SKILL.md`; data-layer issues `../postgresdb/SKILL.md`; security-shaped failures
-`../secure-coding/SKILL.md`). `debug` owns the *method*; it pulls the *mechanics* from whichever
-stack the failure lives in.
-
-## When to use / when not to
-
-Use when:
-
-- A test fails (or flakes) for a reason you don't fully understand, mid-`implement` or after.
-- A crash, exception, 500, segfault, or wrong output appears and nobody can yet say why.
-- A regression shows up ("this used to work") and you need the commit/change that caused it.
-- A fix was applied and the symptom came back, or a "fix" didn't actually stick.
-- The behavior differs between environments ("works locally, fails in CI").
-
-Do NOT use when:
-
-- You're writing a *planned* feature task and its expected failing test — that's `implement`'s
-  red→green→refactor; no mystery yet.
-- You're running the lint/type/test gate to confirm "done" — that's `verify` (it *reports* failures
-  and hands them here; it doesn't diagnose).
-- You're reading a clean diff adversarially for smells a test can't catch — that's `review`.
-- The "bug" is actually an unclear requirement or contradictory spec — that's `clarify`/`analyze`,
-  not a code defect.
+This is a process skill: it owns the *method*, never the instruments. The test runner, debugger,
+race detector and profiler belong to whichever stack the failure lives in — pull them from the
+delegation table below.
 
 ## Model tier — `heavy` (opt-in routing)
 
@@ -53,7 +31,9 @@ This phase's default model tier is **`heavy`** — root-cause diagnosis is deep
 ## Read the room first (accompaniment dial)
 
 Before diagnosing, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment
-level and match it. The *method* never changes with the dial — the volume does.
+level and match it; with no profile yet, assume non-technical — narrate the reasoning plainly and
+never apply a behavior-changing fix without a quick confirm. The *method* never changes with the
+dial — the volume does.
 
 | Level | While diagnosing you show… | Questions you ask |
 | --- | --- | --- |
@@ -62,10 +42,7 @@ level and match it. The *method* never changes with the dial — the volume does
 | **L2** decisions | each step's finding (repro, the half that isolated it, the cause) | confirm before a fix that changes behavior beyond the bug |
 | **L3** full | narrate the whole loop, teach the binary-search reasoning aloud | ask to contextualize the environment, recent changes, expectations |
 
-No profile yet → assume non-technical, narrate the reasoning plainly, and never apply a
-behavior-changing fix without a quick confirm.
-
-## The loop — five steps, in order
+## The loop — five steps, never skipped, never reordered
 
 ```text
 REPRODUCE   → make the bug happen on demand. A reliable repro (or a quantified flake rate) is the
@@ -84,11 +61,6 @@ VERIFY      → re-run the repro: symptom gone. Re-run the new test: green. Re-r
               dropped to zero. Only now is it fixed.
 ```
 
-Never skip a step and never reorder. **Reproduce before isolate** — you can't bisect a bug you can't
-trigger. **Hypothesize before fix** — an edit with no stated cause is a guess wearing a commit
-message. **Verify before "fixed"** — the word *fixed* is a claim about the repro no longer firing
-and the test being green, nothing less.
-
 ### Reproduce — the entry ticket
 
 A bug you cannot reproduce is not a bug you can fix; it's a rumor. Pin it down:
@@ -169,9 +141,9 @@ Why missed — what let it through, so the class of bug doesn't recur
 
 Skip the trivial ones (a typo'd variable). Log the cause a future debugger would pay to know.
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Why it fails |
 | --- | --- |
 | "I see the likely line — let me just change it and see." | That's guess-and-patch. Reproduce first; a fix to an untriggered bug proves nothing. |
 | "It's intermittent, you can't really reproduce it." | "Intermittent" is a rate to measure (k/N), not an excuse. Flakes have causes: state, order, races, time. |
@@ -185,8 +157,6 @@ Skip the trivial ones (a typo'd variable). Log the cause a future debugger would
 
 ## Red flags — stop and re-route
 
-- **You're editing code and you can't yet reproduce the bug** → stop; you're guessing. Get a repro
-  (or a measured flake rate) first.
 - **The "bug" is a spec contradiction or unclear requirement**, not a defect → route to
   `clarify` / `analyze`; debugging won't fix an ambiguity.
 - **The fix grows past the cause** (you're refactoring "while you're here") → split it out; keep the
@@ -210,15 +180,6 @@ Skip the trivial ones (a typo'd variable). Log the cause a future debugger would
 - [ ] Handed the whole-gate re-run back to verify; resumed implement where the failure interrupted it
 ```
 
-## What this skill is NOT
-
-- **Not the feature builder.** Once the cause is fixed and verified, planned work resumes in
-  `implement` (its red→green→refactor for the *next* task, not this bug).
-- **Not the quality gate.** The lint/type/full-suite/audit run that licenses "done" is `verify`'s
-  job; `debug` proves the one bug dead and hands the gate back.
-- **Not a refactor pass.** Keep the fix minimal; broader cleanups are `implement`/`review` territory,
-  not smuggled into a bugfix.
-
 ## Where you are in the chain
 
 `debug` is **on-demand**, callable from any phase — most often pulled in mid-`implement` when a test