skilldrop-cli 0.2.0

package/skills/data-contract/reference.md

@@ -0,0 +1,46 @@
+# data-contract reference — quality dimensions, evolution matrix, field semantics
+
+## Data-quality dimension catalog
+
+Each dimension on the contract gets: a **threshold**, a **check** (how/when measured), and a **breach action**. Pick the dimensions that matter for this asset; mark the rest n/a with a reason.
+
+| Dimension | What it guarantees | Threshold example | Check | Breach action examples |
+|---|---|---|---|---|
+| **Freshness** | data is recent enough to trust | partition D lands by 06:00 D+1 | scheduler SLA / landing-time monitor | page owner; mark stale on the dashboard |
+| **Completeness** | nothing silently missing | row count within ±10% of trailing-7d median; all partitions present | post-load count check | quarantine partition; block downstream |
+| **Validity** | values satisfy field constraints | ≥99.9% rows pass per-field rules | constraint suite per load | reject load; alert; route bad rows to DLQ |
+| **Uniqueness** | the key is actually unique | `event_id` 100% unique | dup-count query | breach = contract violation, not silent dedup |
+| **Consistency** | cross-field/cross-table invariants hold | `ends_at` ≥ `starts_at`; FK resolves | invariant assertions | alert; hold publish |
+| **Distribution / drift** | columns consumers model don't shift unannounced | null-rate, cardinality, mean within historical band | drift monitor vs baseline | alert consumers; investigate before publish |
+| **Timeliness of correction** | how fast a known-bad load is fixed | corrected within {N}h of detection | incident clock | comms to consumers (→ `incident-comms`) |
+
+A dimension with no breach action is decoration. The breach action is the part consumers actually rely on.
+
+## Schema-evolution safe/breaking matrix (for DATA consumers)
+
+"Breaking" here means: a downstream query, pipeline, or trained model could silently produce wrong results or fail. Data consumers are more fragile than API clients — `SELECT *`, positional reads, and models that learned a column's distribution all break in ways HTTP clients don't.
+
+| Change | Safe? | Notes |
+|---|---|---|
+| Add optional/nullable column **with** default or documented null-meaning | usually safe | still breaks strict `SELECT *` schema checks — notify |
+| Add `NOT NULL` column without default | **breaking** | every existing writer fails |
+| Remove or rename a column | **breaking** | rename = remove + add; positional/`*` consumers break |
+| Change type (even "widening") | **breaking** | int→float shifts joins, aggregations, model features |
+| **Change the meaning** behind a stable name+type | **breaking — the silent killer** | gross→net, UTC→local, cents→dollars: no validator catches it; only the contract can |
+| Narrow an enum (remove an allowed value) | **breaking** | consumers branching on it lose a case |
+| Widen an enum (add an allowed value) | maybe breaking | breaks consumers with exhaustive switches; declare enum open/closed |
+| Tighten a constraint (e.g. now `NOT NULL`) | **breaking** | historical rows / lenient writers violate it |
+| Loosen a constraint | usually safe | but consumers assuming the old guarantee may break |
+| Change partitioning / sort | **breaking for performance** | consumer queries may table-scan or time out |
+
+**Every breaking change requires:** version bump → deprecation window (name it, e.g. 30 days or until all registered consumers ack) → notification to the registered consumer list → both versions available during the window where feasible. This mirrors `migration-plan`'s expand/contract — apply it to the schema.
+
+## Field-semantics rules (the cents-vs-dollars firewall)
+
+Every field on the contract states:
+- **Unit** for any quantity — currency + minor/major units, time unit, byte/bit, percentage-as-0-1-vs-0-100. The single most common silent data bug is a unit assumption.
+- **Allowed values** for any categorical — the full enum, open or closed.
+- **Null semantics** — is `null` "unknown", "not applicable", or "zero"? These are three different facts; pick one and write it.
+- **Timezone** for any timestamp — UTC unless stated; name the zone, never leave it implicit.
+- **Meaning** — one line a new consumer reads instead of guessing. "`status`: lifecycle state of the order, see allowed values" beats inferring from the name.
+- **Identity** — which field(s) uniquely identify a row, and whether IDs are stable across reloads.

package/skills/data-contract/templates/data-contract.md

