@ericrisco/rsc 0.1.50 → 0.1.52

package/skills/hiring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hiring
-description: "Use when there's an open role and you need to write the job post, screen inbound candidates, structure the interview loop, or build a scorecard to reach a fair hire decision; symptoms: gut-feel ratings, every interviewer asking the same question, a bloated requirements list, no consistent screen. Triggers: 'write a job description', 'screen these CVs', 'build an interview scorecard', 'structure the interview panel', 'redacta la oferta de empleo', 'necesito una scorecard', plus the non-obvious 'four people interviewed and we still can't decide' and 'is our AI résumé filter legal'. NOT managing the person after they're hired — onboarding, payroll, performance (that is people-ops)."
+description: "Use when a role is open and you must write the job post, screen inbound candidates, structure the interview loop, or score them to a defensible Hire / On-Hold / No-Hire — including whether an AI résumé filter is legal. NOT after the offer is accepted — onboarding, payroll, performance (that is `people-ops`), NOT offer terms (that is `contracts`)."
 tags: [hiring, recruiting, job-description, interview-scorecard, candidate-screening, structured-interview]
 recommends: [people-ops, brand-voice, contracts, compliance, cold-outreach, calendar-scheduling]
 profiles: []
@@ -17,8 +17,7 @@ No-Hire with the reason written down.
 
 Hard boundary: the moment the offer is accepted, you are done. Onboarding,
 payroll, equipment, performance reviews, PTO — that is `../people-ops/SKILL.md`.
-Hiring gets the right person in the door; people-ops takes it from day one. Do
-not draft offer-letter terms here either; that is `../contracts/SKILL.md`.
+Do not draft offer-letter terms here either; that is `../contracts/SKILL.md`.
 
 ## The funnel (the spine)
 
@@ -35,7 +34,7 @@ One rule per stage, with the why:
   named. Write the 3–6 competencies before the post, because they drive the
   post, the questions, and the scorecard.
 - **Write the post from the competencies.** A post is the competencies turned
-  outward, not a wish list. See "Write the job post".
+  outward, not a wish list.
 - **Screen against one rubric.** Same criteria, same order, every candidate, or
   the comparison is meaningless.
 - **Run a structured loop.** Same questions, same rubric, every candidate —
@@ -45,18 +44,6 @@ One rule per stage, with the why:
 - **Score independently, then calibrate.** Each interviewer submits before the
   group talks. Debrief is calibration, not a re-vote.
 
-### Screen decision table
-
-For each candidate at the screen stage:
-
-| Signal | Decision |
-|---|---|
-| Meets the must-haves on job-related evidence | Advance to loop |
-| Strong on most, one must-have unclear | Send a short work-sample / structured task to resolve it |
-| Misses a hard must-have (verified skill, legal eligibility) | Reject, with the job-related reason logged |
-| Borderline, more reqs open soon | Parking lot — note why, revisit, do not silently ghost |
-| Non-job factor (school name, age, gap, "vibe", name) | Ignore it — it is not in the rubric |
-
 ## Write the job post
 
 The job post is the top of the funnel and it leaks candidates if you write it
@@ -102,7 +89,8 @@ How to apply: send a short note + anything you've shipped.
 ## Screen the pile
 
 Score every applicant against the **same job-related rubric** you derived from
-the competencies. No bespoke criteria per candidate.
+the competencies (template: `references/templates.md`). No bespoke criteria per
+candidate.
 
 - **Blind to non-job factors.** School prestige, name, age, employment gaps,
   photo — none of it is in the rubric, so it does not enter the decision.
@@ -116,8 +104,15 @@ the competencies. No bespoke criteria per candidate.
   criminal-history box on the application form. (Candidate-data retention and
   consent: `../gdpr-privacy/SKILL.md`.)
 
-Use the screen decision table above for the advance / work-sample / reject /
-parking-lot call.
+For each candidate, the call:
+
+| Signal | Decision |
+|---|---|
+| Meets the must-haves on job-related evidence | Advance to loop |
+| Strong on most, one must-have unclear | Send a short work-sample / structured task to resolve it |
+| Misses a hard must-have (verified skill, legal eligibility) | Reject, with the job-related reason logged |
+| Borderline, more reqs open soon | Parking lot — note why, revisit, do not silently ghost |
+| Non-job factor (school name, age, gap, "vibe", name) | Ignore it — it is not in the rubric |
 
 ## Structure the interview loop
 
@@ -239,10 +234,3 @@ This skill *follows* the rules; it does not run the legal program — that is
 | Screening on school / name / gap | Non-job factor, not in the rubric | Blind to it; rubric only |
 | Deleting interview notes | Breaks EEOC retention; no defense | Retain ≥1 yr (2 yr for fed contractors) |
 | Drifting into onboarding/payroll | Out of scope, wrong skill | Stop at the decision → `../people-ops/SKILL.md` |
-
-## References
-
-- `references/templates.md` — full anchored scorecard (one competency at all
-  five levels), the structured question bank by competency, a fill-in job-post
-  skeleton with the gender-coded word do/don't list, and a screening rubric
-  template.

package/skills/instagram-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: instagram-api
-description: "Use when wiring an agent into Instagram's Graph API to publish a Reel from a video URL, pull per-media insights (reach, views, watch-time, saves, shares, total_interactions), check the 24-hour publish cap, or ingest Reel performance into 02-DOCS/wiki/shortform. Triggers: 'publish this Reel via the API', 'pull reach and average watch time for these media IDs', 'why does /insights?metric=plays return an error', 'my container is stuck IN_PROGRESS', 'how many posts left in the 24h publish window', 'publica este Reel por la API', 'ingesta el rendimiento dels Reels al wiki'. NOT TikTok publishing (that is tiktok-api), NOT a posting calendar/cadence (that is social-publisher), NOT YouTube uploads/stats (that is youtube-api)."
+description: "Use when wiring an agent into Instagram's Graph API: publishing a Reel through the create/poll/publish container dance, reading per-media insights, checking the 24h publish cap, or ingesting Reel metrics into 02-DOCS/wiki/shortform. NOT TikTok (that is `tiktok-api`), NOT YouTube (that is `youtube-api`), NOT cross-platform cadence (that is `social-publisher`)."
 tags: [instagram, graph-api, content-publishing, reels, insights, shortform]
 recommends: [tiktok-api, youtube-api, social-publisher, shortform-strategy, api-connector-builder]
 origin: risco
