@monoes/monomindcli 2.15.2 → 2.15.4

package/org-skills/postgres-patterns/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/org-skills/postgres-patterns/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: postgres-patterns
+description: "PostgreSQL database patterns for query optimization, schema design, indexing, and security. Based on Supabase best practices. Use when designing PostgreSQL schemas, indexes, or RLS policies, or when a query is too slow."
+tags: ["data","backend"]
+tools: []
+license: MIT
+source: https://github.com/affaan-m/ECC
+source_path: "skills/postgres-patterns"
+source_commit: bf70150eb2df8070024e5bdf08e4aa08959e2735
+---
+# PostgreSQL Patterns
+
+Quick reference for PostgreSQL best practices. For detailed guidance, use the `database-reviewer` agent.
+
+## When to Activate
+
+- Writing SQL queries or migrations
+- Designing database schemas
+- Troubleshooting slow queries
+- Implementing Row Level Security
+- Setting up connection pooling
+
+## Quick Reference
+
+### Index Cheat Sheet
+
+| Query Pattern | Index Type | Example |
+|--------------|------------|---------|
+| `WHERE col = value` | B-tree (default) | `CREATE INDEX idx ON t (col)` |
+| `WHERE col > value` | B-tree | `CREATE INDEX idx ON t (col)` |
+| `WHERE a = x AND b > y` | Composite | `CREATE INDEX idx ON t (a, b)` |
+| `WHERE jsonb @> '{}'` | GIN | `CREATE INDEX idx ON t USING gin (col)` |
+| `WHERE tsv @@ query` | GIN | `CREATE INDEX idx ON t USING gin (col)` |
+| Time-series ranges | BRIN | `CREATE INDEX idx ON t USING brin (col)` |
+
+### Data Type Quick Reference
+
+| Use Case | Correct Type | Avoid |
+|----------|-------------|-------|
+| IDs | `bigint` | `int`, random UUID |
+| Strings | `text` | `varchar(255)` |
+| Timestamps | `timestamptz` | `timestamp` |
+| Money | `numeric(10,2)` | `float` |
+| Flags | `boolean` | `varchar`, `int` |
+
+### Common Patterns
+
+**Composite Index Order:**
+```sql
+-- Equality columns first, then range columns
+CREATE INDEX idx ON orders (status, created_at);
+-- Works for: WHERE status = 'pending' AND created_at > '2024-01-01'
+```
+
+**Covering Index:**
+```sql
+CREATE INDEX idx ON users (email) INCLUDE (name, created_at);
+-- Avoids table lookup for SELECT email, name, created_at
+```
+
+**Partial Index:**
+```sql
+CREATE INDEX idx ON users (email) WHERE deleted_at IS NULL;
+-- Smaller index, only includes active users
+```
+
+**RLS Policy (Optimized):**
+```sql
+CREATE POLICY policy ON orders
+  USING ((SELECT auth.uid()) = user_id);  -- Wrap in SELECT!
+```
+
+**UPSERT:**
+```sql
+INSERT INTO settings (user_id, key, value)
+VALUES (123, 'theme', 'dark')
+ON CONFLICT (user_id, key)
+DO UPDATE SET value = EXCLUDED.value;
+```
+
+**Cursor Pagination:**
+```sql
+SELECT * FROM products WHERE id > $last_id ORDER BY id LIMIT 20;
+-- O(1) vs OFFSET which is O(n)
+```
+
+**Queue Processing:**
+```sql
+UPDATE jobs SET status = 'processing'
+WHERE id = (
+  SELECT id FROM jobs WHERE status = 'pending'
+  ORDER BY created_at LIMIT 1
+  FOR UPDATE SKIP LOCKED
+) RETURNING *;
+```
+
+### Anti-Pattern Detection
+
+```sql
+-- Find unindexed foreign keys
+SELECT conrelid::regclass, a.attname
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+WHERE c.contype = 'f'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_index i
+    WHERE i.indrelid = c.conrelid AND a.attnum = ANY(i.indkey)
+  );
+
+-- Find slow queries
+SELECT query, mean_exec_time, calls
+FROM pg_stat_statements
+WHERE mean_exec_time > 100
+ORDER BY mean_exec_time DESC;
+
+-- Check table bloat
+SELECT relname, n_dead_tup, last_vacuum
+FROM pg_stat_user_tables
+WHERE n_dead_tup > 1000
+ORDER BY n_dead_tup DESC;
+```
+
+### Configuration Template
+
+```sql
+-- Connection limits (adjust for RAM)
+ALTER SYSTEM SET max_connections = 100;
+ALTER SYSTEM SET work_mem = '8MB';
+
+-- Timeouts
+ALTER SYSTEM SET idle_in_transaction_session_timeout = '30s';
+ALTER SYSTEM SET statement_timeout = '30s';
+
+-- Monitoring
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+-- Security defaults
+REVOKE ALL ON SCHEMA public FROM public;
+
+SELECT pg_reload_conf();
+```
+
+## Related
+
+- Agent: `database-reviewer` - Full database review workflow
+- Skill: `clickhouse-io` - ClickHouse analytics patterns
+- Skill: `backend-patterns` - API and backend patterns
+
+---
+
+*Based on Supabase Agent Skills (credit: Supabase team) (MIT License)*