@@ -0,0 +1,69 @@
+# Data-contract template
+
+A dataset is a product. This is its label, its warranty, and its change policy.
+
+```markdown
+# Data contract: {asset name}
+
+**Asset:** {warehouse table | Kafka topic | file feed | view} — `{fully.qualified.name}`
+**Owner:** {team/role} · **Contact / on-call:** {channel}
+**Producer:** {pipeline/service} · **Update mechanism:** {batch | streaming | CDC}
+**Version:** {v1} · **Status:** {proposed | active | deprecated}
+
+## Consumers (defines what "breaking" means)
+
+| Consumer | Team | Usage | Notify on change |
+|---|---|---|---|
+| {dashboard/model/pipeline} | {team} | {what they read it for} | {channel} |
+
+⚠ {Flag any unknown/unregistered consumers — a change can't be safely made until known.}
+
+## Schema (types + semantics)
+
+| Field | Type | Req? | Null means | Unit / allowed values | Meaning |
+|---|---|---|---|---|---|
+| `event_id` | string | required | — | opaque UUID | unique row identity, stable across reloads |
+| `amount` | int64 | required | — | minor units (cents), {currency} | net charged after discounts |
+| `country` | string | optional | unknown | ISO-3166-1 alpha-2, open enum | billing country |
+| `occurred_at` | timestamp | required | — | UTC, ISO-8601 | when the event happened (not when ingested) |
+
+**Identity:** {field(s) that uniquely identify a row}
+**Grain:** {one row per … }
+
+## Quality SLAs
+
+| Dimension | Threshold | Check | Breach action | Met today? |
+|---|---|---|---|---|
+| Freshness | partition D by 06:00 D+1 | landing monitor | page owner | ✅ / aspirational |
+| Completeness | rows within ±10% of 7d median | post-load count | quarantine partition | … |
+| Validity | ≥99.9% pass field rules | constraint suite | reject load, alert | … |
+| Uniqueness | `event_id` 100% unique | dup query | contract breach | … |
+| Distribution | null-rate/cardinality in band | drift monitor | alert consumers | … |
+
+{Mark each "Met today?" honestly: ✅ currently met, or "aspirational — pipeline does not yet meet this".}
+
+## Schema-evolution policy
+
+- Safe (notify only): {additive nullable columns with documented null-meaning}
+- Breaking (version bump + deprecation window + consumer ack): removals, renames, type changes, **meaning changes under a stable name**, enum narrowing, constraint tightening, partition changes.
+- Deprecation window: {e.g. 30 days, or until all registered consumers ack}; both versions live during the window where feasible.
+- Meaning-change clause: a field's documented meaning is part of the contract; changing it (e.g. gross→net) is breaking even if name and type are unchanged.
+
+## Delivery
+
+- **Location / format:** {path or topic} · {Parquet | Avro | JSON}
+- **Partitioning:** {scheme}
+- **Cadence:** {hourly | daily 06:00 | continuous}
+- **Streaming only:** delivery {at-least-once → dedupe on identity}; ordering {per-key | none}; retention {N days}
+- **Register as a consumer:** {how — so breaking-change notices reach you}
+
+## Classification & retention
+
+| Field(s) | Classification | Retention | Residency |
+|---|---|---|---|
+| {field} | {PII / sensitive / public} | {period} | {constraint or none} |
+
+## Open questions
+
+- {unknowns blocking sign-off — e.g. undiscovered consumers, an SLA not yet measurable}
+```