@@ -12,15 +12,10 @@ The wire between an agent and Instagram's Graph API: publish Reels, pull the met
 
 All facts below are pinned to **Graph API v25.0** (current as of 2026-06-02). When you generate code, pin the version explicitly; Meta breaks metrics on version boundaries.
 
-## When to use / when NOT
+## Route out
 
-| The ask | Route |
+| The ask | Skill |
 |---|---|
-| Publish a Reel from a public `video_url` to an IG professional account | **here** |
-| Pull reach / views / watch-time / saves / shares for media IDs | **here** |
-| `/insights?metric=plays` (or `impressions`) suddenly errors | **here** (deprecation trap) |
-| Check the 24h publish cap before a batch | **here** |
-| Long-lived token exchange / refresh, scope wiring | **here** |
 | Post the same clip to **TikTok** | `tiktok-api` |
 | Upload to **YouTube** / pull YouTube stats | [`youtube-api`](../youtube-api/SKILL.md) |
 | Cadence, best-time, multi-platform calendar | [`social-publisher`](../social-publisher/SKILL.md) |
@@ -125,6 +120,8 @@ Bad:  video_url behind auth or a 30s signed URL -> container stalls in ERROR.
 Good: a plain public MP4 that stays reachable for the full ~5 min window.
 ```
 
+Full container field reference (reels / carousel / story), cover & thumb handling, error codes, retry/backoff, and batch publish with cap check → `references/publish-reel.md`.
+
 ## Status polling rules
 
 `status_code` is the only honest signal. Branch on it, do not guess from timing.
@@ -180,6 +177,8 @@ Requesting any retired metric does not return null — it **400s the entire insi
 
 If a previously-working call started erroring, this table is almost certainly why: a metric you used to request was retired on a version boundary. Swap to `views` and drop the dead names.
 
+Complete current metric tables per media type, the full deprecated→replacement map with dates, version-gated 2025–2026 additions, and the `02-DOCS/wiki/shortform/` ingest schema spec → `references/insights-metrics.md`.
+
 ## Ingest into 02-DOCS/wiki/shortform/
 
 This is the checkable deliverable. One file per media id, idempotent overwrite (re-running a pull refreshes `pulled_at` and metrics, never duplicates).
@@ -222,14 +221,6 @@ current valid Reels set; no deprecated names requested.
 
 `type` is the only required OKF v0.1 field; `title`/`description`/`tags`/`timestamp` are the recommended OKF surface (`timestamp` mirrors the pull instant). The DOMAIN keys below are mandatory and stay byte-for-byte — `verify.sh` requires a pinned `graph_version` and greps the `metrics` block for deprecated names; `pulled_at` is the API-pull instant verify/diff rely on. Keep both `pulled_at` and `timestamp`. Why front-matter + media-id filename: the wiki is queried by key, and re-pulls must be diffable, not additive (the idempotent overwrite re-stamps `timestamp` and `pulled_at` together).
 
-## Migration & gotchas
-
-- **Scopes:** replace `instagram_basic` → `instagram_business_basic`, `instagram_content_publish` → `instagram_business_content_publish`. Old names grant nothing post-2025-01-27.
-- **Host:** chosen by login path, not per call. Do not send a `graph.instagram.com` token to `graph.facebook.com`.
-- **Token:** refresh the 60-day long-lived token before expiry; expired tokens fail every call with an auth error, not a 404.
-- **Reel eligibility:** 9:16, 5–90s, H.264/HEVC. A non-conforming source surfaces as container `ERROR`, not a clean validation message.
-- **New 2025–2026 metrics** (Reels skip rate, repost counts, crossposted views): optional and version-gated. Confirm they exist on `GRAPH_VERSION` before requesting, or they trip the same 400 trap.
-
 ## Anti-patterns
 
 | Anti-pattern | Why it bites | Do instead |
@@ -239,10 +230,9 @@ current valid Reels set; no deprecated names requested.
 | Leaving `GRAPH_VERSION` blank / using default | Metric set silently shifts on Meta's rollout | Pin `v25.0` in every call |
 | Signed/auth-gated `video_url` | Container stalls in `ERROR` | Plain public MP4 for the full window |
 | Batch publishing without cap check | Hit #51 mid-run, half-published queue | `content_publishing_limit` before the loop |
-| Old scopes (`instagram_basic`) | Grant nothing since 2025-01-27 | `instagram_business_*` scopes |
+| Old scopes (`instagram_basic`, `instagram_content_publish`) | Grant nothing since 2025-01-27 | `instagram_business_basic` / `instagram_business_content_publish` |
 | Storing the container id as "the post" | It's not the published media id | Persist the `media_publish` id |
-
-## References
-
-- `references/publish-reel.md` — full container field reference (reels / carousel / story), cover & thumb handling, error codes, retry/backoff, batch publish with cap check.
-- `references/insights-metrics.md` — complete current metric tables per media type, the full deprecated→replacement map with dates, version-gated 2025–2026 additions, and the `02-DOCS/wiki/shortform/` ingest schema spec.
+| Sending a `graph.instagram.com` token to `graph.facebook.com` | Host is fixed by the login path, not chosen per call | Pick the host with the auth path and stay on it |
+| Letting the 60-day long-lived token lapse | Every call fails with an auth error, not a 404 | Refresh before expiry |
+| A source video outside Reel eligibility | Surfaces as container `ERROR`, not a clean validation message | 9:16, 5–90s, H.264/HEVC |
+| Requesting the 2025–2026 additions (Reels skip rate, repost counts, crossposted views) blind | Version-gated — trips the same 400 trap as a deprecated name | Confirm they exist on `GRAPH_VERSION` first |

package/skills/machine-learning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: machine-learning
-description: "Use when the task is a classic/tabular machine-learning problem — predict a column from rows of features with trees and scikit-learn: fit a RandomForest / XGBoost / LightGBM classifier or regressor, build a leak-proof Pipeline + ColumnTransformer, choose a cross-validation scheme (stratified / k-fold / time-series / grouped), pick the right metric on imbalanced classes (precision/recall/F1/ROC-AUC/PR-AUC, not accuracy), or debug a model that aced CV then collapsed in production. Triggers: 'train a model to predict churn/fraud/price', 'my ROC-AUC is 0.99 — is that leakage', 'which metric for imbalanced classes', 'cross-validation without leaking', 'XGBoost vs LightGBM', 'add a DummyClassifier baseline', 'entrena un modelo de clasificación tabular con scikit-learn'. NOT neural-net / PyTorch training (that is deep-learning), NOT cleaning the raw dirty table first (that is data-cleaning), NOT BI dashboards or forecasting a dated series (that is analytics/forecasting), NOT text/token modeling (that is nlp)."
+description: "Use when predicting a column from rows of tabular features with classic models — scikit-learn pipelines, RandomForest, XGBoost/LightGBM, leak-free cross-validation, metrics for imbalanced classes, or a model that aced CV then collapsed in production. NOT PyTorch neural nets (that is `deep-learning`), NOT cleaning the dirty table first (that is `data-cleaning`), NOT forecasting a dated series (that is `forecasting`), NOT text/token modeling (that is `nlp`)."
 tags: [machine-learning, scikit-learn, sklearn, xgboost, lightgbm, tabular, gbdt, cross-validation, data-leakage, classification, regression, pipeline]
 recommends: [deep-learning, data-cleaning, python, training-data]
 origin: risco
@@ -21,9 +21,9 @@ once isn't a result — it's a leak you haven't found yet.
 | Rows of features, predict a column, with trees / linear models / sklearn | **machine-learning** (this skill) |
 | Images, audio, long text, sequences, or you need a neural net / PyTorch | [`deep-learning`](../deep-learning/SKILL.md) |
 | The table is still dirty (nulls, dupes, mixed types, bad dates) | [`data-cleaning`](../data-cleaning/SKILL.md) **first** — it hands you a validated table |
-| Text/token classification, NER, tokenization, LLM-adjacent NLP metrics | [`nlp`](../nlp/SKILL.md) |
-| KPIs, dashboards, "explain the business" | `analytics` / `business-intelligence` |
-| Forecast a dated series forward (revenue next quarter) | `forecasting` |
+| Text/token classification, NER, tokenization, LLM-adjacent NLP metrics | [`nlp`](../nlp/SKILL.md) (a TF-IDF + linear/GBDT baseline still lives happily in this skill's pipeline) |
+| KPIs, dashboards, "explain the business" | [`analytics`](../analytics/SKILL.md) / [`business-intelligence`](../business-intelligence/SKILL.md) |
+| Forecast a dated series forward (revenue next quarter) | [`forecasting`](../forecasting/SKILL.md) |
 | Building a training corpus of JSONL messages / preference pairs for an LLM | [`training-data`](../training-data/SKILL.md) |
 
 This skill **starts** at a clean, validated table (rows × features + a target) and **ends** at a fitted,
@@ -36,8 +36,9 @@ Verified 2026-07: **scikit-learn current major ~1.9** (1.9.0 shipped 2026-06-02,
 NOT pin from memory; check the current stable at scikit-learn.org, the 1.x line ships every few months.
 GBDTs: **XGBoost 3.x** and **LightGBM 4.x** (`xgboost` 3.3, `lightgbm` 4.6 current), plus sklearn's own
 **`HistGradientBoostingClassifier`/`...Regressor`** — a fast native GBDT that eats NaN and (with
-`categorical_features="from_dtype"`) categoricals with **no** preprocessing. Pin what you ship; state
-versions as "~X (verify)", never as frozen fact.
+`categorical_features="from_dtype"`) categoricals with **no** preprocessing. Pin what you ship
+([`python`](../python/SKILL.md) owns the environment and the pinning); state versions as "~X (verify)",
+never as frozen fact.
 
 ## The one rule everything else serves: fit on train only
 
@@ -107,7 +108,7 @@ functions**. Start with a GBDT; reach for `deep-learning` on tabular only with a
 All three expose the sklearn estimator API, so they drop into the pipeline and CV below unchanged. Don't
 agonize over XGBoost-vs-LightGBM before you have a baseline and a leak-free CV — split discipline dwarfs the
 library choice. Tuning knobs (`learning_rate`, `num_leaves`/`max_depth`, early stopping, `monotonic_cst`)
-→ [references/gbdt-and-tuning.md](references/gbdt-and-tuning.md).
+and importance/SHAP → [references/gbdt-and-tuning.md](references/gbdt-and-tuning.md).
 
 ## Leakage-safe feature engineering
 
@@ -174,19 +175,21 @@ The default 0.5 threshold is a *choice*: tune it on validation to hit your preci
 Regression uses `root_mean_squared_error` now (`mean_squared_error(squared=False)` is gone). Threshold
 tuning, calibration, `class_weight`/resampling → [references/metrics-and-imbalance.md](references/metrics-and-imbalance.md).
 
-## Cardinal sins (the anti-pattern table)
+## Anti-patterns — the cardinal sins
 
-| Rationalization | Reality → STOP |
+| Anti-pattern | Do instead |
 | --- | --- |
-| "I scaled/encoded/selected features, then split." | **Leakage (#1 sin).** Test statistics are now in train. Split first; put every learned transform *inside* the `Pipeline` so CV re-fits per fold. |
-| "This feature is amazingly predictive." | Suspect **target leakage** — a column derived from the label or unavailable at prediction time. Audit provenance before you celebrate. |
-| "99% accuracy!" (on 1% positives) | The **accuracy trap**. A constant predictor matches it. Report PR-AUC / precision / recall / F1 and a `confusion_matrix`. |
-| "The classes are imbalanced, so I `SMOTE`'d the whole dataset." | Resampling *before* the split, or on the test fold, leaks and evaluates on synthetic rows. Resample **inside CV, on the train fold only** (imblearn `Pipeline`), or just use `class_weight="balanced"`. |
-| "CV score is 0.95, ship it." | You never touched a **held-out test set**, or you peeked at it while tuning. One final, untouched test number — or the estimate is optimistic. |
-| "Random `KFold` on my time-series / multi-user data." | Future or same-group rows leak into train. Use `TimeSeriesSplit` / `GroupKFold`. |
-| "Big train/test gap? It'll generalize." | **Overfitting.** Regularize, reduce capacity (`max_depth`, `min_samples_leaf`), get more data, or use early stopping. Watch `return_train_score`. |
-| "Straight to XGBoost, no baseline." | Without a **`DummyClassifier(strategy="most_frequent")`** / `DummyRegressor` floor (and a simple linear model), you can't tell if the fancy model adds anything. |
-| "I'll grid-search 10k combos on all the data." | Tuning against the test set *is* fitting to it. Tune with CV on train, confirm once on test; consider nested CV. |
+| Modeling straight off the raw, dirty table | This skill starts at a **clean, validated frame**. Run [`data-cleaning`](../data-cleaning/SKILL.md) first — nulls, dupes and mixed dtypes are its job, not a modeling problem. |
+| Scaling / encoding / selecting features, *then* splitting | **Leakage (#1 sin).** Test statistics are now in train. Split first; put every learned transform *inside* the `Pipeline` so CV re-fits per fold. |
+| Celebrating an amazingly predictive feature | Suspect **target leakage** — a column derived from the label or unavailable at prediction time. Audit provenance before you celebrate. |
+| Reporting 99% accuracy on 1% positives | The **accuracy trap**. A constant predictor matches it. Report PR-AUC / precision / recall / F1 and a `confusion_matrix`. |
+| `SMOTE`-ing the whole dataset because the classes are imbalanced | Resampling *before* the split, or on the test fold, leaks and evaluates on synthetic rows. Resample **inside CV, on the train fold only** (imblearn `Pipeline`), or just use `class_weight="balanced"`. |
+| Shipping on the CV score alone | You never touched a **held-out test set**, or you peeked at it while tuning. One final, untouched test number — or the estimate is optimistic. |
+| Random `KFold` on time-series / multi-user data | Future or same-group rows leak into train. Use `TimeSeriesSplit` / `GroupKFold`. |
+| Waving off a big train/test gap | **Overfitting.** Regularize, reduce capacity (`max_depth`, `min_samples_leaf`), get more data, or use early stopping. Watch `return_train_score`. |
+| Going straight to XGBoost with no baseline | Without a **`DummyClassifier(strategy="most_frequent")`** / `DummyRegressor` floor (and a simple linear model), you can't tell if the fancy model adds anything. |
+| Grid-searching 10k combos over all the data | Tuning against the test set *is* fitting to it. Tune with CV on train, confirm once on test; consider nested CV. |
+| Unset `random_state`, unpinned versions | Folds and fits stop being reproducible and re-trains stop being comparable. Set an integer `random_state` on splitters *and* estimators; pin the versions you ship. |
 
 ## Worked lifecycle (end to end)
 
@@ -216,41 +219,6 @@ print("TEST PR-AUC:", round(average_precision_score(y_test, proba), 3))
 print(classification_report(y_test, (proba >= 0.5).astype(int)))   # threshold is a choice — tune it
 ```
 