package/org-skills/postgresql-table-design/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Seth Hobson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/org-skills/postgresql-table-design/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: postgresql-table-design
+description: "Use this skill when designing or reviewing a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features"
+tags: ["data","backend"]
+tools: []
+license: MIT
+source: https://github.com/wshobson/agents
+source_path: "plugins/database-design/skills/postgresql-table-design"
+source_commit: 4236bb91f8395b0435f1d8b8baf9e8e4c69a8620
+---
+# PostgreSQL Table Design
+
+## When to Use
+
+- Designing a new PostgreSQL schema, or reviewing one before it ships.
+- Choosing column types, keys, constraints, or indexes for PostgreSQL specifically.
+- Deciding whether and how to partition a large table, or how to store semi-structured data.
+- Planning a schema change on a live database without downtime.
+
+The rules and decision points for a PostgreSQL schema. The full data-type catalog, workload
+patterns (update-heavy, insert-heavy, upsert, schema evolution), extensions, JSONB indexing,
+and worked DDL examples are in `references/details.md`; open it when a section below points there.
+
+## Core Rules
+
+- Define a **PRIMARY KEY** for reference tables (users, orders, etc.). Not always needed for time-series/event/log data. When used, prefer `BIGINT GENERATED ALWAYS AS IDENTITY`; use `UUID` only when global uniqueness/opacity is needed.
+- **Normalize first (to 3NF)** to eliminate data redundancy and update anomalies; denormalize **only** for measured, high-ROI reads where join performance is proven problematic.
+- Add **NOT NULL** everywhere it is semantically required; use **DEFAULT**s for common values.
+- Create **indexes for access paths you actually query**: PK/unique (auto), **FK columns (manual!)**, frequent filters/sorts, and join keys.
+- Prefer **TIMESTAMPTZ** for event time; **NUMERIC** for money; **TEXT** for strings; **BIGINT** for integers; **DOUBLE PRECISION** for floats (or `NUMERIC` for exact decimal arithmetic).
+
+## PostgreSQL Gotchas
+
+- **Identifiers**: unquoted → lowercased. Avoid quoted/mixed-case names; use `snake_case`.
+- **Unique + NULLs**: UNIQUE allows multiple NULLs. Use `UNIQUE NULLS NOT DISTINCT (...)` (PG15+) to restrict to one NULL.
+- **FK indexes**: PostgreSQL **does not** auto-index FK columns. Add them.
+- **No silent coercions**: length/precision overflows error out (no truncation). Inserting 999 into `NUMERIC(2,0)` fails, unlike databases that silently truncate or round.
+- **Sequences/identity have gaps** (normal; don't "fix"). Rollbacks, crashes, and concurrent transactions leave gaps (1, 2, 5, 6...).
+- **Heap storage**: no clustered PK by default; `CLUSTER` is a one-off reorganization, not maintained on later inserts.
+- **MVCC**: updates/deletes leave dead tuples; vacuum handles them—design to avoid hot wide-row churn.
+
+## Data Types
+
+- **IDs**: `BIGINT GENERATED ALWAYS AS IDENTITY`; `UUID` for distributed or opaque IDs, generated with `uuidv7()` (PG18+) or `gen_random_uuid()`.
+- **Numbers**: `BIGINT` unless storage is critical; `DOUBLE PRECISION` over `REAL`; `NUMERIC(p,s)` for money and exact decimals.
+- **Strings**: `TEXT`, with `CHECK (LENGTH(col) <= n)` when a limit is needed; `BYTEA` for binary. Case-insensitive lookups: expression index on `LOWER(col)`, or `CITEXT` when a constraint must be case-insensitive.
+- **Time**: `TIMESTAMPTZ`, `DATE`, `INTERVAL`. `now()` is transaction start; `clock_timestamp()` is wall clock.
+- **Booleans**: `BOOLEAN NOT NULL` unless tri-state is required.
+- **Enums**: `CREATE TYPE ... AS ENUM` only for small, stable sets; evolving business values get `TEXT` + `CHECK` or a lookup table.
+- **JSONB** over JSON, indexed with GIN, for optional/semi-structured attributes only.
+- Arrays, ranges, network, geometric, full-text, domain, composite, and vector types, plus TOAST storage and collation control: see `references/details.md`.
+
+### Types to avoid
+
+| Avoid | Use instead |
+|---|---|
+| `timestamp` (without time zone) | `timestamptz` |
+| `char(n)`, `varchar(n)` | `text` (+ `CHECK` on length if needed) |
+| `money` | `numeric` |
+| `timetz` | `timestamptz` |
+| `timestamptz(0)` or any precision | `timestamptz` |
+| `serial` | `generated always as identity` |
+
+## Constraints
+
+- **PK**: implicit UNIQUE + NOT NULL; creates a B-tree index.
+- **FK**: specify `ON DELETE/UPDATE` (`CASCADE`, `RESTRICT`, `SET NULL`, `SET DEFAULT`). Index the referencing column. Use `DEFERRABLE INITIALLY DEFERRED` for circular dependencies checked at commit.
+- **UNIQUE**: creates a B-tree index; allows multiple NULLs unless `NULLS NOT DISTINCT` (PG15+). Prefer `NULLS NOT DISTINCT` unless duplicate NULLs are wanted.
+- **CHECK**: row-local; NULL passes (three-valued logic). Combine with `NOT NULL`: `price NUMERIC NOT NULL CHECK (price > 0)`.
+- **EXCLUDE**: prevents overlaps with operators, e.g. `EXCLUDE USING gist (room_id WITH =, booking_period WITH &&)` stops double-booking. Needs a GiST-capable type.
+
+## Indexing
+
+- **B-tree**: default for equality/range (`=`, `<`, `>`, `BETWEEN`, `ORDER BY`).
+- **Composite**: leftmost-prefix rule (`WHERE a = ? AND b > ?` uses `(a,b)`; `WHERE b = ?` does not). Most selective columns first.
+- **Covering**: `CREATE INDEX ON tbl (id) INCLUDE (name, email)` for index-only scans.
+- **Partial**: hot subsets, `CREATE INDEX ON tbl (user_id) WHERE status = 'active'`.
+- **Expression**: `CREATE INDEX ON tbl (LOWER(email))`; the query must use the same expression.
+- **GIN**: JSONB containment/existence, arrays, full-text search. **GiST**: ranges, geometry, exclusion constraints.
+- **BRIN**: large, naturally ordered data (time-series) at minimal storage cost; effective when disk order correlates with the indexed column.
+
+## Partitioning
+
+- Use for large tables (>100M rows) whose queries consistently filter on the partition key, or where maintenance (pruning, bulk replacement) follows a key.
+- **RANGE** for time-series (`PARTITION BY RANGE (created_at)`; **TimescaleDB** automates it with retention and compression), **LIST** for discrete values, **HASH** for even distribution without a natural key.
+- **Constraint exclusion**: the planner prunes partitions through their `CHECK` constraints; declarative partitioning (PG10+) creates them for you.
+- Prefer declarative partitioning or hypertables. Do NOT use table inheritance.
+- **Limitations**: no global UNIQUE constraints—include the partition key in PK/UNIQUE. FKs from partitioned tables need PG11+, FKs referencing a partitioned table need PG12+; on older versions, use triggers.
+
+## Examples
+
+```sql
+CREATE TABLE users (
+  user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX ON users (LOWER(email));
+CREATE INDEX ON users (created_at);
+```
+
+```sql
+CREATE TABLE orders (
+  order_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  user_id BIGINT NOT NULL REFERENCES users(user_id),
+  status TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','PAID','CANCELED')),
+  total NUMERIC(10,2) NOT NULL CHECK (total > 0),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX ON orders (user_id);
+CREATE INDEX ON orders (created_at);
+```
+
+```sql
+-- JSONB attributes with a generated, indexable scalar
+CREATE TABLE profiles (
+  user_id BIGINT PRIMARY KEY REFERENCES users(user_id),
+  attrs JSONB NOT NULL DEFAULT '{}',
+  theme TEXT GENERATED ALWAYS AS (attrs->>'theme') STORED
+);
+CREATE INDEX profiles_attrs_gin ON profiles USING GIN (attrs);
+```
+
+## Going deeper
+
+`references/details.md` holds the material this file only names:
+
+- The full data-type catalog: TOAST storage, collations, arrays, ranges, network, geometric, text search, domains, composites, vectors.
+- Table types (`TEMPORARY`, `UNLOGGED`) and row-level security.
+- Constraint and index notes, and partitioning DDL for RANGE, LIST, and HASH.
+- Workload patterns: update-heavy, insert-heavy, upsert design, safe schema evolution.
+- Generated columns and extensions (`pg_trgm`, `citext`, `timescaledb`, `postgis`, `pgvector`, and more).
+- JSONB indexing strategies, including `jsonb_path_ops` and extracted B-tree columns.

package/org-skills/postgresql-table-design/references/details.md

@@ -0,0 +1,161 @@
+# PostgreSQL table design: details
+
+Deep material for the `postgresql-table-design` skill. `SKILL.md` carries the rules and
+the decision points; this file carries the full data-type catalog, workload patterns,
+extensions, JSONB indexing, and worked DDL.
+
+## Data type catalog
+
+- **IDs**: `BIGINT GENERATED ALWAYS AS IDENTITY` preferred (`GENERATED BY DEFAULT` also fine); `UUID` when merging/federating/used in a distributed system or for opaque IDs. Generate with `uuidv7()` (preferred if using PG18+) or `gen_random_uuid()` (if using an older PG version).
+- **Integers**: prefer `BIGINT` unless storage space is critical; `INTEGER` for smaller ranges; avoid `SMALLINT` unless constrained.
+- **Floats**: prefer `DOUBLE PRECISION` over `REAL` unless storage space is critical. Use `NUMERIC` for exact decimal arithmetic.
+- **Strings**: prefer `TEXT`; if length limits needed, use `CHECK (LENGTH(col) <= n)` instead of `VARCHAR(n)`; avoid `CHAR(n)`. Use `BYTEA` for binary data. Large strings/binary (>2KB default threshold) automatically stored in TOAST with compression. TOAST storage: `PLAIN` (no TOAST), `EXTENDED` (compress + out-of-line), `EXTERNAL` (out-of-line, no compress), `MAIN` (compress, keep in-line if possible). Default `EXTENDED` usually optimal. Control with `ALTER TABLE tbl ALTER COLUMN col SET STORAGE strategy` and `ALTER TABLE tbl SET (toast_tuple_target = 4096)` for threshold. Case-insensitive: for locale/accent handling use non-deterministic collations; for plain ASCII use expression indexes on `LOWER(col)` (preferred unless column needs case-insensitive PK/FK/UNIQUE) or `CITEXT`.
+- **Money**: `NUMERIC(p,s)` (never float).
+- **Time**: `TIMESTAMPTZ` for timestamps; `DATE` for date-only; `INTERVAL` for durations. Avoid `TIMESTAMP` (without timezone). Use `now()` for transaction start time, `clock_timestamp()` for current wall-clock time.
+- **Booleans**: `BOOLEAN` with `NOT NULL` constraint unless tri-state values are required.
+- **Enums**: `CREATE TYPE ... AS ENUM` for small, stable sets (e.g. US states, days of week). For business-logic-driven and evolving values (e.g. order statuses) → use TEXT (or INT) + CHECK or lookup table.
+- **Arrays**: `TEXT[]`, `INTEGER[]`, etc. Use for ordered lists where you query elements. Index with **GIN** for containment (`@>`, `<@`) and overlap (`&&`) queries. Access: `arr[1]` (1-indexed), `arr[1:3]` (slicing). Good for tags, categories; avoid for relations—use junction tables instead. Literal syntax: `'{val1,val2}'` or `ARRAY[val1,val2]`.
+- **Range types**: `daterange`, `numrange`, `tstzrange` for intervals. Support overlap (`&&`), containment (`@>`), operators. Index with **GiST**. Good for scheduling, versioning, numeric ranges. Pick a bounds scheme and use it consistently; prefer `[)` (inclusive/exclusive) by default.
+- **Network types**: `INET` for IP addresses, `CIDR` for network ranges, `MACADDR` for MAC addresses. Support network operators (`<<`, `>>`, `&&`).
+- **Geometric types**: `POINT`, `LINE`, `POLYGON`, `CIRCLE` for 2D spatial data. Index with **GiST**. Consider **PostGIS** for advanced spatial features.
+- **Text search**: `TSVECTOR` for full-text search documents, `TSQUERY` for search queries. Index `tsvector` with **GIN**. Always specify language: `to_tsvector('english', col)` and `to_tsquery('english', 'query')`. Never use single-argument versions. This applies to both index expressions and queries.
+- **Domain types**: `CREATE DOMAIN email AS TEXT CHECK (VALUE ~ '^[^@]+@[^@]+$')` for reusable custom types with validation. Enforces constraints across tables.
+- **Composite types**: `CREATE TYPE address AS (street TEXT, city TEXT, zip TEXT)` for structured data within columns. Access with `(col).field` syntax.
+- **JSONB**: preferred over JSON; index with **GIN**. Use only for optional/semi-structured attrs. ONLY use JSON if the original ordering of the contents MUST be preserved.
+- **Vector types**: `vector` type by `pgvector` for vector similarity search for embeddings.
+
+## Table types
+
+- **Regular**: default; fully durable, logged.
+- **TEMPORARY**: session-scoped, auto-dropped, not logged. Faster for scratch work.
+- **UNLOGGED**: persistent but not crash-safe. Faster writes; good for caches/staging.
+
+## Row-level security
+
+Enable with `ALTER TABLE tbl ENABLE ROW LEVEL SECURITY`. Create policies: `CREATE POLICY user_access ON orders FOR SELECT TO app_users USING (owner = current_user)` when database roles map to users, or compare against an app-set setting such as `current_setting('app.user_id')::bigint`. Built-in user-based access control at the row level.
+
+## Workload patterns
+
+### Update-heavy tables
+
+- **Separate hot/cold columns**—put frequently updated columns in separate table to minimize bloat.
+- **Use `fillfactor=90`** to leave space for HOT updates that avoid index maintenance.
+- **Avoid updating indexed columns**—prevents beneficial HOT updates.
+- **Partition by update patterns**—separate frequently updated rows in a different partition from stable data.
+
+### Insert-heavy workloads
+
+- **Minimize indexes**—only create what you query; every index slows inserts.
+- **Use `COPY` or multi-row `INSERT`** instead of single-row inserts.
+- **UNLOGGED tables** for rebuildable staging data—much faster writes.
+- **Defer index creation** for bulk loads—>drop index, load data, recreate indexes.
+- **Partition by time/hash** to distribute load. **TimescaleDB** automates partitioning and compression of insert-heavy data.
+- **Use a natural key for primary key** such as a (timestamp, device_id) if enforcing global uniqueness is important many insert-heavy tables don't need a primary key at all.
+- If you do need a surrogate key, **Prefer `BIGINT GENERATED ALWAYS AS IDENTITY` over `UUID`**.
+
+### Upsert-friendly design
+
+- **Requires UNIQUE index** on conflict target columns—`ON CONFLICT (col1, col2)` needs exact matching unique index (partial indexes don't work).
+- **Use `EXCLUDED.column`** to reference would-be-inserted values; only update columns that actually changed to reduce write overhead.
+- **`DO NOTHING` faster** than `DO UPDATE` when no actual update needed.
+
+### Safe schema evolution
+
+- **Transactional DDL**: most DDL operations can run in transactions and be rolled back—`BEGIN; ALTER TABLE...; ROLLBACK;` for safe testing.
+- **Concurrent index creation**: `CREATE INDEX CONCURRENTLY` avoids blocking writes but can't run in transactions.
+- **Volatile defaults cause rewrites**: adding `NOT NULL` columns with volatile defaults (e.g., `now()`, `gen_random_uuid()`) rewrites entire table. Non-volatile defaults are fast.
+- **Drop constraints before columns**: `ALTER TABLE DROP CONSTRAINT` then `DROP COLUMN` to avoid dependency issues.
+- **Function signature changes**: `CREATE OR REPLACE` with different arguments creates overloads, not replacements. DROP old version if no overload desired.
+
+## Constraint and index notes
+
+- **FK**: an explicit index on the referencing column speeds up joins and prevents locking issues on parent deletes/updates.
+- **UNIQUE**: standard behavior allows both `(1, NULL)` and `(1, NULL)`; with `NULLS NOT DISTINCT` (PG15+) only one `(1, NULL)` is allowed.
+- **Partial index**: `CREATE INDEX ON tbl (user_id) WHERE status = 'active'` serves any query that includes `status = 'active'`.
+- **Expression index**: the expression must match the WHERE clause exactly: `WHERE LOWER(email) = 'user@example.com'`.
+- **BRIN**: effective when row order on disk correlates with the indexed column (insertion order or after `CLUSTER`).
+- **Heap storage**: no clustered PK by default (unlike SQL Server/MySQL InnoDB); row order on disk is insertion order unless explicitly clustered, and `CLUSTER` is not maintained on later inserts.
+
+## Partitioning details
+
+- Use for very large tables (>100M rows) where queries consistently filter on the partition key (often time/date), or for tables whose maintenance (pruning, periodic bulk replacement) follows a key.
+- **RANGE**: `PARTITION BY RANGE (created_at)`; create partitions with `CREATE TABLE logs_2024_01 PARTITION OF logs FOR VALUES FROM ('2024-01-01') TO ('2024-02-01')`. **TimescaleDB** automates time-based or ID-based partitioning with retention policies and compression.
+- **LIST**: `PARTITION BY LIST (region)` with `FOR VALUES IN ('us-east', 'us-west')`.
+- **HASH**: `PARTITION BY HASH (user_id)` creates N partitions by modulus, for even distribution when there is no natural key.
+- **Constraint exclusion**: requires `CHECK` constraints on partitions for the planner to prune; auto-created for declarative partitioning (PG10+).
+
+## Generated columns
+
+- `... GENERATED ALWAYS AS (<expr>) STORED` for computed, indexable fields. PG18+ adds `VIRTUAL` columns (computed on read, not stored).
+
+## Extensions
+
+- **`pgcrypto`**: `crypt()` for password hashing.
+- **`uuid-ossp`**: alternative UUID functions; prefer `pgcrypto` for new projects.
+- **`pg_trgm`**: fuzzy text search with `%` operator, `similarity()` function. Index with GIN for `LIKE '%pattern%'` acceleration.
+- **`citext`**: case-insensitive text type. Prefer expression indexes on `LOWER(col)` unless you need case-insensitive constraints.
+- **`btree_gin`/`btree_gist`**: enable mixed-type indexes (e.g., GIN index on both JSONB and text columns).
+- **`hstore`**: key-value pairs; mostly superseded by JSONB but useful for simple string mappings.
+- **`timescaledb`**: essential for time-series—automated partitioning, retention, compression, continuous aggregates.
+- **`postgis`**: comprehensive geospatial support beyond basic geometric types—essential for location-based applications.
+- **`pgvector`**: vector similarity search for embeddings.
+- **`pgaudit`**: audit logging for all database activity.
+
+## JSONB guidance
+
+- Prefer `JSONB` with **GIN** index.
+- Default: `CREATE INDEX ON tbl USING GIN (jsonb_col);` → accelerates:
+  - **Containment** `jsonb_col @> '{"k":"v"}'`
+  - **Key existence** `jsonb_col ? 'k'`, **any/all keys** `?\|`, `?&`
+  - **Path containment** on nested docs
+  - **Disjunction** `jsonb_col @> ANY(ARRAY['{"status":"active"}', '{"status":"pending"}'])`
+- Heavy `@>` workloads: consider opclass `jsonb_path_ops` for smaller/faster containment-only indexes:
+  - `CREATE INDEX ON tbl USING GIN (jsonb_col jsonb_path_ops);`
+  - **Trade-off**: loses support for key existence (`?`, `?|`, `?&`) queries—only supports containment (`@>`)
+- Equality/range on a specific scalar field: extract and index with B-tree (generated column or expression):
+  - `ALTER TABLE tbl ADD COLUMN price INT GENERATED ALWAYS AS ((jsonb_col->>'price')::INT) STORED;`
+  - `CREATE INDEX ON tbl (price);`
+  - Prefer queries like `WHERE price BETWEEN 100 AND 500` (uses B-tree) over `WHERE (jsonb_col->>'price')::INT BETWEEN 100 AND 500` without index.
+- Arrays inside JSONB: use GIN + `@>` for containment (e.g., tags). Consider `jsonb_path_ops` if only doing containment.
+- Keep core relations in tables; use JSONB for optional/variable attributes.
+- Use constraints to limit allowed JSONB values in a column e.g. `config JSONB NOT NULL CHECK(jsonb_typeof(config) = 'object')`
+
+## Examples
+
+### Users
+
+```sql
+CREATE TABLE users (
+  user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX ON users (LOWER(email));
+CREATE INDEX ON users (created_at);
+```
+
+### Orders
+
+```sql
+CREATE TABLE orders (
+  order_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  user_id BIGINT NOT NULL REFERENCES users(user_id),
+  status TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','PAID','CANCELED')),
+  total NUMERIC(10,2) NOT NULL CHECK (total > 0),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX ON orders (user_id);
+CREATE INDEX ON orders (created_at);
+```
+
+### JSONB
+
+```sql
+CREATE TABLE profiles (
+  user_id BIGINT PRIMARY KEY REFERENCES users(user_id),
+  attrs JSONB NOT NULL DEFAULT '{}',
+  theme TEXT GENERATED ALWAYS AS (attrs->>'theme') STORED
+);
+CREATE INDEX profiles_attrs_gin ON profiles USING GIN (attrs);
+```

package/org-skills/postmortem-writing/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Seth Hobson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.