vouchington-tooling 0.1.9 → 0.3.0

package/dist/skill-discovery/target-directory.mjs

@@ -0,0 +1,126 @@
+import { execFile } from 'node:child_process';
+import { lstat } from 'node:fs/promises';
+import { parse, relative, resolve, sep, join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function resolveTargetDirectory(targetRoot, beforeRevalidate) {
+    const path = resolve(targetRoot);
+    const ancestors = await snapshotTargetAncestors(path);
+    await beforeRevalidate?.();
+    await assertTargetAncestorsUnchanged(ancestors);
+    return ancestors.at(-1);
+}
+export async function linkDirectoryEntry(source, target, name, beforeWorker, worker = runDirectoryLinkWorker, afterWorker) {
+    await beforeWorker?.();
+    const stdout = await worker(source, target, name);
+    await afterWorker?.();
+    await assertTargetUnchanged(target);
+    if (stdout === 'created')
+        return true;
+    if (stdout === 'existing')
+        return false;
+    throw new Error('Skill link worker returned an invalid result');
+}
+async function runDirectoryLinkWorker(source, target, name) {
+    try {
+        const { stdout } = await execFileAsync(process.execPath, [
+            '--input-type=module',
+            '--eval',
+            LINK_WORKER,
+            source,
+            name,
+            String(target.dev),
+            String(target.ino),
+        ], { cwd: target.path, windowsHide: true });
+        return stdout;
+    }
+    catch (error) {
+        if (error.stderr?.includes('Target root changed during skill linking'))
+            throw new Error('Target root changed during skill linking');
+        throw error;
+    }
+}
+export async function snapshotTargetDirectory(path) {
+    const stat = await lstat(path, { bigint: true });
+    if (stat.isSymbolicLink())
+        throw new Error(`Target root contains symlink: ${path}`);
+    if (!stat.isDirectory())
+        throw new Error(`Invalid target root: ${path}`);
+    return { path, dev: stat.dev, ino: stat.ino };
+}
+async function assertTargetUnchanged(target) {
+    try {
+        const current = await snapshotTargetDirectory(target.path);
+        if (current.dev === target.dev && current.ino === target.ino)
+            return;
+    }
+    catch { }
+    throw new Error('Target root changed during skill linking');
+}
+async function snapshotTargetAncestors(path) {
+    const parsed = parse(path);
+    let ancestor = parsed.root;
+    const ancestors = [];
+    for (const component of relative(parsed.root, path).split(sep)) {
+        ancestor = join(ancestor, component);
+        try {
+            ancestors.push(await snapshotTargetDirectory(ancestor));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                throw new Error(`Target root must exist: ${path}`);
+            throw error;
+        }
+    }
+    return ancestors;
+}
+async function assertTargetAncestorsUnchanged(ancestors) {
+    try {
+        for (const target of ancestors) {
+            const current = await snapshotTargetDirectory(target.path);
+            if (current.dev !== target.dev || current.ino !== target.ino)
+                throw new Error('Target root changed while resolving');
+        }
+    }
+    catch {
+        throw new Error('Target root changed while resolving');
+    }
+}
+const LINK_WORKER = String.raw `
+import { lstat, readlink, symlink } from 'node:fs/promises'
+
+const [source, name, dev, ino] = process.argv.slice(1)
+const directory = await lstat('.', { bigint: true })
+if (!directory.isDirectory() || directory.isSymbolicLink() || directory.dev !== BigInt(dev) || directory.ino !== BigInt(ino))
+  throw new Error('Target root changed during skill linking')
+async function assertExistingMatchesSource() {
+  const destination = await lstat(name)
+  if (!destination.isSymbolicLink() || (await readlink(name)) !== source)
+    throw new Error('Destination already exists: ' + name)
+}
+
+let created = false
+try {
+  await assertExistingMatchesSource()
+} catch (error) {
+  if (error?.code !== 'ENOENT') throw error
+  try {
+    await symlink(source, name, 'dir')
+    created = true
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      await assertExistingMatchesSource()
+    } else {
+      if (process.platform !== 'win32' || !['EACCES', 'EPERM'].includes(error?.code)) throw error
+      try {
+        await symlink(source, name, 'junction')
+        created = true
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error
+        await assertExistingMatchesSource()
+      }
+    }
+  }
+}
+process.stdout.write(created ? 'created' : 'existing')
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.1.9",
+  "version": "0.3.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -31,6 +31,11 @@
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
     },
+    "./skill-discovery": {
+      "types": "./dist/skill-discovery/index.d.mts",
+      "import": "./dist/skill-discovery/index.mjs",
+      "default": "./dist/skill-discovery/index.mjs"
+    },
     "./runner-port-policy": {
       "types": "./dist/runner-port-policy/index.d.mts",
       "import": "./dist/runner-port-policy/index.mjs",
@@ -41,6 +46,16 @@
       "import": "./dist/retrospective-transcript/index.mjs",
       "default": "./dist/retrospective-transcript/index.mjs"
     },
+    "./retrospective-facts": {
+      "types": "./dist/retrospective-facts/index.d.mts",
+      "import": "./dist/retrospective-facts/index.mjs",
+      "default": "./dist/retrospective-facts/index.mjs"
+    },
+    "./agent-blackboard": {
+      "types": "./dist/agent-blackboard/index.d.mts",
+      "import": "./dist/agent-blackboard/index.mjs",
+      "default": "./dist/agent-blackboard/index.mjs"
+    },
     "./session-friction": {
       "types": "./dist/session-friction/index.d.mts",
       "import": "./dist/session-friction/index.mjs",
@@ -234,7 +249,16 @@
     "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@types/picomatch": "^4.0.3"
+    "@types/picomatch": "^4.0.3",
+    "agent-blackboard": "^0.3.1"
+  },
+  "peerDependencies": {
+    "agent-blackboard": "^0.3.1"
+  },
+  "peerDependenciesMeta": {
+    "agent-blackboard": {
+      "optional": true
+    }
   },
   "optionalDependencies": {
     "@libpg-query/parser": "^18.0.0"

package/scripts/build.mjs

@@ -1,7 +1,10 @@
 import { execFileSync } from 'node:child_process'
 import { chmod, copyFile, cp, mkdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import skillManifest from '../skill-manifest.json' with { type: 'json' }
+
 const packageRoot = new URL('..', import.meta.url)
 const dist = new URL('../dist', import.meta.url)
 
@@ -16,9 +19,18 @@ await copyFile(
   new URL('../src/runner-port-policy/runner-port-policy.json', import.meta.url),
   new URL('../dist/runner-port-policy/runner-port-policy.json', import.meta.url),
 )
-await cp(
-  new URL('../../../plugins/vouchington-workflow/skills', import.meta.url),
-  new URL('../skills', import.meta.url),
-  { recursive: true },
+const pluginRoot = fileURLToPath(new URL('../../../plugins', import.meta.url))
+const skillsRoot = fileURLToPath(new URL('../skills/', import.meta.url))
+const seenSkills = new Set()
+for (const skill of skillManifest.skills) {
+  if (seenSkills.has(skill.name)) throw new Error(`Duplicate skill: ${skill.name}`)
+  seenSkills.add(skill.name)
+  await cp(join(pluginRoot, skill.plugin, 'skills', skill.name), join(skillsRoot, skill.name), {
+    recursive: true,
+  })
+}
+await copyFile(
+  new URL('../skill-manifest.json', import.meta.url),
+  new URL('../skills/manifest.json', import.meta.url),
 )
 await chmod(new URL('../dist/cli/index.mjs', import.meta.url), 0o755)

package/scripts/gha/harness-admission-lane.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "${#}" -ne 1 ]; then
+  echo "usage: harness-admission-lane.sh <lanes>" >&2
+  exit 2
+fi
+
+if [ -z "${GITHUB_OUTPUT:-}" ]; then
+  echo 'GITHUB_OUTPUT must be set' >&2
+  exit 2
+fi
+
+LANES="$1"
+if ! [[ "$LANES" =~ ^[1-9][0-9]*$ ]]; then
+  echo "::error::admission lane count must be a positive integer, got: '$LANES'"
+  exit 1
+fi
+
+RUN_ID="${GITHUB_RUN_ID:-}"
+if ! [[ "$RUN_ID" =~ ^[0-9]+$ ]]; then
+  echo "::error::GITHUB_RUN_ID must be a non-negative integer, got: '${RUN_ID}'"
+  exit 1
+fi
+
+echo "lane=$(( RUN_ID % LANES ))" >> "$GITHUB_OUTPUT"

package/scripts/gha/harness-assert-gates.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+  echo "usage: harness-assert-gates.sh <gate>..." >&2
+  exit 2
+fi
+
+for gate in "$@"; do
+  if ! [[ "$gate" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+    echo "::error::invalid gate name: '$gate'"
+    exit 1
+  fi
+done
+
+for gate in "$@"; do
+  value="${!gate:-}"
+  if [ "$value" = "true" ]; then
+    echo "::error::$gate must be disabled but is enabled"
+    exit 1
+  fi
+done
+
+exit 0

package/skills/agent-workflow/SKILL.md

@@ -23,5 +23,10 @@ branching, review, and release policy.
 6. Review the diff for accidental files, secrets, generated output, broken documentation links,
    and assumptions that belong in local instructions instead.
 
+For portable implementation and review checks, read [implementation](references/implementation.md),
+[review](references/review.md), and [evidence sweep](references/evidence-sweep.md). The older
+[implementation and review](references/implementation-and-review.md) remains a compact overview.
+Local instructions remain authoritative for commands, commits, review systems, and release policy.
+
 Do not invent a default branch, runner class, documentation root, review system, merge policy, or
 command catalog. A consumer wrapper or local instruction file owns those choices.

package/skills/agent-workflow/references/evidence-sweep.md

@@ -0,0 +1,8 @@
+# Evidence sweep
+
+Map every acceptance criterion to a focused test, inspection, or manual verification with a concrete
+result. Run the required broader checks after focused validation. Treat skipped validation as a
+finding: state the blocker, affected surface, and remaining risk.
+
+Before handoff, compare the final diff to the accepted decision ledger and verify documentation,
+generated output, and public contracts agree with the implementation.

package/skills/agent-workflow/references/implementation-and-review.md

@@ -0,0 +1,9 @@
+# Implementation and review
+
+Before editing, map callers, tests, configuration, and documentation that own the behavior. Keep the
+change within the accepted boundary; record a new dependency or product decision before widening it.
+
+After focused validation, inspect the complete diff for accidental generated files, secret exposure,
+dead paths, and documentation drift. Validate the public interface and failure paths, not only the
+happy path. Before a reviewable commit, run the repository-required checks and state any skipped
+checks with their concrete blocker.

package/skills/agent-workflow/references/implementation.md

@@ -0,0 +1,8 @@
+# Implementation
+
+Keep an accepted-decision ledger for interfaces, data boundaries, validation, and ownership choices
+that could otherwise be lost during coding. Start from a failing behavioral test when practical and
+complete the real path rather than adding placeholders or compatibility shims without a requirement.
+
+When behavior changes, update the public contract, documentation, fixtures, and generated artifacts
+that describe it. Keep local commands, branch policy, and release mechanics in the consumer wrapper.

package/skills/agent-workflow/references/review.md

@@ -0,0 +1,7 @@
+# Review
+
+Review the complete diff, not only changed implementation lines. Check premise and scope, public
+contract compatibility, failure paths, authorization, untrusted input, secrets, and security
+boundaries. Remove dead paths and stale documentation rather than labeling them as legacy.
+
+Record unresolved risk as an explicit accepted decision or follow-up, never as an unnoticed gap.

package/skills/backend-vitest-test-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: backend-vitest-test-authoring
+description: Apply backend Vitest patterns for service, provider, persistence, and queue boundaries.
+---
+
+# Backend Vitest test authoring
+
+Apply [vitest-test-authoring](../vitest-test-authoring/SKILL.md) first. Exercise real integration
+boundaries only when their lifecycle is controlled by the test environment; otherwise mock the
+network or provider edge. Randomize fixture identities where shared stores can collide, assert
+authorization and retry behavior at boundaries, and clean up resources deterministically.
+
+Consumer wrappers own database setup, queue providers, test projects, and rate-limit policy.
+
+Read [integration boundaries](references/integration-boundaries.md) for fixture and collision safety.

package/skills/backend-vitest-test-authoring/references/integration-boundaries.md

@@ -0,0 +1,10 @@
+# Integration boundaries
+
+Use real persistence, queue, and internal-service boundaries when the test environment controls
+their lifecycle. Mock only external provider edges. Create collision-safe fixture identities and
+register event listeners before the mutation that produces them. Cleanup must be ownership-scoped;
+never broadly reset shared state used by concurrent tests.
+
+Assert persisted state, emitted work, or externally visible results at the boundary. A mock-only
+test is insufficient when import wiring, serialization, transaction behavior, or retries are part
+of the contract.

package/skills/dotnet-test-authoring/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: dotnet-test-authoring
+description: Add maintainable .NET tests with appropriate unit, app, and integration boundaries.
+---
+
+# .NET test authoring
+
+Place tests at the narrowest layer that proves the behavior. Batch native or external selection
+where the project requires it, isolate process and filesystem state, and assert serialized contracts
+instead of private implementation details. Keep test helpers typed and reusable only when they remove
+repeated setup without hiding important expectations.
+
+Consumer wrappers own solution layout, test frameworks, native dependencies, and coverage policy.
+
+Keep portable library tests separate from rendered application tests; batch compatible native targets
+in one selection pass so a shared build validates the same source set.

package/skills/manifest.json

@@ -0,0 +1,158 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "name": "agent-workflow",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "agent-workflow/SKILL.md"
+    },
+    {
+      "name": "backend-vitest-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "backend-vitest-test-authoring/SKILL.md",
+      "prerequisites": ["vitest-test-authoring"]
+    },
+    {
+      "name": "blackboard",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "blackboard/SKILL.md"
+    },
+    {
+      "name": "dotnet-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "dotnet-test-authoring/SKILL.md"
+    },
+    {
+      "name": "git-commit-checklist",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "git-commit-checklist/SKILL.md"
+    },
+    {
+      "name": "github-actions-checklist",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "github-actions-checklist/SKILL.md"
+    },
+    {
+      "name": "github-issue",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "github-issue/SKILL.md"
+    },
+    {
+      "name": "nextjs-vitest-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "nextjs-vitest-test-authoring/SKILL.md",
+      "prerequisites": ["vitest-test-authoring"]
+    },
+    {
+      "name": "organize-github-issues",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "organize-github-issues/SKILL.md"
+    },
+    {
+      "name": "package-json-checklist",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "package-json-checklist/SKILL.md"
+    },
+    {
+      "name": "planning",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "planning/SKILL.md"
+    },
+    {
+      "name": "playwright-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "playwright-authoring/SKILL.md"
+    },
+    {
+      "name": "postgres-node-performance-tuning",
+      "plugin": "vouchington-database",
+      "pluginVersion": "0.1.0",
+      "path": "postgres-node-performance-tuning/SKILL.md"
+    },
+    {
+      "name": "postgres-partitioning-uuid-v7",
+      "plugin": "vouchington-database",
+      "pluginVersion": "0.1.0",
+      "path": "postgres-partitioning-uuid-v7/SKILL.md"
+    },
+    {
+      "name": "pr-description",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "pr-description/SKILL.md"
+    },
+    {
+      "name": "retrospective",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "retrospective/SKILL.md"
+    },
+    {
+      "name": "retrospective-distill",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "retrospective-distill/SKILL.md"
+    },
+    {
+      "name": "review-ci-logs",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "review-ci-logs/SKILL.md"
+    },
+    {
+      "name": "review-github-issue-taxonomy",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "review-github-issue-taxonomy/SKILL.md"
+    },
+    {
+      "name": "revisit-followups",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "revisit-followups/SKILL.md"
+    },
+    {
+      "name": "static-analysis-checklist",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "static-analysis-checklist/SKILL.md"
+    },
+    {
+      "name": "storybook-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "storybook-authoring/SKILL.md"
+    },
+    {
+      "name": "swift-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "swift-test-authoring/SKILL.md"
+    },
+    {
+      "name": "test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "test-authoring/SKILL.md"
+    },
+    {
+      "name": "vitest-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "vitest-test-authoring/SKILL.md",
+      "prerequisites": ["test-authoring"]
+    }
+  ]
+}

package/skills/nextjs-vitest-test-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: nextjs-vitest-test-authoring
+description: Apply Vitest patterns for Next.js components, routes, and server-side modules.
+---
+
+# Next.js Vitest test authoring
+
+Apply [vitest-test-authoring](../vitest-test-authoring/SKILL.md) first. Mock framework navigation,
+headers, and server-only boundaries at the framework edge, then test component behavior through
+rendered output and user-visible state. Keep API-response fixtures representative and avoid testing
+framework internals. Use browser tests for behavior that cannot be represented in the test runtime.
+
+Consumer wrappers own framework mock helpers, render libraries, and route fixture conventions.
+
+Read [framework boundaries](references/framework-boundaries.md) for module shape and server-only cases.

package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md

@@ -0,0 +1,9 @@
+# Framework boundaries
+
+Mock framework navigation, headers, cookies, and server-only APIs at the framework edge, not inside
+the component or route under test. Preserve typed module shape and use the consumer's shared mocks
+when they exist. Build API responses with typed factories rather than inline partial objects.
+
+Use direct rendering for component behavior. If request scope, hydration, browser APIs, or server
+module resolution cannot be represented faithfully, move the assertion to an integration or browser
+test instead of widening a unit-test mock.

package/skills/planning/SKILL.md

@@ -19,5 +19,8 @@ Use before implementation work that needs a durable plan. Repository-local `AGEN
 5. Validate and save the plan using the repository's required issue or document workflow before
    implementation when local policy requires one.
 
+For cross-cutting changes, read [impact discovery](references/impact-discovery.md) before selecting
+tests or concluding that a surface has no dependents.
+
 Do not invent a plan template, default repository, issue taxonomy, dependency graph tool, or
 approval workflow. A consumer wrapper owns those choices.

package/skills/planning/references/impact-discovery.md

@@ -0,0 +1,9 @@
+# Impact discovery
+
+Start from the changed surface and trace imports, callers, configuration, generated artifacts, and
+tests. Use the repository's graph or search tools where available; otherwise record the evidence
+used and the uncertainty that remains. Select focused tests from real dependents, then include
+broader validation when a shared contract, package boundary, or generated artifact changes.
+
+Do not treat a tool's incomplete graph as proof that no dependent exists. Escalate uncertain
+high-risk boundaries for independent review or a broader test selection.

package/skills/playwright-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: playwright-authoring
+description: Author reliable Playwright browser tests, fixtures, selectors, and user flows.
+---
+
+# Playwright authoring
+
+Use stable, accessible locators and assert user-observable outcomes. Establish data, authentication,
+and server state through supported fixtures or APIs; do not rely on test ordering or arbitrary waits.
+Keep each scenario independently repeatable, use auto-waiting assertions, and capture diagnostics on
+failure. Prefer browser coverage for real browser interactions rather than duplicating unit tests.
+
+Consumer wrappers own environments, credentials, personas, fixtures, and suite commands.
+
+Read [browser reliability](references/browser-reliability.md) for locator, waiting, state, and network rules.

package/skills/playwright-authoring/references/browser-reliability.md

@@ -0,0 +1,9 @@
+# Browser reliability
+
+Use the browser only for browser-owned behavior. Prefer stable accessibility or test-id locators,
+scope repeated content, and assert visible outcomes. Never use arbitrary sleeps; wait for a precise
+URL, request, response, DOM state, or user-visible completion signal.
+
+Seed deterministic data and establish authentication through supported fixtures. Mock network only
+for third-party behavior, fault injection, streaming, or conditions impossible to seed. Register
+response waits before triggering mutations, and make each scenario independent of prior state.

package/skills/postgres-node-performance-tuning/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: postgres-node-performance-tuning
+description: Diagnose and improve PostgreSQL performance in Node.js applications with large data volumes.
+---
+
+# PostgreSQL and Node.js performance
+
+Measure query plans and workload shape before changing code. Select only required columns, bound
+result sets, paginate or stream large reads, batch writes within explicit transaction limits, and
+keep connection-pool usage bounded. Validate query changes with representative cardinality and
+watch latency, memory, lock time, and connection pressure together.
+
+Consumer wrappers own schema ownership, operational thresholds, pooling configuration, and rollout.
+
+Read [performance patterns](references/performance-patterns.md) before changing high-volume paths.

package/skills/postgres-node-performance-tuning/references/performance-patterns.md

@@ -0,0 +1,14 @@
+# Performance patterns
+
+Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
+Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
+transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
+
+For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
+For writes, prefer set-based batches such as UNNEST or COPY when they preserve validation and error
+handling. Measure query plans with representative cardinality before changing an index or query.
+
+Check query predicates, joins, ordering, and selected columns against index shape. Use EXPLAIN
+evidence to confirm planner behavior. Add extended statistics only when observed estimates show a
+correlation problem; verify the statistics are collected and used. Partitioning can reduce scanned
+data, but it does not replace suitable local indexes or predicates that permit pruning.

package/skills/postgres-partitioning-uuid-v7/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: postgres-partitioning-uuid-v7
+description: Design PostgreSQL partitions and indexes that use time-ordered UUIDv7 identifiers efficiently.
+---
+
+# PostgreSQL partitioning with UUIDv7
+
+Partition only after confirming lifecycle, retention, and query predicates benefit from it. Treat a
+UUIDv7 as time ordered but not as a replacement for explicit business timestamps where semantics
+matter. Align partition keys, primary keys, indexes, constraints, and query predicates so partition
+pruning is observable. Plan creation, retention, migration, and verification as one deployable
+lifecycle, including rollback and independent-reader compatibility.
+
+Consumer wrappers own partition intervals, migration tooling, retention policy, and deploy sequencing.
+
+Read [partition lifecycle](references/partition-lifecycle.md) before a schema or retention migration.