-## Related skills
-
-- [`deep-learning`](../deep-learning/SKILL.md) — PyTorch neural nets. Cross the boundary for images, audio,
-  long text, sequences; on *tabular* data, stay here (Grinsztajn: trees win).
-- [`data-cleaning`](../data-cleaning/SKILL.md) — upstream; produces the validated table this skill trains
-  on. Don't re-teach nulls/dupes/dtypes here.
-- [`nlp`](../nlp/SKILL.md) — text/token modeling, NER, tokenization, task metrics (a TF-IDF + linear/GBDT
-  baseline still lives happily in this skill's pipeline).
-- [`python`](../python/SKILL.md) — environment, packaging, pinning the versions you ship.
-- [`training-data`](../training-data/SKILL.md) — if the goal is an LLM corpus (JSONL messages / preference
-  pairs), not a tabular predictor. BI/forecasting products → `analytics` / `business-intelligence` / `forecasting`.
-
-## Checklist
-
-- [ ] Input is a clean, validated table (from `data-cleaning`), not raw dirty rows.
-- [ ] A **test set** was held out **once, up front**, stratified, and left untouched until the final score.
-- [ ] Every learned transform (impute/scale/encode/select/target-encode) lives **inside** the `Pipeline`.
-- [ ] CV runs on the training portion only, via `cross_validate`/`GridSearchCV` over the *pipeline*.
-- [ ] Splitter matches the data: `StratifiedKFold` (imbalanced), `TimeSeriesSplit` (time), `GroupKFold` (clustered).
-- [ ] A `DummyClassifier`/`DummyRegressor` baseline (and a simple linear model) is beaten, not skipped.
-- [ ] Metric fits the task — **not accuracy on imbalanced data**; PR-AUC/precision/recall/F1 as appropriate.
-- [ ] Target-leakage audit done: no label-derived / future / not-at-prediction-time features.
-- [ ] `random_state` set on splitters and estimators; versions pinned for what ships.
-- [ ] Train-vs-test gap inspected; overfitting addressed before shipping.
-
-## References
-
-- [references/pipelines-and-cv.md](references/pipelines-and-cv.md) — `Pipeline`/`ColumnTransformer` patterns,
-  `FunctionTransformer`, `TargetEncoder` cross-fitting, `GridSearchCV`/`RandomizedSearchCV`/`HalvingRandomSearchCV`,
-  nested CV, `TimeSeriesSplit`/`GroupKFold` recipes.
-- [references/metrics-and-imbalance.md](references/metrics-and-imbalance.md) — metric selection, threshold
-  tuning, probability calibration, `class_weight`/`sample_weight`, leak-free resampling (imbalanced-learn `Pipeline`).
-- [references/gbdt-and-tuning.md](references/gbdt-and-tuning.md) — HistGBDT vs XGBoost vs LightGBM parameter
-  maps, early stopping, native categoricals, monotonic constraints, permutation importance vs SHAP.
-
 ## Project grounding (02-DOCS + CLAUDE.md)
 
 In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), record the modeling