package/skills/db-schema-design/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: db-schema-design
+description: Design a database schema from access patterns — paradigm chosen deliberately (relational/document/key-value/wide-column/graph), keys and partitioning driven by the actual queries, indexes mapped to predicates, money/time types right, and every read path verified to have a supporting access path. Use when the user is designing a data model, schema, or tables for a feature, choosing a database, or asks how to structure/store data.
+---
+
+# db-schema-design
+
+Designs the storage layer **from the queries backward** — because a schema is right or wrong only relative to how it's read and written, and the most expensive schema mistakes are the access paths nobody designed for. Distinct from `data-contract` (the guarantee on a *published* dataset) and `api-contract-draft` (the sync interface): this is the table/collection/key design underneath. Hands evolution off to `migration-plan` and the published-dataset guarantee to `data-contract`.
+
+## How to respond
+
+1. **Collect the access patterns before drawing a single table.** The deliverable starts as a list: each read and write the feature needs, with **frequency**, **latency sensitivity**, **selectivity** (one row / a range / a scan), and **consistency need** (read-your-writes? eventual ok?). Ask at most 2 questions, spent on the highest-frequency query and the largest-growth entity. A schema designed from the entity diagram instead of the queries is how you get a clean model that can't serve its hottest path.
+
+2. **Choose the paradigm deliberately, with a reason** (selection matrix in [`reference.md`](reference.md)). Relational is the correct default for most transactional features and needs no defense; reaching *past* it does. ✅ *"Document store — the entity is read and written whole, no cross-entity queries, and the shape varies per type"* — ❌ *"NoSQL because scale"* (scale is a property of access patterns and data size, not a vibe). For NoSQL especially, the access patterns *are* the schema — you cannot add a query later for free the way SQL lets you.
+
+3. **Design keys from the queries.**
+   - **Relational:** surrogate key (e.g. `bigint`/ULID) as PK by default; natural keys get a unique constraint, not the clustered PK. Avoid random UUIDv4 as a clustered/primary key — it scatters writes and splits pages; use a time-ordered ID (ULID/UUIDv7) when you need a UUID and ordered inserts.
+   - **NoSQL:** partition key + sort key derived directly from the access patterns, chosen to spread load (no hot partition) and to co-locate what's read together. State the query each key shape serves.
+
+4. **Normalize to 3NF, then denormalize only for a named read pattern — and name the sync obligation.** 3NF is the default because it makes writes correct and anomalies impossible. Every denormalization is a deliberate trade for a specific hot read, and it incurs a duplicate-keeping-in-sync debt that must be stated: ✅ *"Cache `order_count` on `customer` for the dashboard's top query; kept in sync by the order-write transaction / a trigger"* — ❌ a denormalized field with no answer to "what updates the copy?".
+
+5. **Index for the actual predicates, joins, and sorts — not speculatively.** Every index pays a write cost and storage; an unused index is pure overhead. Rules (full set in [`reference.md`](reference.md)): index the columns in `WHERE`/`JOIN`/`ORDER BY` of real queries; **composite index column order is equality-first, then range, then sort**; consider a covering index for a hot read; don't index low-selectivity columns alone. Map each index to the query it serves — an index with no query is a guess.
+
+6. **Get the types and constraints right at the schema, not in app code.** Money as integer minor units or `decimal`, **never float** (echoes `data-contract`); timestamps with explicit timezone (store UTC); enums as a constrained type or lookup table, not free strings; `NOT NULL` + defaults + `CHECK` + foreign keys express invariants the database enforces for every writer, including the ones you'll add later. Right-size types (don't `text` a 2-char country code).
+
+7. **State the scale and multitenancy decisions.** Name the table that grows unbounded and its plan (partition by time, archive cold data); the partition/shard strategy if any (and why it's not premature); and the **multitenancy isolation model** (shared-table + `tenant_id` with row-level security / schema-per-tenant / db-per-tenant) with its trade — this is an early decision that's brutal to reverse, so it's explicit, not defaulted.
+
+8. **Verify every access pattern has a supporting path, and emit with [`templates/schema-design.md`](templates/schema-design.md)** in one message: access-pattern table, paradigm + rationale, the schema (tables/collections with columns, types, keys, constraints), relationships/cardinality, indexes mapped to queries, scale + multitenancy decisions, and the **verification table** — each access pattern → the key or index that serves it, with any that fall to a full scan flagged. Evolution → `migration-plan`; published-to-consumers → `data-contract`.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — paradigm-selection matrix, key-design rules, the normalization/denormalization ladder, indexing rules, multitenancy options, and the schema anti-pattern catalog
+- [`templates/schema-design.md`](templates/schema-design.md) — the design skeleton with access-pattern, schema, index, and verification tables
+
+## Quality bar
+
+- **Access patterns are listed before the schema**, with frequency and selectivity. A schema with no query list was designed blind.
+- **The paradigm choice has a reason tied to access patterns** — and relational-by-default needs none while every move past it does.
+- **Keys are justified by queries**, and no random UUIDv4 sits as a clustered PK without a noted reason.
+- **Every index maps to a real query**; every denormalization names what keeps the copy in sync.
+- **Money is never float, timestamps carry timezone, invariants are DB constraints** — not left to application discipline.
+- **Multitenancy and the unbounded-growth table have explicit plans.** The expensive-to-reverse decisions are made on purpose.
+- **The verification table shows each access pattern's supporting path**, with full scans flagged rather than hidden.
+
+## When to use this skill
+
+- ✅ Designing tables/collections/keys for a new feature or service
+- ✅ Choosing a database paradigm for a known set of access patterns
+- ✅ "How should I structure / store this data?" with real queries in mind
+- ✅ Reworking a schema whose hot query has no supporting index
+
+## When NOT to use this skill
+
+- ❌ Governing a dataset other teams consume (quality SLAs, evolution policy) — that's `data-contract`
+- ❌ The sync API/event shape over the data — that's `api-contract-draft`
+- ❌ Executing a schema change on a live system (expand/backfill/contract) — that's `migration-plan`
+- ❌ Picking a specific managed product (Aurora vs Cloud SQL) — that's `tech-comparison-matrix`; this designs the model, not the vendor
+
+## Anti-patterns to avoid
+
+- ❌ **Entity-first, query-never.** A beautiful normalized ER diagram whose top query needs four joins and a full scan. Design from the access patterns.
+- ❌ **"NoSQL for scale" with no access-pattern argument.** NoSQL trades ad-hoc query flexibility for scale on *known* patterns; choosing it blind buys the downside without the upside.
+- ❌ **UUIDv4 as the clustered primary key.** Random keys scatter inserts and fragment the index; use a time-ordered ID when you need a UUID.
+- ❌ **EAV / the god table.** Entity-attribute-value "flexible" schemas and 80-column catch-all tables are queryability and integrity sold for a flexibility you'll regret.
+- ❌ **JSON-blob-as-schema-avoidance.** Dumping everything in a `jsonb` column to skip design, then writing queries that dig into it with no index — schema design deferred, not avoided, and now unindexable.
+- ❌ **Speculative indexing.** Indexing every column "to be safe" taxes every write and bloats storage; index the queries you have.
+- ❌ **Float money / naked timestamps / stringly-typed enums.** The same three regrets as `data-contract`, baked in at the storage layer where they're hardest to fix.
+- ❌ **Deferring the multitenancy decision.** Shared-table-vs-isolated is near-impossible to change after data lands; an unmade decision is the riskiest one.

package/skills/db-schema-design/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "db-schema-design",
+  "version": "0.1.0",
+  "description": "Design a database schema from access patterns — paradigm chosen deliberately (relational/document/key-value/wide-column/graph), keys and partitioning driven by the actual queries, indexes mapped to predicates, money/time types right, and every read path verified to have a supporting access path. Use when the user is designing a data model, schema, or tables for a feature, choosing a database, or asks how to structure/store data.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["api-contract-draft", "data-contract", "migration-plan", "tech-comparison-matrix"],
+  "tags": ["database", "schema-design", "data-model", "indexing", "sql", "nosql"],
+  "model": { "tier": "standard", "rationale": "Design synthesis from access patterns against a fixed paradigm/indexing/anti-pattern reference. Paradigm and denormalization judgment is bounded; escalate via ambiguous-input on contested scale/consistency tradeoffs." }
+}

