[pumarogie]

What this is

The six skills were good structurally but had real gaps and two factual errors. This adds the missing production rules, corrects the errors, and puts a validation gate and an eval harness in the repo.

Highest-value additions

• lock_timeout and the lock-queue failure mode. The outage people actually hit is not the rewrite — it is a statement waiting for ACCESS EXCLUSIVE while every query behind it queues too. The table goes down without the migration ever acquiring its lock. This was absent entirely.
• Invalid index cleanup. A failed CREATE INDEX CONCURRENTLY leaves an invalid index that must be dropped before retrying. The skill taught the command, not the recovery.
• DDL lock levels (skills/writing-safe-migrations/reference/lock-levels.md) — which operations rewrite, which are catalog-only, which allow concurrent traffic.
• pgbouncer pooling modes and what breaks under transaction pooling: prepared statements, advisory locks, LISTEN/NOTIFY, session variables, temp tables.
• Concrete autovacuum values. The skill previously said "tune more aggressively" without saying to what.
• pg_stat_statements. The performance skill previously began at "you already know which query is slow."
• Atomic queue claim — UPDATE ... FROM (SELECT ... FOR UPDATE SKIP LOCKED) ... RETURNING, plus lease expiry, a partial index, and idempotency.

Corrections

• timestamptz stores an instant and discards the original offset. The previous text said it stores "UTC + offset", which is wrong and would mislead anyone deciding whether to keep a separate timezone column.
• Removed an unverifiable claim that PostgreSQL 19 adds native REPACK … CONCURRENTLY.

CI

.github/workflows/validate-skills.yml validates every SKILL.md with no dependencies: frontmatter parses, name and description meet the documented limits, name matches its directory, and every relative link resolves.

Evals — read before citing any number

18 cases, three per skill, with a two-arm runner comparing responses with and without the skills.

No improvement claim is published, deliberately. Measured on Sonnet: baseline 66/90, with skills 76/90. But between two runs of the same configuration, 20% of items flipped verdict — a noise floor of roughly ±10 on 90, the same size as the effect. At one run per case these numbers cannot separate a real effect from sampling variation.

evals/FINDINGS.md documents this in full, including the two design flaws that must be fixed before any published number is honest: the rubric was written after reading the skills (teaching to the test), and there are no repeats per cell.

The skills are better on inspection. That claim rests on review, not on the eval.

Verification

• Validator passes on all six skills.
• Both plugin manifests parse.
• Every SKILL.md under 500 lines; reference files one level deep.

Skills grew from ~470 to ~650 words each. That length bought prominence for rules that were being dropped from responses when they lived in reference files — a tradeoff worth revisiting later.

Summary by CodeRabbit

• Documentation

  • Expanded PostgreSQL guidance for safe migrations, schema design, query performance, connection pooling, advanced operational patterns, and autovacuum/bloat management.
  • Added practical references covering pooling modes, DDL locks, and transaction-wraparound monitoring.
  • Added contribution guidelines and clarified project sources, evaluation methodology, and findings.

• Quality Improvements

  • Added automated validation for skill documentation, including metadata and link checks.
  • Added evaluation cases and reporting tools to assess guidance quality.
  • Updated project metadata, licensing, keywords, and version information.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ede107bd-5879-4bc6-b614-468c44e64763

📥 Commits

Reviewing files that changed from the base of the PR and between 698800d and c40ed60.

📒 Files selected for processing (18)

• .claude-plugin/plugin.json
• .github/workflows/validate-skills.yml
• .gitignore
• CONTRIBUTING.md
• README.md
• evals/FINDINGS.md
• evals/README.md
• evals/cases.jsonl
• evals/run.py
• skills/designing-postgres-schemas/SKILL.md
• skills/managing-postgres-connections/SKILL.md
• skills/managing-postgres-connections/reference/pgbouncer-pooling-modes.md
• skills/postgres-advanced-patterns/SKILL.md
• skills/tuning-autovacuum-and-bloat/SKILL.md
• skills/tuning-autovacuum-and-bloat/reference/autovacuum-settings-and-wraparound.md
• skills/writing-performant-queries/SKILL.md
• skills/writing-safe-migrations/SKILL.md
• skills/writing-safe-migrations/reference/lock-levels.md

---

📝 Walkthrough

Walkthrough

The change adds repository metadata and skill validation, introduces a two-arm evaluation harness, and revises PostgreSQL guidance for schemas, connections, operational patterns, vacuum, query diagnosis, and safe migrations.

Changes

Postgres skills repository update

Layer / File(s)	Summary
Repository metadata and validation .claude-plugin/plugin.json, .github/workflows/validate-skills.yml, .gitignore, CONTRIBUTING.md, README.md	Plugin metadata, contribution guidance, ignored evaluation outputs, source documentation, and automated skill validation are added or updated.
Evaluation cases and runner evals/*	Evaluation cases, methodology, findings, and a CLI for baseline/treatment generation, rubric grading, and reporting are added.
Schema and connection guidance skills/designing-postgres-schemas/*, skills/managing-postgres-connections/*	Schema invariants, JSONB, keys, pooling modes, connection budgets, session-state constraints, and saturation diagnosis are documented.
Operational patterns and vacuum skills/postgres-advanced-patterns/*, skills/tuning-autovacuum-and-bloat/*	Queue leases, batching, partition maintenance, live-table movement, autovacuum tuning, wraparound monitoring, and bloat remediation are expanded.
Query diagnosis and safe migrations skills/writing-performant-queries/*, skills/writing-safe-migrations/*	Evidence-first query diagnosis, index verification, lock management, concurrent DDL, bounded backfills, and expand-and-contract migrations are documented.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant EvaluationCases
  participant EvaluationRunner
  participant ClaudeCLI
  participant GradeReport
  EvaluationCases->>EvaluationRunner: load cases
  EvaluationRunner->>ClaudeCLI: generate baseline and treatment responses
  ClaudeCLI-->>EvaluationRunner: return responses
  EvaluationRunner->>ClaudeCLI: grade responses against rubrics
  ClaudeCLI-->>GradeReport: return verdicts
  GradeReport-->>EvaluationRunner: aggregate skill scores

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch harden-skills-v0.2.0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}