package/skills/observability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: observability
-description: "Use when instrumenting a service from the inside so an incident can be explained from telemetry alone — wiring OpenTelemetry logs, metrics and traces, standing up a Collector, exporting via OTLP, and defining telemetry-driven alerts. Triggers: 'add OpenTelemetry to this service', 'we can't tell why requests are slow across services — add distributed tracing', 'replace our print/console.log with structured logs correlated to traces', 'stand up an OTel Collector and export to Grafana/Datadog/Honeycomb', 'instrument our LLM calls so each request is a span with token counts', 'define RED metrics and a burn-rate alert from the telemetry', 'instrumenta el servei amb OpenTelemetry i exporta a Grafana', 'añade trazas distribuidas y métricas'. NOT outside-in uptime probes, on-call rotation, or who-gets-paged (that is monitoring)."
+description: "Use when instrumenting a service from the inside so an incident can be explained from telemetry alone — wiring OpenTelemetry logs, metrics and traces, standing up a Collector, exporting via OTLP, and defining telemetry-driven alerts. NOT outside-in uptime probes, on-call rotation, or who-gets-paged (that is `monitoring`)."
 tags: [observability, opentelemetry, tracing, metrics, structured-logging]
 recommends: [monitoring, error-handling, performance, cost-tracking, docker]
 origin: risco