package/skills/db-schema-design/reference.md

@@ -0,0 +1,56 @@
+# db-schema-design reference — paradigm matrix, keys, indexing, multitenancy, anti-patterns
+
+## Paradigm-selection matrix (relational is the default; justify moving past it)
+
+| Paradigm | Fits when | Access-pattern signal | Cost of choosing it |
+|---|---|---|---|
+| **Relational** (Postgres, MySQL) | transactional data, ad-hoc queries, joins, strong consistency | "we'll query this many ways, some not yet known"; integrity matters | vertical-scale ceiling (far off for most); needs sharding eventually at very high write volume |
+| **Document** (Mongo, DynamoDB doc, Firestore) | entity read/written whole, varying shape per item, few cross-entity queries | "always fetch the whole order with its lines by order id" | ad-hoc cross-document queries are slow/absent; you design for the queries you know |
+| **Key-value** (Redis, DynamoDB KV) | get/put by a single key, caching, sessions, very high throughput | "look up by exact id, nothing else" | no querying beyond the key; not a system of record alone |
+| **Wide-column** (Cassandra, Bigtable) | massive write volume, time-series-ish, known query keys, linear scale | "billions of rows, query by partition+time, no joins" | one table per query pattern; data duplicated across tables; eventual consistency |
+| **Graph** (Neo4j) | relationship traversal is the query (friends-of-friends, paths, recommendations) | "find all X connected to Y within N hops" | overkill for tabular data; operational maturity cost |
+| **Time-series** (Timescale, Influx) | append-heavy metrics/events keyed by time, downsampling, retention | "ingest events, query ranges, roll up by window" | narrow purpose; pair with a relational store for the rest |
+
+Polyglot is legitimate (Postgres for the system of record + Redis cache + a search index) — but each store needs its own access-pattern justification, and you now own the consistency between them.
+
+## Key design
+
+- **Surrogate vs natural (relational):** surrogate PK (`bigint` identity, or ULID/UUIDv7) by default — stable, opaque, join-friendly. Natural keys (email, SKU) get a `UNIQUE` constraint, not the role of clustered PK (they change, and they leak into URLs/logs).
+- **Avoid random UUIDv4 as a clustered/primary key:** random order scatters inserts across the B-tree, causing page splits and write amplification. Use **UUIDv7/ULID** (time-ordered) when you need a UUID with ordered inserts, or a `bigint` sequence.
+- **NoSQL partition + sort key:** derive from access patterns. Partition key must spread load — a low-cardinality or monotonically-increasing partition key creates a **hot partition**. Sort key co-locates and orders what's read together (e.g. PK=`customer_id`, SK=`order#<ts>` to list a customer's orders by time). One access pattern that doesn't fit the key shape = a new table or a secondary index, decided now.
+- **Composite/natural uniqueness:** enforce real-world uniqueness (one active subscription per customer) with a partial/unique index, not app-code checks that race.
+
+## Normalization / denormalization ladder
+
+1. **Start at 3NF.** Each fact in one place; no update anomalies. This is the correct default for a system of record.
+2. **Denormalize only for a named hot read**, and only after the normalized form is shown to be the bottleneck (or obviously will be). Examples: a counter cache (`order_count`), a duplicated display field to avoid a join on the top query, a materialized view.
+3. **Every denormalization states its sync mechanism** — transaction, trigger, application code, or scheduled rebuild — and accepts the staleness window. A duplicated value with no sync owner *will* drift.
+4. **NoSQL is denormalized by design** — you duplicate across items/tables to serve each access pattern; the "sync obligation" becomes a write-path responsibility (write to all copies, or accept eventual reconciliation).
+
+## Indexing rules
+
+- Index the columns that appear in `WHERE`, `JOIN`, and `ORDER BY` of **actual** queries.
+- **Composite column order: equality predicates first, then the range predicate, then the sort column.** `WHERE tenant_id = ? AND created_at > ? ORDER BY created_at` → index `(tenant_id, created_at)`.
+- A **covering index** (includes the selected columns) turns a hot read into an index-only scan — worth it for a top query, costly to maintain for a rare one.
+- **Don't index low-selectivity columns alone** (a boolean, a 3-value status) — the scan is cheaper than the index hop; combine with a selective column instead, or use a partial index (`WHERE status = 'active'`).
+- Every index taxes **every write** and consumes storage. The right count is "one per real query shape," not zero and not all-columns.
+- Foreign-key columns are usually worth indexing (joins + cascade performance).
+
+## Multitenancy isolation (decide early — expensive to reverse)
+
+| Model | Isolation | Cost / blast radius | Fits |
+|---|---|---|---|
+| Shared table + `tenant_id` (+ row-level security) | logical, enforced by RLS/query | cheapest; a query bug = cross-tenant leak (see `threat-model`) | many small tenants, SaaS default |
+| Schema-per-tenant | stronger; separate tables per tenant | migrations × N schemas; noisy-neighbor still shared | tens–hundreds of mid tenants |
+| Database-per-tenant | strongest; separate DBs | highest ops cost; per-tenant backup/restore is a feature | few large/regulated/enterprise tenants |
+
+State the choice and its trade. If shared-table, the `tenant_id` predicate is non-negotiable on every query and belongs in RLS, not developer discipline.
+
+## Schema anti-pattern catalog
+
+- **EAV (entity-attribute-value)** — rows of `(entity, attribute, value)` to be "flexible." Kills types, constraints, and queryability. Use real columns, or a typed `jsonb` column with documented shape and expression indexes — not a generic triple store.
+- **The god table** — 60+ columns, half null for any given row, modeling several entities at once. Split by entity.
+- **JSON-blob-as-schema-avoidance** — `jsonb` for everything to skip modeling, then unindexed queries digging into it. JSON is for genuinely variable/sparse sub-structure, with expression indexes on what you query.
+- **Premature sharding** — operational complexity for scale you don't have. Vertical + read replicas + partitioning usually buy years first.
+- **Index-everything / index-nothing** — both are failures; index the real query shapes.
+- **Soft-delete everywhere without thought** — `is_deleted` flags leak into every query and every unique constraint; decide per table, and use partial indexes (`WHERE NOT is_deleted`).

