@ericrisco/rsc 0.1.43 → 0.1.45

package/skills/postgresdb/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: postgresdb
-description: Use when designing or reviewing a PostgreSQL schema (types, constraints, normalization), writing or optimizing SQL, choosing or adding indexes, reading EXPLAIN/ANALYZE, planning a migration (expand-contract, concurrent index, batched backfill), or operating/securing Postgres (roles, RLS, PgBouncer pooling, VACUUM/autovacuum, pg_stat_statements, declarative partitioning, backups/PITR). Triggers - "slow query", "add an index", "EXPLAIN", "design this table", "zero-downtime migration", "row level security", "connection pool", "N+1", "JSONB", "full-text search", "pgvector". PostgreSQL 16; ORM-agnostic (SQLAlchemy/Alembic, Prisma, golang-migrate, raw SQL).
+description: Use when PostgreSQL engine behaviour decides the answer — schema and type design, index choice, reading EXPLAIN on a slow query, zero-downtime DDL and backfills, or ops (roles, RLS, pooling, vacuum, partitioning, PITR). PG16, ORM-agnostic. NOT portable query logic (that is `sql`), NOT a managed provider's platform surface (that is `neon`).
 tags: [postgres, sql, database, migrations]
 recommends: [secure-coding]
 origin: risco
@@ -12,25 +12,9 @@ Engine-level PostgreSQL 16 guidance: design correct schemas, pick the right inde
 fix slow SQL, run zero-downtime migrations, and operate/secure the database. Tooling-agnostic; every
 example is runnable.
 