@@ -8,9 +8,7 @@ origin: risco
 
 # Observability
 
-You are wiring the *inside* view of a service: when something breaks at 3am, an engineer must be able to answer "what happened, where, and why" from telemetry alone — without adding a `console.log` and redeploying into the fire. This skill emits a concrete artifact: SDK init code, instrumentation (spans/metrics/structured logs), a Collector config, and alert rules that the instrumentation makes possible.
-
-It is the inside-out half of running in production. The outside half — is it up, who gets paged, on-call rotation — is `../monitoring/SKILL.md`. The clean test: if the deliverable is *"a human gets paged,"* that is monitoring. If it is *"the data that explains the page exists and is queryable,"* that is here.
+You are wiring the *inside* view of a service: when something breaks at 3am, an engineer must be able to answer "what happened, where, and why" from telemetry alone — without adding a `console.log` and redeploying into the fire. This skill emits a concrete artifact: SDK init code, instrumentation (spans/metrics/structured logs), a Collector config, and alert rules that the instrumentation makes possible. The outside-in half — is it up, who gets paged — is `../monitoring/SKILL.md`.
 
 ## The one rule
 

package/skills/rag/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rag
-description: "Use when building grounded Q&A over your own documents — handbook, support tickets, PDFs, policies — and the answers must come only from the corpus with citations; when retrieval surfaces the right document but the answer is still wrong; when the model invents facts that are not in the sources; when you need to measure whether retrieval is any good; when the right document is found but the wrong passage is used. Triggers: 'build a bot that answers from our docs with citations', 'my RAG returns the right document but the answer is wrong', 'how do I stop the model hallucinating facts not in the corpus', 'context recall vs context precision', 'add contextual retrieval / prepend chunk context before embedding', 'hybrid search plus rerank pipeline', 'respuestas con citas sobre nuestros documentos', 'el bot s'inventa coses que no surten als documents'. NOT operating the vector store itself — collection schema, HNSW ef_search, quantization (that is vector-db)."
+description: "Use when building grounded Q&A over your own corpus — chunk, retrieve hybrid, rerank, ground, cite chunk ids, refuse when the sources fall short — or when the right document is retrieved but the answer is still wrong, invented, or unmeasured. NOT operating the store itself — collection schema, HNSW ef_search, quantization (that is `vector-db`)."
 tags: [rag, retrieval-augmented-generation, chunking, hybrid-search, reranking, grounding, citations, faithfulness, contextual-retrieval]
 recommends: [vector-db, embeddings-search, document-processing, chatbot, agent-eval]
 origin: risco
@@ -8,15 +8,14 @@ origin: risco
 
 # rag — own the retrieve → rerank → ground → cite → refuse pipeline
 
-You own the **pipeline** that turns a corpus plus a question into a grounded, cited answer.
-You do **not** own the store underneath it (`../vector-db/SKILL.md`) nor the embedding and
-chunk-sizing science beside it (`embeddings-search`). Your job is the glue: chunk, optionally
-contextualize, index, retrieve hybrid, rerank, assemble a grounded prompt, cite the sources,
-and **refuse** when the context does not contain the answer.
+You own the **pipeline** that turns a corpus plus a question into a grounded, cited answer: chunk,
+optionally contextualize, index, retrieve hybrid, rerank, assemble a grounded prompt, cite the
+sources, and **refuse** when the context does not contain the answer.
 
 You are judged by **retrieval quality and answer faithfulness**, not by raw vector math. If you
-find yourself tuning HNSW parameters, you wandered into `vector-db`. If you are comparing
-embedding models or chunk sizes, that is `embeddings-search`.
+find yourself tuning HNSW parameters, you wandered into the store underneath you
+(`../vector-db/SKILL.md`). If you are comparing embedding models or chunk sizes, that is the
+science beside you (`embeddings-search`).
 
 ## The pipeline, and where each stage hands off
 