package/skills/db-schema-design/templates/schema-design.md

@@ -0,0 +1,75 @@
+# Schema-design template
+
+Access patterns first, schema second, verification last — every query must end the document with a supporting path.
+
+```markdown
+# Schema design: {feature / domain}
+
+**Paradigm:** {relational | document | key-value | wide-column | graph | time-series}
+**Rationale:** {tied to the access patterns below — relational needs none; anything else justifies}
+**Engine (if decided):** {Postgres 16 | DynamoDB | …} `[assumption if not confirmed]`
+
+## Access patterns (the spec the schema is judged against)
+
+| # | Query / write | R/W | Frequency | Selectivity | Latency | Consistency |
+|---|---|---|---|---|---|---|
+| Q1 | get order with lines by order id | R | very high | 1 row + children | <50ms | read-your-writes |
+| Q2 | list a customer's orders, newest first | R | high | range | <200ms | eventual ok |
+| W1 | create order + lines | W | high | — | — | atomic |
+
+## Schema
+
+### {table / collection: orders}
+
+| Column | Type | Null | Key/constraint | Notes |
+|---|---|---|---|---|
+| id | bigint / ULID | no | PK | surrogate; time-ordered |
+| customer_id | bigint | no | FK → customers(id), indexed | |
+| total_minor | bigint | no | CHECK (>= 0) | minor units, currency below — never float |
+| currency | char(3) | no | CHECK (ISO-4217) | |
+| status | text | no | CHECK in (pending,paid,shipped,cancelled) | enum, not free string |
+| created_at | timestamptz | no | default now() | UTC |
+
+{Repeat per table/collection. For NoSQL: state PK (partition) + SK (sort) and the access pattern each serves.}
+
+## Relationships
+
+- customers 1 —< orders 1 —< order_lines  (cascade: delete order → delete its lines)
+- {cardinality + cascade/restrict per relationship}
+
+## Indexes (each maps to a query)
+
+| Index | Columns (order matters) | Serves | Type |
+|---|---|---|---|
+| idx_orders_customer_created | (customer_id, created_at) | Q2 (equality then sort) | btree |
+| pk_orders | (id) | Q1 | primary key (clustered/index-organized only on engines that support it — Postgres heaps don't) |
+
+{Note any covering/partial index and why. No index without a query.}
+
+## Denormalizations (if any)
+
+| Field | On | For query | Kept in sync by |
+|---|---|---|---|
+| order_count | customers | dashboard top read | order-write transaction |
+
+## Scale & multitenancy
+
+- **Unbounded-growth table:** {orders} — plan: {partition by created_at month; archive > 24mo to cold storage}.
+- **Partition/shard:** {none yet — vertical + read replica suffices to ~Nx; revisit at {trigger}} or {strategy + why not premature}.
+- **Multitenancy:** {shared-table + tenant_id + RLS | schema-per-tenant | db-per-tenant} — trade: {…}. `tenant_id` predicate enforced by {RLS policy}.
+
+## Verification — every access pattern has a path
+
+| # | Supported by | Full scan? |
+|---|---|---|
+| Q1 | pk_orders + FK index on lines | no |
+| Q2 | idx_orders_customer_created | no |
+| W1 | insert; FK indexes present | no |
+
+⚠ {Any pattern with no supporting index/key — flag it and resolve before build.}
+
+## Evolution
+
+- Migrations / rollout of changes → `migration-plan`.
+- If this data is published to other teams → wrap it in a `data-contract`.
+```