-## When to use / When NOT to use
-
-> **⚠️ SDD new-feature gate — read this first.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP — do **not** write feature code yet. Hand off to `../specify/SKILL.md` first: it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build here directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
-
-**When to use:**
-
-- Schema/DDL decisions: types, keys, constraints, generated/identity columns, enum-vs-lookup, jsonb-vs-column.
-- Any query that is slow, scans too much, or returns wrong cardinality; reading a plan.
-- Index decisions: which kind, column order, partial/covering, and when NOT to add one.
-- Migrations against tables with real data or live traffic.
-- Concurrency: isolation, locking, deadlocks, queues.
-- Ops: pooling, vacuum, monitoring, partitioning, backups, RLS, least-privilege roles.
-
-**When NOT to use:**
-
-- ORM-API ergonomics (Prisma `updateMany` count trap, SQLAlchemy session lifecycle) → your ORM's own docs. This skill owns the **SQL the ORM emits and the engine behavior underneath**.
-- Non-Postgres engines (MySQL/SQLite/ClickHouse) — different MVCC, locking, planner.
-- App-layer caching / Redis / Kafka as products; only Postgres-as-queue via `SKIP LOCKED` is in scope.
-- Cloud-vendor console clicks — we give the SQL/params, not the RDS/Cloud SQL UI path.
+New, non-trivial feature with no approved spec + plan under `02-DOCS/wiki/sdd/`? Hand off to
+[`specify`](../specify/SKILL.md) before writing feature code (method: [`sdd`](../sdd/SKILL.md)); build
+straight from here only for a genuinely one-line, low-risk change.
 
 Deep dives: [schema-and-indexing](references/schema-and-indexing.md) (types, constraints, every index
 kind, bloat) · [query-optimization](references/query-optimization.md) (EXPLAIN, joins, concurrency,
@@ -38,18 +22,13 @@ JSONB/FTS/pgvector) · [migrations](references/migrations.md) (zero-downtime DDL
 [operations-and-security](references/operations-and-security.md) (roles, RLS, pooling, vacuum,
 partitioning, backups).
 
-## Non-negotiables
-
-1. `timestamptz` always for events; store UTC. Never naive `timestamp`.
-2. Money is `numeric(19,4)`, never `float`/`double precision`.
-3. Every FK gets a covering index — Postgres does **not** auto-index FK columns.
-4. `text` + `CHECK (length(...) <= n)`, not `varchar(n)` as a length hack.
-5. Index creation on a live table is **always** `CONCURRENTLY` (so it cannot run inside a txn).
-6. Never `ADD COLUMN ... NOT NULL` without a default/backfill plan; never add a volatile default on a large table without a batched backfill.
-7. Read the plan before adding an index: `EXPLAIN (ANALYZE, BUFFERS)` or it didn't happen.
-8. Migrations are forward-only in prod; never edit an applied migration.
-9. `SET lock_timeout` + `SET statement_timeout` around DDL on hot tables.
-10. RLS is opt-in per table and the **table owner bypasses it** — verify with a non-owner role (use `FORCE ROW LEVEL SECURITY` for the owner too).
+**Not this skill.** ORM-API ergonomics (Prisma `updateMany` count trap, SQLAlchemy session lifecycle)
+and per-runner migration wiring → that tool's own docs; this skill owns the **SQL the ORM emits and
+the engine behavior underneath**. Other engines → [`mysql`](../mysql/SKILL.md),
+[`sqlite-turso`](../sqlite-turso/SKILL.md), [`clickhouse-analytics`](../clickhouse-analytics/SKILL.md)
+(different MVCC, locking, planner). App-layer caching / Redis / Kafka as products are out — only
+Postgres-as-queue via `SKIP LOCKED` is in scope. Cloud-vendor console clicks →
+[`deployment`](../deployment/SKILL.md); we give the SQL and params, not the RDS/Cloud SQL UI path.
 
 ## Decision rules
 
@@ -91,6 +70,9 @@ Fast lookups; runnable DDL lives in the references.
 Hash indexes: almost never — equality-only, no multicolumn, rarely beats btree even though WAL-logged
 since PG10.
 
+Read the plan **before** adding an index — `EXPLAIN (ANALYZE, BUFFERS)` or it didn't happen. An index
+the planner never picks is pure write tax on every insert and update, forever.
+
 ### When NOT to add an index
 
 - Low-selectivity boolean / `status` with few distinct values (planner ignores it; seq scan wins).
@@ -262,9 +244,30 @@ Read these four first:
 
 Full method in [query-optimization](references/query-optimization.md).
 
-## Anti-patterns / rationalizations → STOP
+## DDL on a live table
 
-| Rationalization | Reality → STOP |
+Full sequences (zero-downtime expand-contract, batched backfills, per-ORM runners) in
+[migrations](references/migrations.md). These four are absolute because each one is a lock you cannot
+take back once traffic is on the table:
+
+1. Index creation on a live table is **always** `CONCURRENTLY` — plain `CREATE INDEX` holds ACCESS
+   EXCLUSIVE for the entire build and blocks every writer. It therefore cannot run inside a txn.
+2. Never `ADD COLUMN ... NOT NULL` without a default/backfill plan, and never add a **volatile**
+   default (`now()`, `gen_random_uuid()`) on a large table without a batched backfill — a volatile
+   default rewrites the whole table under ACCESS EXCLUSIVE. A non-volatile constant is instant (PG11+).
+3. `SET lock_timeout` + `SET statement_timeout` around DDL on hot tables, so a blocked statement fails
+   fast instead of parking an ACCESS EXCLUSIVE request that every reader behind it then queues on.
+4. Migrations are forward-only in prod; never edit an applied migration — it has already run
+   somewhere, so the next environment replays a history that no longer matches the one in production.
+
+Lock modes: `CREATE INDEX CONCURRENTLY` takes SHARE UPDATE EXCLUSIVE (allows writes); plain
+`CREATE INDEX`, `ALTER TABLE ... TYPE`, `ADD COLUMN` with a volatile default, and `VACUUM FULL` take
+ACCESS EXCLUSIVE (blocks everything). Full table in
+[migrations](references/migrations.md#lock-impact-reference).
+
+## Anti-patterns
+
+| Claim | Reality |
 | --- | --- |
 | "I'll add the FK index later, the query works now" | Unindexed FK = seq scan + heavy lock cascade on parent `DELETE`/`UPDATE`. Index it now. |
 | "UUID PK is fine everywhere" | Random v4 fragments the B-tree and bloats WAL. Use `IDENTITY` internally or uuid **v7**. |
@@ -274,6 +277,7 @@ Full method in [query-optimization](references/query-optimization.md).
 | "Store money as float, round on display" | Silent drift across arithmetic. `numeric(19,4)`. |
 | "`ADD COLUMN ... NOT NULL DEFAULT now()`" | Volatile default rewrites the table under ACCESS EXCLUSIVE. Non-volatile constant is instant (PG11+). |
 | "One big `jsonb` blob beats columns" | No constraints, no per-key stats, GIN bloat. Promote hot keys to typed columns. |
+| "RLS is on, so the table is protected" | RLS is opt-in per table and the **table owner bypasses it**. Verify with a non-owner role; add `FORCE ROW LEVEL SECURITY` to cover the owner too. |
 | "RLS policy calling `auth.uid()` per row" | Re-evaluated per row. Wrap: `(SELECT auth.uid())` so it runs once. |
 | "`CREATE INDEX` in the migration is fine" | Blocks writes for the whole build. `CREATE INDEX CONCURRENTLY` (outside a txn). |
 | "`VACUUM FULL` will fix bloat" | Takes ACCESS EXCLUSIVE, rewrites the table. Use autovacuum tuning / `REINDEX CONCURRENTLY`. |
@@ -290,12 +294,6 @@ Full method in [query-optimization](references/query-optimization.md).
 
 Retry the txn on SQLSTATE `40001` (serialization_failure) and `40P01` (deadlock_detected).
 
-### Lock modes (DDL)
-
-`CREATE INDEX CONCURRENTLY` takes SHARE UPDATE EXCLUSIVE (allows writes); plain `CREATE INDEX`,
-`ALTER TABLE ... TYPE`, `ADD COLUMN` with a volatile default, and `VACUUM FULL` take ACCESS EXCLUSIVE
-(blocks everything). Full table in [migrations](references/migrations.md#lock-impact-reference).
-
 ### Diagnostic one-liners
 
 ```sql
@@ -337,38 +335,20 @@ FROM pg_stat_user_indexes WHERE idx_scan = 0 ORDER BY relname;
 
 ## Verify
 
-Run `scripts/verify.sh` from your project root. It lints discovered SQL with `sqlfluff` (if
+Run `scripts/verify.sh` from your project root: it lints discovered SQL with `sqlfluff` (if
 configured), syntax-sanity-checks migration files (the quote/paren balance check is dollar-quote and
-block-comment aware) and flags foot-guns (`CREATE INDEX` without `CONCURRENTLY` in a migration,
+block-comment aware), flags foot-guns (`CREATE INDEX` without `CONCURRENTLY` in a migration,
 `ADD COLUMN ... NOT NULL` without `DEFAULT`, `VACUUM FULL`), and — only if `DATABASE_URL` and `psql`
 are present — checks that `pg_stat_statements` is enabled. It exits non-zero **only** on a real
-`sqlfluff` lint error; everything else (missing tools, heuristic quote/paren warnings, DB unreachable)
-is advisory `[skip]`/`[warn]`, never a failure. Runs on stock macOS bash 3.2; it never writes and
-never connects without `DATABASE_URL`.
-
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's database decisions there and index them from the root `CLAUDE.md`, so the next
-agent inherits the conventions instead of re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/postgresdb.md`, indexed in `02-DOCS/wiki/index.md` (the
-   Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with the project's real choices — schema and naming conventions, the migration tool, indexing/partitioning decisions, the pooling setup, and any RLS policies —
-   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a
-   short pointer to it).
-3. **Read it first on every use** and stay consistent; when a convention changes, update the
-   article (bump its `Updated` date) in the same change.
-
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
-brand study, technical conventions are *recorded, not gated* — never block the task on this.
-
-## See Also
-
-- [references/schema-and-indexing.md](references/schema-and-indexing.md) — types, constraints, all index kinds, bloat.
-- [references/query-optimization.md](references/query-optimization.md) — EXPLAIN, joins, concurrency, JSONB/FTS/pgvector.
-- [references/migrations.md](references/migrations.md) — zero-downtime DDL, lock-impact table, per-ORM.
-- [references/operations-and-security.md](references/operations-and-security.md) — roles, RLS, pooling, vacuum, partitioning, backups.
-- Sibling skills: [`harness`](../harness/SKILL.md) (scaffolds the `01-TOOLS/POSTGRES` operational tool). Stack siblings: [`fastapi`](../fastapi/SKILL.md), [`nextjs`](../nextjs/SKILL.md), [`go`](../go/SKILL.md), [`flutter`](../flutter/SKILL.md), [`secure-coding`](../secure-coding/SKILL.md), [`deployment`](../deployment/SKILL.md).
-- Out of scope here — these are external tools with their own upstream documentation, not skills in this collection: ORM-surface traps (Prisma's `updateMany` count, serverless connection exhaustion) and per-runner migration wiring (Prisma, Alembic, golang-migrate, Drizzle, …). This skill owns the engine-level SQL and migration mechanics those tools sit on top of; for the tool's own API/CLI, read that tool's docs.
+`sqlfluff` lint error; everything else (missing tools, heuristic warnings, DB unreachable) is advisory
+`[skip]`/`[warn]`. Runs on stock macOS bash 3.2; never writes, never connects without `DATABASE_URL`.
+
+## Project grounding
+
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), read
+`02-DOCS/wiki/stack/postgresdb.md` first and stay consistent with it. Missing or stale? Write the
+project's real choices there — schema and naming conventions, migration tool, indexing/partitioning
+decisions, pooling setup, RLS policies — index it in `02-DOCS/wiki/index.md` (the Knowledge map; root
+`CLAUDE.md` keeps only a pointer), and bump its `Updated` date in the same change, so the next agent
+inherits the conventions instead of re-deriving them. No `02-DOCS/` layer? Skip silently (optionally
+suggest `harness`) — technical conventions are *recorded, not gated*; never block the task on this.

package/skills/presentations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: presentations
-description: "Use when building a presentation deck — a pitch deck, sales deck, product/keynote talk, investor deck, board/QBR review, or a leave-behind one-pager — and you need a stunning, on-brand result exported to PDF and/or an editable PPTX. Covers two production pipelines: design-led Markdown decks (Marp/Slidev themed from the project's design tokens, exported to PDF + PPTX) and native editable PowerPoint via python-pptx (masters, layouts, native charts, tables, speaker notes). Grounds copy in the brand study and visuals in the design tokens; defers the WORDS to `marketing` and the visual system to `design`. Triggers: 'make a deck', 'build a pitch/sales/investor deck', 'slides for my talk', 'turn this doc into slides', 'export to PowerPoint/PPTX', 'Marp', 'Slidev', 'python-pptx', 'keynote deck', 'one-pager'. NOT a video skill (motion is used with restraint, not as the medium)."
+description: "Use when building, theming, or exporting a presentation deck — pitch, sales, keynote, board/QBR, leave-behind one-pager — from slide structure to a token-based theme to PDF or editable PPTX (Marp, Slidev, python-pptx). NOT the words (that is `marketing`), NOT the visual tokens (that is `design`), NOT the investor story arc (that is `pitch-deck`)."
 tags: [presentations, pptx, slides, deck]
 recommends: [marketing]
 origin: risco
@@ -14,82 +14,56 @@ origin: risco
 > The deck owns *structure, visual system, and export*. The **words** are `marketing`'s job; the
 > **visual tokens** are `design`'s. This skill orchestrates all three into a finished deck.
 
-## When to use / When NOT to use
+Also out of scope: a web-native, scroll/animation-heavy **landing page** (that is
+`../design/SKILL.md` + `../nextjs/SKILL.md`); a **video / motion explainer** as the deliverable — this
+skill uses motion only as restrained slide transitions and builds, never as the medium; and the live
+financial *model* behind an investor deck — this skill renders the slides and cites the model as the
+source of truth.
 
-**Use when:**
+## Brand grounding (gate — clears before the first headline)
 
-- Building any deck: pitch, sales, product launch, keynote/conference talk, investor raise, board/QBR review, training/workshop, internal all-hands.
-- Turning an existing doc, memo, or notes into a slide-by-slide deck.
-- Producing a leave-behind one-pager or executive summary alongside a deck.
-- Exporting a deck to PDF (vector, fonts embedded, 16:9) or to an editable `.pptx`.
-- Re-skinning / restructuring an existing deck to be on-brand and less generic.
+**Never produce deck copy or a deck narrative without a complete brand study.** A deck is the brand on
+stage: generic slides read as "another AI deck" the moment they hit the projector, and the only cure is
+grounding every headline, claim, and tone choice in a real, persisted brand profile. This is the same
+gate `marketing` and `design` enforce — decks share the study, they do not fork it.
 
-**Do NOT use when (delegate or decline):**
-
-- Writing the deck's *copy* in isolation (headlines, value prop, narrative voice) → that is `../marketing/SKILL.md`. This skill *consumes* that copy and lays it out.
-- Choosing the brand's *visual tokens* (OKLCH palette, type pairing, spacing scale, motion personality) → that is `../design/SKILL.md`. This skill *consumes* those tokens into a slide theme.
-- A web-native, scroll/animation-heavy **landing page** (not a deck) → `../design/SKILL.md` + `../nextjs/SKILL.md`.
-- A **video / motion explainer** as the deliverable (Manim/Remotion, talking-head, animated short) → that is a video job. This skill uses motion only as restrained slide transitions/builds, never as the medium.
-- A live financial *model* / spreadsheet (the numbers engine behind an investor deck) → that is an investor-materials/modeling job; this skill renders the *slides* and cites the model as the source of truth.
-
-## Brand grounding (read this first)
-
-**Hard rule: never produce deck copy or a deck narrative without a complete brand study.** A deck is the
-brand on stage — generic slides read as "another AI deck" the moment they hit the projector, and the cure
-is grounding every headline, claim, and tone choice in a real, persisted brand profile. This is the same
-hard gate the `marketing` and `design` skills enforce; decks share the study, they do not fork it.
-
-Run this gate before writing a single slide headline:
-
-1. **Locate the brand study.** Read the project's root `CLAUDE.md` for a `## Brand & voice` section linking into `02-DOCS/wiki/brand/` (the `harness` Karpathy-wiki convention: compiled brand articles under `02-DOCS/wiki/brand/`, raw inputs the user pastes under `02-DOCS/raw/brand/`). If `CLAUDE.md` is absent, the link is missing, or it points nowhere, treat the study as ABSENT.
-2. **Check completeness** against the checklist in `references/brand-grounding.md` (it extends the shared brand checklist with **deck-specific** dimensions: deck purpose, audience & setting, length, presenter-vs-leave-behind, and must-include slides). Any empty dimension = INCOMPLETE.
-3. **If ABSENT or INCOMPLETE, STOP and interview the user** — one focused batch at a time (never dump all questions at once). Voice samples are mandatory; never fabricate a voice. Then persist: write/update the brand study under `02-DOCS/wiki/brand/` (raw inputs verbatim under `02-DOCS/raw/brand/`), and add/update the `## Brand & voice` link in root `CLAUDE.md`. Exact format → `references/brand-grounding.md`.
+1. **Locate the brand study.** Read the project's root `CLAUDE.md` for a `## Brand & voice` section linking into `02-DOCS/wiki/brand/` (the `harness` Karpathy-wiki convention: compiled brand articles under `02-DOCS/wiki/brand/`, raw inputs the user pastes under `02-DOCS/raw/brand/`). No `CLAUDE.md`, no link, or a link that points nowhere = ABSENT.
+2. **Check completeness** against the checklist in `references/brand-grounding.md` — it extends the shared brand checklist with **deck-specific** dimensions: deck purpose, audience & setting, length, presenter-vs-leave-behind, and must-include slides. Any empty dimension = INCOMPLETE.
+3. **If ABSENT or INCOMPLETE, STOP and interview the user** — one focused batch at a time, never all questions at once. Voice samples are mandatory; never fabricate a voice. Then persist: write/update the brand study under `02-DOCS/wiki/brand/` (raw inputs verbatim under `02-DOCS/raw/brand/`), and add/update the `## Brand & voice` link in root `CLAUDE.md`. Exact format → `references/brand-grounding.md`.
 4. **Only once the study is complete, proceed** — and cite which articles drove the deck (e.g. "narrative grounded in `02-DOCS/wiki/brand/value-proposition.md`, voice in `voice.md`").
 
-If the user explicitly says "skip it, rough draft", you may produce a clearly-labelled `DRAFT (ungrounded — not brand-checked)` and still recommend running the gate before it ships. That is the only exception, and it must be labelled.
-
-## The non-negotiables
+Single exception: if the user explicitly says "skip it, rough draft", you may produce a clearly-labelled
+`DRAFT (ungrounded — not brand-checked)` and still recommend running the gate before it ships.
 
-These are constraints, not preferences. Violating any one is a defect.
+## Design the message before the pixels
 
-1. **Brand study first, then narrative, then layout, then export.** No deck before the grounding gate passes. Cite the articles you used.
-2. **One idea per slide.** A slide that needs two breaths to explain is two slides. If you can't title it with one assertion, it isn't one slide.
-3. **The headline IS the slide.** Write assertion headlines ("Churn fell 40% after onboarding v2"), not topic labels ("Churn"). The audience reads the headline; the body proves it.
-4. **Legible from the back of the room.** Body text ≥ 24pt (≥ 28–32pt for talks); ~6 words/line, ~6 lines/slide as a ceiling, not a target. Contrast ≥ 4.5:1. If it doesn't read at 3 metres, it doesn't ship.
-5. **16:9, fonts embedded, exports verified.** PDF is vector with fonts embedded; PPTX opens clean in PowerPoint/Keynote/Google Slides. Run `scripts/verify.sh` before claiming done.
-6. **Tokens, not magic numbers.** Colors, type scale, and spacing come from the project's `design` tokens (OKLCH → the deck theme), never hand-picked hex per slide.
-7. **Motion with restraint.** One transition family, fast (≤ 300ms), builds reveal *meaning* (one bullet at a time), not decoration. Honor reduced-motion in HTML pipelines. A deck is not a video.
-8. **No invented numbers.** Every metric on a slide traces to a source (the model, analytics, a citation). Mark gaps `[[NEEDS PROOF]]`; never fabricate to fill a chart.
-
-## Design first (assertion-evidence + cognitive load)
-
-Before a pipeline, a theme, or a single pixel: a deck is a *communication* artifact, and the design that
-matters most is the message design. The one principle everything below descends from is **audience-centered
-design** — every choice serves the audience's understanding, not the presenter's comfort.
+A deck is a *communication* artifact, so the design that matters most is the message design. Everything
+below descends from **audience-centered design** — every choice serves the audience's understanding, not
+the presenter's comfort.
 
 **Plan the message (six questions).** Lock these before storyboarding: (1) who *specifically* is the
 audience and what do they already know; (2) the ONE main message they remember a week later; (3) the 3–5
 supporting points that carry it; (4) the evidence proving each; (5) the single call-to-action; (6) what is
-essential vs. expandable under time pressure. These feed straight into the deck arc — message = thesis,
-points = beats, CTA = closing ask (→ `references/storytelling-and-decks.md`).
+essential vs. expandable under time pressure. These feed the deck arc directly: message = thesis, points =
+beats, CTA = closing ask (→ `references/storytelling-and-decks.md`).
 
 **Assertion-evidence is the slide unit.** Each slide = one assertion (a complete claim, written as the
 title) + the visual evidence that proves it — never a topic label over a bullet list. *"User engagement rose
-43% after the redesign"* + a chart, not *"Engagement"* + three bullets. This is non-negotiable #3 made
-concrete: the body proves the headline, it does not repeat it.
+43% after the redesign"* + a chart, not *"Engagement"* + three bullets. The body proves the headline; it
+never repeats it.
 
-**Manage cognitive load: one concept per slide.** Working memory is small and the audience is also listening
-to you. If a slide needs two breaths to explain, it's two slides. Reveal sequential parts progressively
-(build order *is* the explanation) rather than dumping everything at once.
+**One concept per slide.** Working memory is small and the audience is also listening to you. If a slide
+needs two breaths to explain, it's two slides. Reveal sequential parts progressively — build order *is* the
+explanation — rather than dumping everything at once.
 
-**Spoken vs. shown — never both.** The slide and your mouth are two channels; redundancy wastes both. Show
-the assertion, the visual, the number, the next step; *say* the elaboration, the context, the
-interpretation, the story. Reading slides verbatim is the fastest way to lose a room.
+**Spoken vs. shown — never both.** The slide and your mouth are two channels; redundancy wastes both. *Show*
+the assertion, the visual, the number, the next step; *say* the elaboration, the context, the interpretation,
+the story. Reading slides verbatim is the fastest way to lose a room.
 
 Full frameworks — the planning questions, the spoken/shown table, the **1–5 evaluation rubric**
 (audience-centered / visual clarity / cognitive load / accessibility), the implementation checklist, and the
 communication anti-patterns — live in `references/slide-design.md`. Score any draft against the rubric (≥ 4
-on each axis) before shipping; the Deck QA gate below points back to it.
+on each axis) before shipping.
 
 ## Which pipeline? (decide before building)
 
@@ -186,10 +160,8 @@ Always pin/verify the version in the target project before generating (`marp --v
 The deck's words are conversion copy on a stage. Defer the *craft* to `../marketing/SKILL.md`; this skill
 enforces the deck-specific shape:
 
-- **Assertion headline per slide.** Not "Market", but "TAM is $12B and growing 24%/yr". The headline carries the point; the body is evidence.
 - **Benefit-led, climbing feature → benefit → proof**, stopping at the rung the audience cares about. Specificity (a number, a mechanism, a receipt) beats adjectives — "2× faster" not "blazing fast".
-- **Minimal text.** Presenter decks: a headline + one visual + 0–3 support points; the argument lives in the speaker notes / your mouth. Leave-behinds may carry more, because no one's narrating.
-- **Two variants when both are needed:** *presenter* (sparse, you narrate) vs *leave-behind* (self-contained, sent as PDF). Same narrative, different text density — never ship a wall-of-text presenter slide.
+- **Two text densities, chosen deliberately:** *presenter* slides carry a headline + one visual + 0–3 support points, with the argument in the speaker notes / your mouth; *leave-behind* slides are self-contained because no one is narrating. Never ship a wall-of-text presenter slide.
 - **Voice from the brand study.** Headlines obey the do/don't word lists and tone samples. Ban-list words ("revolutionary", "seamless", "game-changer", "supercharge") are defects.
 
 ## Visual system for slides (with `design`)
@@ -199,11 +171,11 @@ The deck's pixels are the brand's design system projected at 3 metres. Defer the
 `references/slide-design.md`):
 
 - **Layout grid** built for 16:9: a 12-column grid, generous margins, one focal point per slide, consistent safe-area so nothing clips on a projector.
-- **Type scale for projection**, not for a laptop reading distance: display/headline/body/caption steps, body ≥ 24pt, line length ~6 words, never below the legibility floor to cram text.
-- **Color from tokens, allocated for a room:** dark deck themes read better in dark rooms / on big screens; light themes for printed handouts and bright rooms. High contrast always; never rely on color alone to encode meaning.
-- **Data viz that makes one point:** one chart = one takeaway named in the headline; remove gridlines/clutter; label directly; pre-attentive emphasis (one highlighted bar/line) over rainbow palettes; never a 3-D pie.
+- **Type scale for projection**, not laptop reading distance: display/headline/body/caption steps, body ≥ 24pt (≥ 28–32pt for talks), ~6 words/line and ~6 lines/slide as a ceiling, contrast ≥ 4.5:1. Never drop below the legibility floor to cram text — split the slide instead. If it doesn't read at 3 metres, it doesn't ship.
+- **Color from tokens, allocated for a room:** dark themes read better in dark rooms / on big screens, light themes for printed handouts and bright rooms. High contrast always; never rely on color alone to encode meaning.
+- **Data viz that makes one point:** one chart = one takeaway named in the headline; remove gridlines/clutter; label directly; pre-attentive emphasis (one highlighted bar/line) over rainbow palettes; never a 3-D pie. Every number traces to a source — mark gaps `[[NEEDS PROOF]]`, never fabricate one to fill a chart.
 - **Imagery** full-bleed and intentional (with a legibility scrim behind text), not stocky decoration; respect resolution so it doesn't pixelate on a 4K projector.
-- **Motion with restraint:** one transition family, builds that reveal one idea at a time, ≤ 300ms; reduced-motion honored in HTML pipelines. Animation explains sequence/state change, never just fills time.
+- **Motion with restraint:** one transition family, ≤ 300ms, builds that reveal one idea at a time; reduced-motion honored in HTML pipelines. Animation explains sequence/state change, never just fills time.
 
 ## Anti-patterns
 
@@ -253,7 +225,8 @@ npx decktape reveal http://localhost:8000 deck.pdf
 
 ## Deck QA gate
 
-Run before claiming done. `scripts/verify.sh` automates the mechanical subset.
+Run before claiming done — each line is a defect if unchecked. `scripts/verify.sh` automates the
+mechanical subset.
 
 - [ ] Brand study located, complete, and cited (which articles grounded the deck).
 - [ ] One idea per slide; every slide titled with an assertion headline, not a topic label.
@@ -269,28 +242,17 @@ Run before claiming done. `scripts/verify.sh` automates the mechanical subset.
 - [ ] File size sane (compressed images, subsetted fonts); ban-list words absent from copy.
 - [ ] Scored ≥ 4/5 on each axis of the design rubric — audience-centered, visual clarity, cognitive load, accessibility (→ `references/slide-design.md`, "Diagnostic rubric").
 
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this project's deck
-conventions there and index them from the root `CLAUDE.md`, so the next agent inherits them instead of
-re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/presentations.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with this project's real choices — the chosen pipeline (Marp / Slidev / python-pptx) and why; the theme file path and how it maps the design tokens (`02-DOCS/wiki/stack/design.md`); the standard deck arc(s); export commands and the canonical output (PDF / PPTX); presenter-vs-leave-behind convention; font-embedding and asset-location notes — then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
-3. **Read it first on every use** and stay consistent; when a convention changes, update the article (bump its `Updated` date) in the same change.
-
-The deck theme is downstream of the design tokens: always reconcile `02-DOCS/wiki/stack/presentations.md`
-with `02-DOCS/wiki/stack/design.md` so the deck and the product share one palette and type system.
+## Project grounding (02-DOCS)
 
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Like the other technical
-conventions and unlike the brand study, deck conventions are *recorded, not gated* — never block the task
-on this.
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), read
+`02-DOCS/wiki/stack/presentations.md` first and stay consistent with it; create or refresh it when
+missing or stale, and index it in `02-DOCS/wiki/index.md`. It records this project's real choices: the
+chosen pipeline (Marp / Slidev / python-pptx) and why, the theme file path and how it maps the design
+tokens, the standard deck arc(s), export commands and the canonical output, the presenter-vs-leave-behind
+convention, and font-embedding / asset-location notes.
 
-## See Also
+The deck theme is downstream of the design tokens: always reconcile that article with
+`02-DOCS/wiki/stack/design.md` so the deck and the product share one palette and type system.
 
-- `../marketing/SKILL.md` — **the copy**: headlines, value prop, benefit-led claims, the deck's voice. This skill consumes that copy and lays it out.
-- `../design/SKILL.md` — **the visuals**: OKLCH tokens, type pairing, spacing, motion personality. This skill maps those tokens into the slide theme and reads `02-DOCS/wiki/stack/design.md`.
-- `../nextjs/SKILL.md` — when a "deck" is actually a web-native landing/microsite, the build belongs there.
-- `../harness/SKILL.md` — the `02-DOCS` Karpathy-wiki convention the brand study and deck conventions persist into.
-- References: `references/storytelling-and-decks.md` (arcs + slide-by-slide skeletons), `references/markdown-decks.md` (Marp + Slidev theming & export), `references/pptx-python.md` (python-pptx recipes), `references/slide-design.md` (visual system + data viz + motion), `references/brand-grounding.md` (checklist + question script).
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the brand study, deck
+conventions are *recorded, not gated* — never block the task on this.

package/skills/python/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: python
-description: "Use when writing, reviewing, modernizing, typing, or packaging Python at the language level (any framework or none) - PEP 695 generics and the type-alias statement, mypy --strict typing, dataclasses/Protocol/TypedDict/Enum choices, asyncio.TaskGroup and structured concurrency, stdlib idioms (pathlib/itertools/functools/contextlib/match), src/ layout + pyproject.toml managed with uv, and a ruff+mypy+pytest verify gate. Triggers: 'set up a Python project with uv', 'is this Pythonic / modernize to 3.12+', 'make mypy --strict pass', 'convertir este gather a TaskGroup', 'dataclass slots frozen vs NamedTuple', any .py file or pyproject.toml. NOT building a FastAPI/ASGI service (that is fastapi), NOT a deep pytest fixture/mock suite (that is testing-py)."
+description: "Use when the task is Python itself, in any framework or none: PEP 695 generics, mypy --strict typing, dataclass/Protocol/TypedDict/Enum choices, asyncio.TaskGroup, stdlib idioms, src/ layout + pyproject.toml with uv, ruff+mypy+pytest gate. NOT a FastAPI/ASGI service (that is fastapi), NOT a deep pytest suite (that is testing-py)."
 tags: [python, typing, async, packaging, uv]
 recommends: [fastapi, secure-coding, deployment]
 origin: risco
@@ -20,15 +20,7 @@ annotations`), PEP 750 template strings (`t"..."`), and `compression.zstd`. Tool
 **uv 0.11** (project + package manager), **ruff 0.15** (lint + format), **mypy 1.20
 `--strict`** (or Astral's `ty`, still preview — default to mypy), **pytest 8**.
 
-## When to use / When NOT to use
-
-**Use when** the question is *the language* in any `.py` file or `pyproject.toml`: typing,
-generics, protocols, dataclass/NamedTuple/TypedDict/Enum choices, async (`TaskGroup`, timeouts,
-cancellation — not a web server), comprehensions, context managers, error handling; setting up a
-project from zero with `uv` (init, venv, lockfile, scripts); modernizing to PEP 695; or wiring
-the `ruff` + type-checker + `pytest` + `verify.sh` gate.
-
-**When NOT to use (delegate):**
+## Scope — what this skill delegates
 
 - Building a FastAPI / ASGI service (routes, Pydantic models, SQLAlchemy, uvicorn) ->
   [`fastapi`](../fastapi/SKILL.md). That skill owns the service shape; this one owns the
@@ -56,19 +48,10 @@ Apply on every Python edit:
    unindented — arrow code hides the logic.
 3. **Stdlib before a dependency.** `pathlib`, `itertools`, `functools`, `dataclasses`,
    `collections` cover most needs; a new dep is a maintenance liability you must justify.
-4. **One `pyproject.toml`, managed with uv.** Never hand-edit `requirements.txt`; `uv add`
-   writes the dep and updates `uv.lock`, which you commit.
-5. **Prefer immutability.** `@dataclass(frozen=True, slots=True)` for value objects; mutate
+4. **Prefer immutability.** `@dataclass(frozen=True, slots=True)` for value objects; mutate
    only where you must — shared mutable state is the bug you debug at 2am.
-6. **`pathlib`, not `os.path`.** `Path("a") / "b"` over `os.path.join`; it is typed and composable.
-7. **Structured `logging`, never `print` in a library.** `print` writes to a caller's stdout
-   you do not own; `logging.getLogger(__name__)` lets them configure it.
-8. **`asyncio.TaskGroup` over bare `gather`.** A `TaskGroup` cancels siblings on first error and
-   propagates an `ExceptionGroup`; `gather` leaks tasks on failure (rule 8 in Async below).
-9. **No mutable default arguments.** `def f(xs: list[int] | None = None)` then `xs = xs or []`;
-   `def f(xs=[])` shares one list across all calls — a classic latent bug.
-10. **Everything passes the gate.** `ruff check` + `ruff format --check` + `mypy --strict` +
-    `pytest` — green locally via `scripts/verify.sh` before you call it done.
+5. **Everything passes the gate.** `ruff check` + `ruff format --check` + `mypy --strict` +
+   `pytest` — green locally via `scripts/verify.sh` before you call it done.
 
 ## Typing
 
@@ -95,7 +78,7 @@ annotations`.
 
 Full PEP 695 bounds/constraints/variance, `Protocol` vs ABC, `TypedDict`
 `Required`/`NotRequired`, `ParamSpec`/`TypeVarTuple`, `TypeGuard`/`TypeIs`, `cast`, and common
-`--strict` errors with fixes -> `references/typing.md`.
+`--strict` errors with fixes -> [`references/typing.md`](references/typing.md).
 
 ## Data modeling
 
@@ -129,11 +112,13 @@ the thing genuinely *is* a small tuple you also unpack positionally.
 Reach into the stdlib before adding a dependency.
 
 - **`pathlib`** for all filesystem paths: `Path("data") / name`, `p.read_text()`,
-  `p.glob("*.json")`, `p.with_suffix(".bak")`.
+  `p.glob("*.json")`, `p.with_suffix(".bak")` — typed and composable, never `os.path.join`.
 - **`collections`**: `defaultdict(list)`, `Counter(words)`, `deque(maxlen=100)` for ring buffers.
 - **`itertools`**: `chain`, `groupby`, `islice`, `batched` (3.12+) instead of hand-rolled loops.
 - **`functools`**: `@cache` / `@lru_cache` for pure memoization, `@cached_property`, `partial`.
 - **`contextlib`**: `@contextmanager`, `ExitStack` for dynamic resource sets, `suppress(FileNotFoundError)`.
+- **`logging`**, never `print` in a library: `print` writes to a caller's stdout you do not own;
+  `logging.getLogger(__name__)` lets them configure it.
 
 Prefer comprehensions over `map`/`filter`+`lambda`; prefer a generator (`(... for ...)`) when
 you only iterate once. Use `match` for structural dispatch over a chain of `isinstance`:
@@ -158,7 +143,7 @@ f-strings for formatting; note 3.14's PEP 750 `t"..."` template strings yield a
 (not a `str`) for *safe custom interpolation* (e.g. escaping) — use them when an f-string would
 inject untrusted text. Full cookbook (itertools/functools/collections recipes, `match`
 patterns, dataclass `field`/`default_factory`/`__post_init__`, `Enum`/`StrEnum`/`IntFlag`) ->
-`references/stdlib.md`.
+[`references/stdlib.md`](references/stdlib.md).
 
 ## Errors & resources
 
@@ -205,7 +190,8 @@ Bound every wait with `async with asyncio.timeout(5.0):`. On `CancelledError`, c
 concurrency only; CPU-bound work blocks the loop — push it to `asyncio.to_thread` / a
 `ProcessPoolExecutor` (or 3.14's free-threaded build). **HTTP servers belong to
 [`fastapi`](../fastapi/SKILL.md), not here.** Runtime model, `ExceptionGroup`/`except*`, queues
-with backpressure, cancellation discipline, and sync<->async bridging -> `references/async.md`.
+with backpressure, cancellation discipline, and sync<->async bridging ->
+[`references/async.md`](references/async.md).
 
 ## Project layout & packaging (uv)
 
@@ -221,7 +207,8 @@ myapp/
   scripts/verify.sh
 ```
 
-`pyproject.toml` is the single config — PEP 621 metadata, dependency groups, and tool config:
+`pyproject.toml` is the single config — PEP 621 metadata, dependency groups, and tool config.
+Never hand-edit a `requirements.txt`; `uv add` writes the dep and updates `uv.lock`, which you commit.
 
 ```toml
 [project]
@@ -306,9 +293,9 @@ random.random()  # tokens                       secrets.token_urlsafe(32)      #
 Keep deps locked (`uv.lock`) and audited (`pip-audit` / `uv` resolution); read secrets from
 env or a secret manager, never hardcode or log them.
 
-## Anti-patterns / rationalizations -> STOP
+## Anti-patterns -> STOP
 
-| Rationalization | Reality / Do instead |
+| Tempting move | Reality / do instead |
 | --- | --- |
 | "`def f(xs=[])` is fine, it's empty" | One list shared across all calls; use `= None` then `xs = xs or []`. |
 | "bare `except:` to be safe" | Swallows `KeyboardInterrupt`/bugs; catch a specific type. |
@@ -323,47 +310,11 @@ env or a secret manager, never hardcode or log them.
 | "`pickle.loads` the cache, it's ours" | Any untrusted byte = code execution; use `json`. |
 | "explicit `TypeVar` everywhere" | New code uses PEP 695 `def f[T]` / `class C[T]` / `type X`. |
 
-## Quick reference
+## Project grounding (02-DOCS)
 
-| Task | Command / idiom |
-| --- | --- |
-| New project | `uv init --package myapp` |
-| Add dep / dev dep | `uv add httpx` / `uv add --dev pytest` |
-| Reproducible install | `uv sync --frozen` |
-| Run in venv | `uv run python -m myapp` |
-| Lint + autofix | `uv run ruff check --fix .` |
-| Format (check) | `uv run ruff format --check .` |
-| Type check | `uv run mypy --strict src` |
-| Test | `uv run pytest -q` |
-| Local gate | `./scripts/verify.sh` |
-| Generic | `def f[T](x: T) -> T:` / `type Alias = ...` |
-| Optional | `X | None` (not `Optional[X]`) |
-| Structured async | `async with asyncio.TaskGroup() as tg: tg.create_task(...)` |
-| Memoize | `@functools.cache` |
-| Token | `secrets.token_urlsafe(32)` |
-
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this project's Python conventions
-there so the next agent inherits them — *recorded, not gated*, never block the task on this.
-
-1. **Find** `02-DOCS/wiki/stack/python.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, write the project's real choices (interpreter floor, `src/` layout,
-   uv workflow, ruff/mypy config, async-vs-sync stance, data-modeling defaults) and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
-3. **Read it first on every use**; bump its `Updated` date when a convention changes.
-
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`).
-
-## See Also
-
-Sibling skills: [`fastapi`](../fastapi/SKILL.md) (the FastAPI/ASGI service shape — this skill
-owns the language it is written in), [`secure-coding`](../secure-coding/SKILL.md) (language-
-agnostic threat modeling/authz — this skill keeps the Python-specific controls),
-[`deployment`](../deployment/SKILL.md) (Containerfile/CI/shipping — this skill ships only the
-uv CI note), and `testing-py` (by id; deep pytest technique — this skill carries only the baseline).
-
-Local references (read when): `references/typing.md` (PEP 695 generics, Protocol vs ABC,
-TypedDict, narrowing, `--strict` fixes); `references/async.md` (asyncio model, TaskGroup vs
-gather, timeouts, cancellation, queues, CPU-bound); `references/stdlib.md`
-(itertools/functools/collections/contextlib/pathlib cookbook, `match`, dataclasses, Enum).
+In a project that has the [`harness`](../harness/SKILL.md) wiki, record this project's Python
+conventions in `02-DOCS/wiki/stack/python.md` and index it in `02-DOCS/wiki/index.md` — the
+interpreter floor, `src/` layout, uv workflow, ruff/mypy config, async-vs-sync stance, and
+data-modeling defaults. Read it first on every use and bump its `Updated` date when a convention
+changes. This is *recorded, not gated*: never block the task on it, and skip silently when there
+is no `02-DOCS/` layer.