@@ -25,19 +24,21 @@ delegate to a sibling skill rather than living here.
 
 | Stage | What you do | Hands off to |
 |---|---|---|
-| Ingest | Get clean text out of PDFs/DOCX/HTML/OCR | `../document-processing/SKILL.md` |
-| Chunk | Heading/semantic-aware splits with overlap, stable ids | chunk-size science → `embeddings-search` |
+| Ingest | Get clean text out of PDFs/DOCX/HTML/OCR | you assume text exists → `../document-processing/SKILL.md` |
+| Chunk | Heading/semantic-aware splits with overlap, stable ids | model, dims + chunk-size science → `embeddings-search` |
 | Contextualize | Prepend an LLM-written context blurb per chunk (optional) | stays here |
-| Index | Embed + write dense vectors and a BM25/keyword index | the store → `../vector-db/SKILL.md` |
+| Index | Embed + write dense vectors and a BM25/keyword index | you upsert, it owns the knobs → `../vector-db/SKILL.md` |
 | Retrieve | Hybrid dense + BM25, fuse with RRF, top ~150 | hybrid query mechanics → `../vector-db/SKILL.md` |
 | Rerank | Cross-encoder over the 150, keep top ~20 | stays here |
 | Ground + cite | System prompt: answer only from context, cite chunk ids | stays here |
 | Refuse | Output "I don't have enough information" on weak context | stays here |
 | Evaluate | Faithfulness, answer relevancy, context precision/recall | general harness → `agent-eval` |
 
-Surfacing this answer inside a chat product (sessions, channels, UI) is `../chatbot/SKILL.md`;
-pulling schema-constrained fields out of text is `structured-extraction`. `rag` is the
-retrieval brain those products call.
+Three neighbors are not stages at all. Surfacing this answer inside a chat product (sessions,
+channels, UI) is `../chatbot/SKILL.md` — it calls you, not the reverse. A multi-step tool loop with
+state, where retrieval is one tool among many, is `../building-agents/SKILL.md`. Pulling
+schema-constrained fields out of text instead of a grounded prose answer is
+`structured-extraction`. `rag` is the retrieval brain those products call.
 
 ## Retrieval is the bottleneck — measure recall before touching the prompt
 
@@ -87,8 +88,8 @@ def chunk_markdown(doc_id, text, target=800, overlap=120):
     return out
 ```
 
-For the deep "what window/overlap maximizes recall for *this* corpus" study, that is
-`embeddings-search`. Here you just need structurally sane chunks that keep their ids.
+The "what window/overlap maximizes recall for *this* corpus" study is `embeddings-search`; here you
+just need structurally sane chunks that keep their ids.
 
 ## Contextual retrieval — prepend context before you embed
 
@@ -107,7 +108,8 @@ document for search retrieval. Answer only with the context, nothing else.
 ```
 
 Embed `context + "\n" + chunk_text` (not the bare chunk). The full implementation — caching the
-document prompt, batching, the BM25 side — lives in `references/pipeline.md`.
+document prompt, batching, the BM25 side, and a runnable retrieve → rerank → answer skeleton —
+lives in `references/pipeline.md`.
 
 ## Hybrid retrieval + RRF + rerank
 