package/skills/decision-log/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: decision-log
+description: Extract decisions, action items, owners, and due dates from meeting notes, Slack threads, design-review transcripts, or any unstructured discussion. Produces a clean structured log the user can paste into a doc, tracker, or ADR queue. Use when the user has notes/threads/transcripts and asks for a "decision log", "action items", "what did we agree", or "follow-ups".
+---
+
+# decision-log
+
+You help the user turn messy meeting notes or threads into a structured log of what was decided, who owns the follow-up, and what's still open.
+
+## How to respond
+
+1. **Ingest the source.** The user will paste notes, give a file path, or share a transcript. If the source is huge (e.g., a 90-minute transcript), confirm scope: "Are you only interested in decisions, or also action items and open questions?"
+
+2. **Extract four categories:**
+
+   - **Decisions made.** Things the group agreed on — even if informal. Look for phrases like "we'll go with…", "let's do…", "agreed", "fine by me", "ship it". Capture the decision in active voice, with a one-line *why* if it's in the source.
+   - **Action items.** Things someone agreed to *do*. Need an owner (a name), an action (a verb phrase), and ideally a due date. If the date is fuzzy ("by next week"), convert to an absolute date and flag it.
+   - **Open questions.** Things explicitly *not* resolved. Include who needs to answer if it's stated.
+   - **Risks raised.** Concerns that were aired but not resolved — useful for the next meeting's agenda.
+
+3. **Convert fuzzy dates to absolute dates.** "Friday" → `YYYY-MM-DD`. "End of week" → `YYYY-MM-DD (EOW)`. "Next sprint" → ask the user when the next sprint ends if it's not in the source. Mark dates as `(implied)` when you've inferred them so the user can verify.
+
+4. **Attribute every action item to a named person.** "Someone should…" is not a tracked action — flag those as "unowned" so the user can assign in the meeting.
+
+5. **Output as four tables**, in this order:
+
+   ```markdown
+   ## Decisions
+   | # | Decision | Why | Source |
+   |---|---|---|---|
+
+   ## Action items
+   | # | Owner | Action | Due | Source |
+   |---|---|---|---|---|
+
+   ## Open questions
+   | # | Question | Owner (to answer) | Source |
+   |---|---|---|---|
+
+   ## Risks raised (not yet acted on)
+   | # | Risk | Raised by | Source |
+   |---|---|---|---|
+   ```
+
+   The `Source` column quotes ~5–10 words from the original notes so the user can verify nothing was hallucinated.
+
+6. **Surface gaps.** End with a "🚩 Gaps" callout listing:
+   - Action items without an owner
+   - Action items without a date
+   - Decisions whose rationale isn't captured in the source
+   - Anything where you weren't sure whether it was a decision or a discussion
+
+## Quality bar
+
+- **Don't invent ownership.** If the source says "we should email the legal team", don't pick a name. Flag as unowned.
+- **Don't promote opinions to decisions.** "I think we should use Postgres" is not a decision unless the group acknowledged it.
+- **Quote, don't paraphrase, the source column.** A 5–10 word verbatim snippet is the audit trail.
+- **Active voice in the action column.** ✅ "Send PR for ADR-0007 to legal" — ❌ "ADR-0007 to be sent to legal".
+- **Convert relative dates.** Today's date is needed — ask if unclear.
+
+## Anti-patterns to avoid
+
+- ❌ Mixing decisions and action items in one table. They're different.
+- ❌ Capturing every utterance — pick the load-bearing ones.
+- ❌ "AOB" or generic catch-all entries — be specific or drop.
+- ❌ Hallucinating attendees, dates, or rationale that isn't in the source.
+- ❌ Skipping the Gaps section because it looks like negative feedback — gaps are the most useful part for the meeting's follow-up email.