@@ -144,8 +146,8 @@ top = [candidates[r.index] for r in ranked.results]  # each still carries chunk_
 
 Properly grounded RAG reduces hallucination rates by up to ~71%; poorly grounded pipelines still
 hallucinate in up to ~40% of responses *even with the right doc retrieved* (Confident AI / Maxim
-2025, accessed 2026-06-02). The prompt must do three non-negotiable things: bind the answer to
-the context, force inline citations, and provide an explicit refusal path.
+2025, accessed 2026-06-02). The prompt must do three things: bind the answer to the context, force
+inline citations, and provide an explicit refusal path.
 
 ```text
 You answer ONLY using the information inside <context>. Do not use prior knowledge.
@@ -205,22 +207,3 @@ the RAG-specific metrics live here.
 | Embedding the query differently from the corpus | Query and chunks land in different spaces | Same model + same preprocessing both sides |
 | Dense-only, ignoring BM25/keyword | Misses exact codes/names/error strings | Hybrid dense + BM25 fused with RRF |
 | Tuning temperature to fix wrong answers | Generation is rarely the bottleneck | Measure context recall first |
-
-## Wiring map
-
-- **Ingestion (file → text, OCR, tables):** `../document-processing/SKILL.md` — you assume text
-  already exists; send raw PDFs/DOCX/scans there first.
-- **The store (collection, index, hybrid query, quantization):** `../vector-db/SKILL.md` — you
-  call it to upsert and query; it owns the knobs.
-- **Embedding model + chunk-size science:** `embeddings-search` — picking the model, dims,
-  cost, and the semantic-vs-fixed chunking experiments.
-- **Chat product surface (sessions, channels, UI):** `../chatbot/SKILL.md` — wraps the answer
-  you return; it calls you, not the reverse.
-- **Multi-step tool/agent loop with state:** `../building-agents/SKILL.md` — when retrieval is
-  one tool among many in a larger loop.
-- **General eval framework:** `agent-eval` — RAG-specific metrics are here; the harness is there.
-- **Schema-constrained field extraction:** `structured-extraction` — when the goal is fields,
-  not a grounded prose answer.
-
-See `references/pipeline.md` for the full runnable retrieve → rerank → answer skeleton and
-`references/evaluation.md` for the metric formulas, thresholds, and CI gate.

package/skills/security-scan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-scan
-description: "Use when running automated security scanners over a repo or app and turning the raw output into a triaged, ranked, gate-able report: scan for vulnerabilities before shipping, audit dependencies/lockfiles for known CVEs, find secrets committed to the tree or git history, run SAST, or wire scanners into CI. Triggers: 'scan this repo for vulnerabilities', 'check my package-lock for CVEs', 'did anyone commit AWS keys', 'scan git history for leaked keys', 'my lockfile has a transitive CVE', 'is aquasecurity/trivy-action@latest safe', 'set up Semgrep/gitleaks to fail CI', 'escanea el repo en busca de vulnerabilidades', 'audita las dependencias', 'analitza les dependències'. NOT threat-modeling, OWASP design reasoning, or authoring the fix (that is secure-coding)."
+description: "Use when automated scanners drive a security sweep of a repo or app — SAST, dependency/lockfile CVEs, secrets in the tree or git history, IaC misconfig — and the raw output has to become one deduped, exploitability-ranked report CI can gate on. NOT threat-modeling, OWASP design reasoning, or hand-authoring the fix (that is `secure-coding`)."
 tags: [security, sast, sca, secrets, scanning, owasp]
 recommends: [secure-coding, github-actions, verify]
 origin: risco
@@ -15,40 +15,28 @@ finding comes from a **tool run**, not a hunch — if you are reasoning about a
 design or hand-writing a fix, that is [`secure-coding`](../secure-coding/SKILL.md),
 not this skill.
 
-Your job is orchestration + triage. Not eyeballing code, not authoring patches.
-
-## Operating posture
-
-- **Read-only by default.** Scan, triage, report. Apply fixes (version bumps,
-  rotation, `.gitignore` edits) only when the user asks. *Why:* a security sweep
-  that silently mutates the tree destroys the evidence and the trust.
-- **Machine-first.** Every finding must trace to a scanner run with a `ruleId`
-  and a source location. *Why:* "I think this looks injectable" is design
-  reasoning — route it to `secure-coding`. This skill ships reproducible output.
-- **Pin and verify your scanners.** Pin exact versions, verify checksums/SHAs,
-  never pull `@latest` GitHub Actions. *Why:* in **March 2026 Trivy was
-  supply-chain compromised** — malicious releases `v0.69.4/0.69.5/0.69.6` and a
-  hijacked `aquasecurity/trivy-action` exfiltrated CI secrets. Your scanner runs
-  with repo + CI-secret access; an unpinned scanner is itself the attack surface.
-- **SARIF everything.** Make every tool emit SARIF (or JSON you normalize to it).
-  *Why:* a common schema is what lets you merge four tools, dedupe, and feed one
-  artifact into CI instead of four incompatible logs.
-- **Triage before you report.** Raw scanner output is high-noise. Rank by
-  exploitability and dedupe overlap; never dump 400 raw findings on the user.
-
-## The four scan classes
-
-| Class | What it catches | Primary tool | Backup / fast pass |
-|---|---|---|---|
-| **SAST** | injection, XSS, path traversal in *first-party* code | Semgrep | — |
-| **SCA / deps** | known CVEs in dependency manifests + lockfiles | osv-scanner | `npm audit`, `pip-audit` |
-| **Secrets** | credentials in the tree **or git history** | gitleaks (speed) | TruffleHog (depth + live verification) |
-| **Misconfig / IaC** | Dockerfile, k8s, Terraform, exposed config | Trivy `config` | Semgrep rulesets |
-
-### Tool selection by ecosystem
-
-Pick by what is in the repo. This is the real branch point — match the tool to
-the manifest, do not run everything everywhere.
+Your job is orchestration + triage: every finding traces to a scanner run with a
+`ruleId` and a source location, so the output is reproducible. Not eyeballing
+code, not authoring patches.
+
+**Read-only by default.** Scan, triage, report. Apply fixes (version bumps,
+rotation, `.gitignore` edits) only when the user asks — a security sweep that
+silently mutates the tree destroys the evidence and the trust.
+
+**Pin and verify your scanners.** Exact versions, verified checksums/SHAs, never
+`@latest` GitHub Actions. In **March 2026 Trivy was supply-chain compromised** —
+malicious releases `v0.69.4/0.69.5/0.69.6` and a hijacked
+`aquasecurity/trivy-action` exfiltrated CI secrets. Your scanner runs with repo +
+CI-secret access; an unpinned scanner is itself the attack surface.
+
+## Scan classes and tool selection
+
+Four classes: **SAST** (injection, XSS, path traversal in *first-party* code),
+**SCA / deps** (known CVEs in dependency manifests + lockfiles), **Secrets**
+(credentials in the tree **or git history**), **Misconfig / IaC** (Dockerfile,
+k8s, Terraform, exposed config). Pick tools by what is in the repo. This is the
+real branch point — match the tool to the manifest, do not run everything
+everywhere.
 
 | Repo contains | SAST | SCA | Secrets | Misconfig |
 |---|---|---|---|---|
@@ -56,15 +44,17 @@ the manifest, do not run everything everywhere.
 | Python (`poetry.lock`/`requirements.txt`) | Semgrep | osv-scanner + `pip-audit` (fast) | gitleaks → TruffleHog | Trivy |
 | Go (`go.mod`/`go.sum`) | Semgrep | osv-scanner (+ `govulncheck` for reachability) | gitleaks | Trivy |
 | Containers (`Dockerfile`, images) | — | Trivy `fs`/`image` | Trivy `--scanners secret` | Trivy `config` |
-| IaC (Terraform/k8s/Helm) | Semgrep (IaC rules) | — | gitleaks | Trivy `config` |
+| IaC (Terraform/k8s/Helm) | Semgrep (IaC rules) | — | gitleaks | Trivy `config`, Semgrep rulesets |
 | Monorepo (mixed) | Semgrep `auto` | osv-scanner (multi-ecosystem) | gitleaks → TruffleHog | Trivy |
 
 Full install (pinned), flag matrix, and suppression syntax: `references/tools.md`.
 
 ## Run recipes
 
-All recipes emit SARIF or JSON so they merge into one report. **Pin the version
-shown** — the placeholders below mark where to lock an exact tag/digest.
+All recipes emit SARIF (or JSON you normalize to it) — a common schema is what
+lets you merge four tools, dedupe, and feed one artifact into CI instead of four
+incompatible logs. **Pin the version shown**; the placeholders below mark where
+to lock an exact tag/digest.
 
 ### SAST — Semgrep
 
@@ -107,10 +97,10 @@ gitleaks detect --redact --report-format sarif --report-path secrets.sarif
 trufflehog git file://. --only-verified --json > trufflehog.json
 ```
 
-### Misconfig / IaC — Trivy (PINNED — see the caveat)
+### Misconfig / IaC — Trivy (PINNED — see the caveat above)
 
 Trivy scans filesystems, images, and IaC and finds transitive CVEs `npm audit`
-misses. After the March 2026 compromise, **never** run an unpinned Trivy.
+misses.
 
 ```bash
 # Pin the EXACT version (NOT v0.69.4/.5/.6 — those were the malicious releases).
@@ -200,17 +190,17 @@ Emit one `security-scan-report.json` — the machine-checkable contract CI gates
 
 ## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Do instead |
 |---|---|
-| "Pull `aquasecurity/trivy-action@latest`, it's official." | March 2026: a hijacked tag stole CI secrets. Pin a full SHA, verify provenance. |
-| "Every scanner finding is a bug to fix." | Most are noise. Rank by reachable + exposed + sensitive sink; report the few that matter. |
-| "Scanned the working tree, no secrets." | History holds the deleted keys. Scan git history; a removed-in-HEAD key is still leaked and live. |
-| "`npm audit` is clean, deps are fine." | Native auditors miss transitive CVEs. Run osv-scanner/Trivy too; native is the fast pass, not the only pass. |
-| "Commit a blanket `.semgrepignore` to quiet CI." | A blanket ignore hides the next real bug. Suppress per-finding with a written justification + expiry. |
-| "We found a verified key, I deleted it from the file." | Deleting ≠ safe. Rotate the credential first, then scrub history. The committed value is already compromised. |
-| "Trust the SARIF `level`, that's the severity." | Tools disagree. Normalize to one scale before you rank or gate. |
-| "Dump all four tool outputs in the PR, let the reviewer sort it." | The reviewer won't. Merge, dedupe, rank, and emit one report. |
-| "Run the scan; it'll auto-fix the deps." | Read-only by default. Propose bumps; apply only when asked — never mutate during a sweep. |
+| Pulling `aquasecurity/trivy-action@latest` because it is the official action | March 2026: a hijacked tag stole CI secrets. Pin a full SHA, verify provenance. |
+| Treating every scanner finding as a bug to fix | Most are noise. Rank by reachable + exposed + sensitive sink; report the few that matter. |
+| Calling the repo clean after scanning only the working tree | History holds the deleted keys. Scan git history; a removed-in-HEAD key is still leaked and live. |
+| Declaring deps fine because `npm audit` is clean | Native auditors miss transitive CVEs. Run osv-scanner/Trivy too; native is the fast pass, not the only pass. |
+| Committing a blanket `.semgrepignore` to quiet CI | A blanket ignore hides the next real bug. Suppress per-finding with a written justification + expiry. |
+| Deleting a verified key from the file and moving on | Deleting ≠ safe. Rotate the credential first, then scrub history. The committed value is already compromised. |
+| Taking the SARIF `level` as the severity | Tools disagree. Normalize to one scale before you rank or gate. |
+| Dumping all four tool outputs in the PR for the reviewer to sort | The reviewer won't. Merge, dedupe, rank, and emit one report. |
+| Letting the scan auto-fix the deps it finds | Read-only by default. Propose bumps; apply only when asked — never mutate during a sweep. |
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
@@ -218,23 +208,12 @@ In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md)
 Karpathy wiki), record the scanner choices, pinned versions, gate thresholds, and
 any accepted-risk suppressions in `02-DOCS/wiki/stack/security-scan.md`, and index
 it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short
-pointer to it). Read it first on every run so the
-next agent inherits the pinned tools and thresholds instead of re-deriving them.
-No `02-DOCS/`? Skip silently. Conventions are recorded, not gated — never block
-the scan on this.
+pointer to it). Read it first on every run so the next agent inherits the pinned
+tools and thresholds instead of re-deriving them. No `02-DOCS/`? Skip silently.
+Conventions are recorded, not gated — never block the scan on this.
 
 ## See Also
 
-- [`secure-coding`](../secure-coding/SKILL.md) — the human-reasoning sibling:
-  threat-model a feature, hand-write the vulnerable→fixed diff. *If the answer
-  comes from a tool run it's this skill; if it comes from reasoning about the
-  design it's secure-coding.*
-- [`review`](../review/SKILL.md) — adversarial review of a diff against a spec.
-- [`code-review`](../code-review/SKILL.md) — general correctness/quality review.
-- [`verify`](../verify/SKILL.md) — the broader lint/type/test green gate this
-  feeds into.
-- **References** — `references/tools.md` (pinned installs, flag matrix,
-  suppression syntax); `references/triage.md` (ranking rubric, dedupe keying,
-  severity map, full report schema).
-</content>
-</invoke>
+Reviewing a diff rather than scanning a repo: [`code-review`](../code-review/SKILL.md)
+for correctness and quality, [`review`](../review/SKILL.md) for adversarial review
+against a spec.

package/skills/security-scan/references/tools.md

@@ -95,4 +95,3 @@ trivy image --format sarif --output trivy-img.sarif <pinned-image@sha256:...>
 - Every recipe emits SARIF 2.1.0 so findings merge into one report. Where a tool
   only emits native JSON (`npm audit`, `pip-audit`, TruffleHog), normalize it to
   the report schema in `triage.md` rather than gating on its raw shape.
-</content>

package/skills/security-scan/references/triage.md

@@ -90,4 +90,3 @@ This is the contract `scripts/verify.sh` gates on.
 - **Gate:** any `findings[]` with `status: "open"` and `severity: "critical"`
   → fail. Strict mode also fails on `open` + `high`. `suppressed`/`fixed` never
   fail. An empty/clean report exits `0`.
-</content>