package/skills/decision-log/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "decision-log",
+  "version": "0.1.0",
+  "description": "Extract decisions, action items, owners, and due dates from meeting notes, Slack threads, design-review transcripts, or any unstructured discussion. Produces a clean structured log the user can paste into a doc, tracker, or ADR queue. Use when the user has notes/threads/transcripts and asks for a \"decision log\", \"action items\", \"what did we agree\", or \"follow-ups\".",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["meetings", "decisions", "action-items", "stakeholder-communication"],
+  "model": { "tier": "light", "rationale": "Extracts decisions/owners/dates from notes. Pattern extraction; escalates on long transcripts." }
+}

package/skills/deck-builder/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: deck-builder
+description: Generate a real PowerPoint (.pptx) file from content, target audience, and a color palette. Produces structurally-appropriate decks (slide count, density, layout choice) tuned for the audience — execs, technical reviewers, sales prospects, investors, internal teams. Use when the user wants an actual editable .pptx, not just an outline.
+---
+
+# deck-builder
+
+You help the user produce an **actual editable `.pptx` file**, not just an outline. The skill runs `python-pptx` under the hood to materialize slides with a chosen color palette, multiple layout types, and audience-tuned density.
+
+This skill pairs with two others:
+- **[`audience-profile`](../audience-profile/SKILL.md)** — decides how dense / how many / which sections the deck should have
+- **[`slide-outliner`](../slide-outliner/SKILL.md)** — drafts the per-slide content before this skill turns it into a `.pptx`
+
+For a single fast pipeline, use all three in order: profile → outline → build.
+
+## How to respond
+
+1. **Gather three inputs** before generating anything:
+
+   - **Content.** Either a finished outline (from `slide-outliner`), a long doc the user wants compressed into slides, or a list of points. If the content is thin ("here's the topic, you fill in"), pause and ask — *making slides up is the easiest way to make a bad deck*.
+   - **Audience.** One of: `exec`, `board`, `technical`, `sales`, `internal`, `investor`, `partner`, `customer`. If the user gives a free-form description ("VP of Eng + their staff at a partner"), map to the closest archetype and call out your choice. Use [`audience-profile`](../audience-profile/SKILL.md) for the structural rules.
+   - **Palette.** Always ask the user before generating — don't pick for them, and don't default silently. Present the choice like this:
+
+     > Pick a palette before I generate the deck:
+     > - `corporate-blue` — default for B2B / enterprise audiences
+     > - `monochrome` — restrained / when content is sensitive
+     > - `vibrant` — internal / sales / pitch decks
+     > - `dark-mode` — engineering audiences, live demos
+     > - `editorial` — long-form / read-ahead decks
+     > - `forest` — calm, nature-leaning
+     > - `sunset` — warm, narrative-leaning
+     > - Or give me hex values for `primary` / `secondary` / `accent` / `background` / `text`
+     > - Or paste your brand colors and I'll map them into the five roles
+
+     If the user gives brand colors as a partial set (e.g. just a primary), derive the missing roles using the rules in [`reference.md`](reference.md#color-palette-principles) and call out what you filled in.
+
+2. **Plan the slide list against the audience archetype.** For example:
+
+   | Audience | Slide count | Density | Required sections |
+   |---|---|---|---|
+   | `exec` | 6–10 | Low — 3 bullets max | Ask • TL;DR • Business impact • Risks • Ask (closing) |
+   | `board` | 8–12 | Low — big numbers | Cover • TL;DR • Strategic context • Financials • Risks • Ask |
+   | `technical` | 12–20 | High — detail welcome | Context • Goals • Proposal (3–5) • Alternatives • Risks • Rollout |
+   | `sales` | 8–12 | Story arc, visual | Hook • Pain • Solution • Proof • Pricing • Close |
+   | `internal` | 5–10 | Mixed | Context • Proposal • Discussion topics • Action items |
+   | `investor` | 10–15 | Polished, narrative | Problem • Market • Product • Traction • Team • Ask |
+
+   The full archetype spec is in [`audience-profile`](../audience-profile/SKILL.md).
+
+3. **Build a deck spec.** The spec is a JSON document with this shape — full schema in [`templates/deck-spec.json`](templates/deck-spec.json):
+
+   ```json
+   {
+     "title": "ProjectX Migration — Board Update",
+     "audience": "board",
+     "palette": { "primary": "#1A2A6C", "accent": "#FDBB2D", ... },
+     "slides": [
+       { "layout": "title", "title": "...", "subtitle": "..." },
+       { "layout": "section", "title": "..." },
+       { "layout": "content", "title": "...", "bullets": ["..."] },
+       { "layout": "big_number", "title": "...", "number": "$24M", "caption": "ARR at risk" },
+       { "layout": "two_column", "title": "...", "left": {...}, "right": {...} },
+       { "layout": "quote", "quote": "...", "attribution": "..." },
+       { "layout": "closing", "title": "Approval requested", "subtitle": "..." }
+     ]
+   }
+   ```
+
+   Available layouts: `title`, `section`, `content`, `two_column`, `big_number`, `quote`, `closing`. Most slides should be `content`; sprinkle in `big_number` and `quote` for emphasis.
+
+4. **Run the build script** to produce the actual `.pptx`:
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" /tmp/deck-spec.json -o ./out/deck.pptx
+
+   # Other IDEs (from the skill folder)
+   cd path/to/deck-builder && python3 scripts/build_deck.py /tmp/deck-spec.json -o ./out/deck.pptx
+   ```
+
+   The script writes a real `.pptx` the user can open in PowerPoint, Keynote, or Google Slides and edit further. Tell the user where the file landed and what to do next.
+
+5. **Recommend post-generation refinement.** A generated deck is a strong first draft, not a finished artifact. Always suggest:
+
+   - Reviewing speaker notes (they were written by the agent — verify before presenting)
+   - Replacing any placeholder images with real visuals
+   - Doing one "audience pass" — read every slide title in order, does the *narrative* make sense to that specific audience?
+
+## Useful references
+
+- [`reference.md`](reference.md) — Color palette principles + layout-vs-content matching guide
+- [`templates/deck-spec.json`](templates/deck-spec.json) — Full JSON schema with every layout demonstrated
+- [`templates/palettes.json`](templates/palettes.json) — Pre-built color palettes (corporate-blue, monochrome, vibrant, dark-mode, editorial, forest, sunset)
+- [`examples/exec-board-update.md`](examples/exec-board-update.md) — Worked example: brief → spec → resulting deck
+- [`scripts/build_deck.py`](scripts/build_deck.py) — The generator (don't edit unless extending layouts)
+
+## Quality bar
+
+- **Title slide isn't blank** — it has a real title, subtitle, presenter, date.
+- **Section dividers used sparingly** — at most one every 4–5 content slides.
+- **Big numbers are real** — never invent statistics for emphasis. If the user gave you a number, use it; otherwise pick a different layout.
+- **Bullet density matches audience** — for `exec`, *max 3 bullets per slide*, period. For `technical`, up to 6 if the content really needs it.
+- **Speaker notes for every slide** — even one sentence. They're how the presenter remembers what's *between* the bullets.
+- **Color palette is consistent** — don't mix in random colors that aren't in the palette.
+- **No surprise pages** — first and last slides match in style; the deck reads as one document.
+
+## Anti-patterns to avoid
+
+- ❌ Generating a deck without confirming the audience. The same content for execs vs engineers is a different deck.
+- ❌ Writing fake numbers to fill a `big_number` slide.
+- ❌ Defaulting to bullets when a `big_number`, `quote`, or `two_column` would land harder.
+- ❌ Skipping speaker notes because the user "knows the topic" — they're for the reviewer/co-presenter too.
+- ❌ Choosing low-contrast palettes (light grey text on white). If the palette has poor contrast, swap to a sensible default and explain.
+- ❌ More than ~20 slides for any audience. If you can't make the point in 20, the deck isn't the right format.