vouchington-tooling 2.0.1 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/dist/host-lock/with-host-lock.test-helpers.d.mts +10 -0
  2. package/dist/host-lock/with-host-lock.test-helpers.mjs +27 -1
  3. package/dist/sql-ast/no-mistakes-peer.d.mts +29 -0
  4. package/package.json +3 -3
  5. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  6. package/skills/manifest.json +15 -202
  7. package/skills/organize-github-issues/SKILL.md +20 -3
  8. package/skills/pr-description/SKILL.md +9 -65
  9. package/skills/retrospective/SKILL.md +15 -0
  10. package/skills/retrospective-distill/SKILL.md +1 -1
  11. package/skills/retrospective-distill/references/issue-body.md +6 -1
  12. package/skills/review-github-issue-taxonomy/SKILL.md +3 -4
  13. package/skills/triage-loop/SKILL.md +115 -30
  14. package/skills/triage-prs/SKILL.md +26 -27
  15. package/skills/triage-prs/references/feedback.md +14 -2
  16. package/skills/triage-prs/references/rubric.md +4 -4
  17. package/skills/triage-sweep/SKILL.md +41 -27
  18. package/skills/agent-workflow/SKILL.md +0 -72
  19. package/skills/agent-workflow/references/evidence-sweep.md +0 -12
  20. package/skills/agent-workflow/references/four-refs.md +0 -74
  21. package/skills/agent-workflow/references/implementation-and-review.md +0 -4
  22. package/skills/agent-workflow/references/implementation.md +0 -20
  23. package/skills/agent-workflow/references/review-response.md +0 -49
  24. package/skills/agent-workflow/references/review.md +0 -10
  25. package/skills/backend-vitest-test-authoring/SKILL.md +0 -22
  26. package/skills/backend-vitest-test-authoring/references/integration-boundaries.md +0 -10
  27. package/skills/bounded-iteration/SKILL.md +0 -92
  28. package/skills/bounded-iteration/references/sweep-patterns.md +0 -719
  29. package/skills/dependabot/SKILL.md +0 -117
  30. package/skills/dotnet-test-authoring/SKILL.md +0 -24
  31. package/skills/git-commit-checklist/SKILL.md +0 -29
  32. package/skills/github-actions-authoring/SKILL.md +0 -63
  33. package/skills/github-actions-checklist/SKILL.md +0 -118
  34. package/skills/github-issue/SKILL.md +0 -121
  35. package/skills/glide-mq/SKILL.md +0 -52
  36. package/skills/glide-mq/references/lease-patterns.md +0 -44
  37. package/skills/nextjs-vitest-test-authoring/SKILL.md +0 -21
  38. package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md +0 -9
  39. package/skills/npm-publishing/SKILL.md +0 -72
  40. package/skills/package-json-checklist/SKILL.md +0 -31
  41. package/skills/planning/SKILL.md +0 -37
  42. package/skills/planning/references/impact-discovery.md +0 -11
  43. package/skills/playwright-authoring/SKILL.md +0 -23
  44. package/skills/playwright-authoring/references/browser-reliability.md +0 -9
  45. package/skills/postgres-node-performance-tuning/SKILL.md +0 -35
  46. package/skills/postgres-node-performance-tuning/references/performance-patterns.md +0 -175
  47. package/skills/postgres-node-performance-tuning/references/reading-plans.md +0 -111
  48. package/skills/postgres-partitioning-uuid-v7/SKILL.md +0 -35
  49. package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md +0 -53
  50. package/skills/postgres-schema-design/SKILL.md +0 -31
  51. package/skills/postgres-schema-design/references/naming.md +0 -34
  52. package/skills/postgres-schema-design/references/relations.md +0 -66
  53. package/skills/postgres-schema-design/references/table-shapes.md +0 -78
  54. package/skills/pr-description/references/examples.md +0 -189
  55. package/skills/review-ci-logs/SKILL.md +0 -44
  56. package/skills/revisit-followups/SKILL.md +0 -47
  57. package/skills/stacked-prs/SKILL.md +0 -98
  58. package/skills/stacked-prs/references/drain.md +0 -177
  59. package/skills/stacked-prs/references/gh-stack.md +0 -147
  60. package/skills/static-analysis-checklist/SKILL.md +0 -32
  61. package/skills/storybook-authoring/SKILL.md +0 -22
  62. package/skills/storybook-authoring/references/component-coverage.md +0 -9
  63. package/skills/swift-test-authoring/SKILL.md +0 -23
  64. package/skills/swift-test-authoring/references/network-test-doubles.md +0 -9
  65. package/skills/test-authoring/SKILL.md +0 -27
  66. package/skills/test-authoring/references/core-practice.md +0 -16
  67. package/skills/test-authoring/references/dependency-boundaries.md +0 -38
  68. package/skills/test-authoring/references/tautological-tests.md +0 -47
  69. package/skills/triage-loop/references/shepherd.md +0 -62
  70. package/skills/vitest-test-authoring/SKILL.md +0 -22
  71. package/skills/vitest-test-authoring/references/mock-boundaries.md +0 -9
@@ -1,72 +0,0 @@
1
- ---
2
- name: npm-publishing
3
- description: Prepare npm bootstrap and trusted publishing commands for a human.
4
- ---
5
-
6
- # npm publishing bootstrap
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/npm-publishing/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Prepare the local package. Leave public registry writes and trusted-publisher mutations to the
13
- human. Read every applicable `AGENTS.md` from the repository root through the
14
- package. Repository-local policy and the consumer wrapper own the package path and name, npm scope,
15
- GitHub repository, release workflow, build commands, and whether a laptop may publish.
16
-
17
- ## Prepare the package
18
-
19
- - Resolve the absolute repository root, the package directory relative to that root, the exact npm
20
- package name, `owner/repository`, and the release workflow filename. The workflow value is the
21
- case-sensitive filename under `.github/workflows`, not a path. Leave no placeholders in the final
22
- commands.
23
- - Confirm npm 11.15 or newer, account-level two-factor authentication, and write access to the
24
- package or scope.
25
- - On the default branch, the workflow must grant `id-token: write`, use a supported runner, install
26
- an npm version that can trusted-publish, and publish this package.
27
- - When the package does not exist in the registry, create the smallest useful stub in its intended
28
- directory. Follow neighboring packages for metadata, source, exports, types, license, README,
29
- build output, and workspace registration.
30
- - Do not replace an existing module with a stub. Do not publish a version already in the registry.
31
- - Build the package, then inspect the payload with
32
- `npm publish <package-directory> --access public --dry-run`. Stop if it includes secrets,
33
- environment files, source maps, unrelated workspace files, or a missing runtime or type
34
- entrypoint. The dry run must include `prepublishOnly`. A pack-only check misses that script.
35
- - If the package already exists, have the human run `npm trust list <package-name>` before any
36
- mutation. Omit the initial publish command. If trust already exists, report it and omit trust
37
- creation. Do not revoke or replace it.
38
-
39
- ## Hand off the mutations
40
-
41
- - Do not run a real `npm publish` or a mutating `npm trust` subcommand.
42
- - Say that the first command creates an externally visible, effectively irreversible package
43
- version, and the second grants the named workflow publish authority.
44
- - Include the publish command only when bootstrapping a package that does not exist. An existing
45
- package with an empty trust list goes straight to trust setup.
46
- - Tell the human to append a current one-time password after each final `--otp=` and not to share
47
- or record it. Warn that `--otp=` can expose the OTP in shell history and process arguments, and
48
- to follow local secret-handling policy.
49
- - Give the applicable commands with resolved values, in this order:
50
-
51
- ```sh
52
- cd /absolute/repository/root
53
- npm publish ./relative/package-directory --access public --otp=
54
- npm trust github @scope/package \
55
- --repo owner/repository \
56
- --file release.yml \
57
- --allow-publish \
58
- --yes \
59
- --otp=
60
- ```
61
-
62
- - The `cd` target is the directory from which the relative publish path resolves.
63
- - If local policy prohibits publishing from this machine, say so and name the approved environment.
64
- Keep the same command order.
65
- - Ask the human to confirm the payload, package name, repository, workflow filename, and publish
66
- permission immediately before running the commands.
67
- - Afterward, have the human verify any newly published version and run `npm trust list` again.
68
- - Do not retry an authorization or registry failure blindly. Do not fall back to a long-lived npm
69
- token without explicit direction.
70
-
71
- Consumer wrapper owns: package path and name, npm scope, GitHub repository, release workflow, build
72
- commands, and whether a laptop may publish.
@@ -1,31 +0,0 @@
1
- ---
2
- name: package-json-checklist
3
- description: Check package metadata, dependencies, entrypoints, and lockfiles.
4
- ---
5
-
6
- # Package metadata checklist
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/package-json-checklist/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Use before changing `package.json`, a lockfile, workspace metadata, or a package entrypoint. Read
13
- every applicable `AGENTS.md` from the repository root through the owning package,
14
- applying the closest file only when rules conflict. Those instructions own package-manager version,
15
- dependency age/version policy, registry, release process, and package layout.
16
-
17
- 1. Identify the owning package and every consumer of the changed script, dependency, export, or
18
- binary. Prefer existing workspace utilities before adding a dependency.
19
- 2. Use the repository's package manager for dependency changes. Update the lockfile when it records
20
- the affected metadata; avoid lockfile churn for metadata-only edits it does not record. Keep
21
- peer,
22
- optional, development, and runtime dependencies in their intended sections.
23
- 3. For a published package, verify exports, types, files, binaries, and build output match the
24
- package's supported import and installation paths.
25
- 4. Run the package manager's integrity check, focused tests, typecheck, build, and local policy
26
- checks required by the affected package. Do not publish or alter registry state without explicit
27
- authorization.
28
- 5. Review the lockfile and generated metadata for unrelated churn before committing.
29
-
30
- Local instructions or the consumer wrapper own: version range, workspace topology, registry,
31
- package-manager command, and release convention.
@@ -1,37 +0,0 @@
1
- ---
2
- name: planning
3
- description: Plan a repository change and save the decision outside Git.
4
- ---
5
-
6
- # Planning
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/planning/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Use when a task needs a plan. Scale detail to uncertainty and impact; no fixed headings, tables,
13
- diagram, independent reviewer, or separate issue are required by this skill.
14
-
15
- 1. State the desired outcome and compare no change, reuse, and alternative approaches. Choose the
16
- smallest durable option; ask before treating an unresolved product choice as settled.
17
- 2. Read applicable instructions, documentation, current code, tests, and recent changes from a
18
- fresh base. Record which evidence supports each proposed path.
19
- 3. Map affected owners, contracts, operational boundaries, and tests. Use independent review or
20
- exploration when the change is cross-cutting or uncertain and local policy calls for it.
21
- 4. Record the chosen approach, steps, validation, and unresolved decisions. Mark which steps run
22
- concurrently and name the dependency that serializes each remaining step. Add rollout details
23
- only when an established deployment contract requires them.
24
- 5. Save the plan once outside Git: an existing issue, a PR description, or a durable native plan
25
- file outside the repository. Do not commit task plans or count temporary scratch files as saved
26
- plans. If no durable record is available, use an issue through the local issue workflow. Link
27
- the record from the handoff instead of duplicating it. When creating a plan issue from a source issue
28
- that already has a milestone or project, apply that same existing milestone or project through
29
- [github-issue](../github-issue/SKILL.md).
30
-
31
- For cross-cutting changes, read [impact discovery](references/impact-discovery.md) before selecting
32
- tests or concluding that a surface has no dependents.
33
-
34
- On a `/plan` comment, the triage loop's subagent drafts the plan, the loop asks the human its
35
- open questions, then posts the plan on the source issue or PR as the durable record.
36
-
37
- Consumer wrapper owns: durable plan storage, repository, taxonomy, discovery tools, and approval.
@@ -1,11 +0,0 @@
1
- # Impact discovery
2
-
3
- Start from the changed surface and trace imports, callers, configuration, generated artifacts, and
4
- tests. Use the repository's graph or search tools where available; otherwise record the evidence
5
- used and the uncertainty that remains. Select focused tests from real dependents, then include
6
- broader validation when a shared contract, package boundary, or generated artifact changes.
7
-
8
- Check source-issue paths against current source before relying on them; issue text is a snapshot.
9
-
10
- Do not treat a tool's incomplete graph as proof that no dependent exists. Escalate uncertain
11
- high-risk boundaries for independent review or a broader test selection.
@@ -1,23 +0,0 @@
1
- ---
2
- name: playwright-authoring
3
- description: Author reliable Playwright flows, fixtures, and assertions.
4
- ---
5
-
6
- # Playwright authoring
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/playwright-authoring/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Apply [test-authoring](../test-authoring/SKILL.md).
13
-
14
- - Use a stable, accessible locator. Assert a user-observable outcome.
15
- - Establish data, authentication, and server state through a supported fixture or API.
16
- - Do not rely on test order or an arbitrary wait.
17
- - Keep each scenario independently repeatable. Use an auto-waiting assertion. Capture diagnostics
18
- on failure.
19
- - Use the browser for a real browser interaction. Do not repeat a unit test there.
20
- - Read [browser reliability](references/browser-reliability.md) for locator, waiting, state, and
21
- network rules.
22
-
23
- Consumer wrapper owns: environments, credentials, personas, fixtures, and suite commands.
@@ -1,9 +0,0 @@
1
- # Browser reliability
2
-
3
- Use the browser only for browser-owned behavior. Prefer stable accessibility or test-id locators,
4
- scope repeated content, and assert visible outcomes. Never use arbitrary sleeps; wait for a precise
5
- URL, request, response, DOM state, or user-visible completion signal.
6
-
7
- Seed deterministic data and establish authentication through supported fixtures. Mock network only
8
- for third-party behavior, fault injection, streaming, or conditions impossible to seed. Register
9
- response waits before triggering mutations, and make each scenario independent of prior state.
@@ -1,35 +0,0 @@
1
- ---
2
- name: postgres-node-performance-tuning
3
- description: Measure and improve PostgreSQL queries in Node.js services.
4
- ---
5
-
6
- # PostgreSQL and Node.js performance
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/postgres-node-performance-tuning/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Measure the query plan and the workload shape before changing code.
13
-
14
- Owner's principle: "the basic premise is to use the simplest query, and making it more complex
15
- requires explain analyze plans". Start with filters in `WHERE`, keyed `EXISTS`, joins or
16
- subqueries, `ORDER BY`, and `LIMIT`. A complex shape stays only with `EXPLAIN ANALYZE` plans showing
17
- it beats that simple query, not merely the previous version; see
18
- [simplest query first](references/performance-patterns.md#simplest-query-first).
19
-
20
- - Select only the required columns.
21
- - Bound each result set. Paginate or stream a large read. A stream bounds memory, not work: cap
22
- the rows per run as in [bounded iteration](../bounded-iteration/SKILL.md).
23
- - Batch writes inside an explicit transaction limit.
24
- - Keep connection-pool usage bounded.
25
- - Validate a query change at representative cardinality. Watch latency, memory, lock time, and
26
- connection pressure together.
27
- - Cut round trips without weakening correctness: fold dependent reads, batch per-item lookups, and
28
- overlap independent reads; see
29
- [round trips](references/performance-patterns.md#round-trips).
30
- - Read the plan for hidden per-row work before trusting a change; see
31
- [reading plans](references/reading-plans.md).
32
- - Read [performance patterns](references/performance-patterns.md) before changing a high-volume
33
- path.
34
-
35
- Consumer wrapper owns: schema ownership, operational thresholds, pooling configuration, and rollout.
@@ -1,175 +0,0 @@
1
- # Performance patterns
2
-
3
- Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
4
- Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
5
- transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
6
- Never use advisory locks, and never hold a transaction or connection across an external call; take
7
- a token lease in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
8
- renewal fails, and guard any write a stale owner could make with the token.
9
-
10
- For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
11
- For writes, prefer set-based batches such as UNNEST or COPY when they preserve validation and error
12
- handling. Do large list diffs and dedupes in the worker as a streaming comparison of sorted
13
- inputs, not as writer-side set operations. Measure query plans with representative cardinality
14
- before changing an index or query. Adding an index for a measured plan is a default: do not ask
15
- first and do not make it a spec stop condition.
16
-
17
- Check query predicates, joins, ordering, and selected columns against index shape. Use EXPLAIN
18
- evidence to confirm planner behavior. Add extended statistics only when observed estimates show a
19
- correlation problem; verify the statistics are collected and used. Partitioning can reduce scanned
20
- data, but it does not replace suitable local indexes or predicates that permit pruning.
21
-
22
- ## Query shapes
23
-
24
- ### Simplest query first
25
-
26
- Owner's principle: "hot/best should just be a JOIN and an ORDER BY". A ranked sort joins the
27
- entity to its stored score and orders by it. Filters go in `WHERE`; membership is a keyed `EXISTS`,
28
- join, or subquery; then `ORDER BY` and `LIMIT`.
29
-
30
- These need `EXPLAIN ANALYZE` plans, at representative cardinality, showing they beat the simple
31
- query for the same result, not merely the previous version on the base branch: `MATERIALIZED` or
32
- capped candidate CTEs, `UNION`, `GROUP BY` or `DISTINCT` dedupe, `LATERAL` joins and planner
33
- fences, cohort or window ranking, and multi-stage cap-filter-rank pipelines. Never build a
34
- candidate pool. A walk that stops at an inspected-row cap and returns a short or empty page with a
35
- continuation cursor is fine.
36
-
37
- Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
38
- `NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
39
- UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
40
- Read and return tables with explicit columns: no `SELECT *`, `alias.*`, or `RETURNING *`.
41
- A view may use `*` when its reviewed column list is the reader contract.
42
-
43
- Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CTE, not
44
- `OFFSET 0`. The fence keeps the outer query's filters and ordering away from the CTE's indexes.
45
- The outer query still reads CTE rows on demand and can stop at its `LIMIT`, but when its filters
46
- reject most CTE rows, or it sorts, aggregates or hash-joins them, it reads every row up to the CTE's own
47
- `LIMIT`. Use a `MATERIALIZED` CTE only when it holds the final `LIMIT`, or for a small
48
- viewer-scoped set, and only with plans showing it beats the plain query. Never use it as a
49
- candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
50
- cross-partition query. Choose the partition key from dominant access patterns; a hot reader
51
- of `RANGE (id)` needs an id or time bound.
52
-
53
- For a `RANGE (id)` child read by parent id, a shared lower-bound helper equivalent to
54
- `id >= min_uuidv7(uuid_extract_timestamp(parent_id) - interval '1 hour')` prunes earlier
55
- partitions; the overlap allows clock skew. It is safe only when every writer sets the parent at
56
- insert to an existing parent, never re-points it to a newer parent, and nothing mints child ids
57
- from a historical time; see
58
- [parent lower bound](../../postgres-partitioning-uuid-v7/references/partition-lifecycle.md#parent-lower-bound).
59
- Rate limits query an actor-keyed table rather than
60
- recipient-keyed fan-out rows. Verify actual pruning with EXPLAIN.
61
-
62
- Generic `jonathanong/no-mistakes` checks include `postgres-no-offset`; inspect available rules
63
- and configure reviewed cross-partition exceptions rather than treating a rule as plan evidence.
64
-
65
- ## Volatile functions in predicates
66
-
67
- `uuidv7(interval)` and `random()` are volatile: PostgreSQL evaluates them for every row, so
68
- `WHERE id >= uuidv7(INTERVAL '-30 days')` is a `Filter`, cannot be an `Index Cond`, and blocks
69
- partition pruning. Compute the bound once per statement and compare against that. A bind
70
- parameter works, as does a stable expression such as `now() - INTERVAL '30 days'` fed to a stable
71
- or immutable bound helper. A stable bound can be an index condition, and a partitioned table
72
- prunes at executor start. Confirm `Index Cond` and `Subplans Removed` in the plan.
73
-
74
- ```sql
75
- -- evaluated per row
76
- SELECT id FROM events WHERE id >= uuidv7(INTERVAL '-30 days');
77
- -- bound computed once by the caller
78
- SELECT id FROM events WHERE id >= $1;
79
- ```
80
-
81
- ## Function inlining
82
-
83
- PostgreSQL inlines a simple scalar SQL function into the calling query, so its body is planned
84
- with the outer query and its predicates can become index conditions. A SQL function whose body
85
- contains a subquery (for example `EXISTS`) is never inlined as a scalar call; a set-returning SQL
86
- function in `FROM` follows a separate inlining path. Functions with `SECURITY DEFINER` or
87
- a `SET` clause, and PL/pgSQL functions, are not inlined either, nor is a body that is not a single
88
- simple expression. When the function is not inlined, the plan shows only `fn_x(col)` in a `Filter`
89
- or output, and none of the queries it runs per row.
90
-
91
- ```sql
92
- -- not inlined: the EXISTS runs once per orders row
93
- CREATE FUNCTION fn_has_events(order_id uuid) RETURNS boolean
94
- LANGUAGE sql STABLE AS $$ SELECT EXISTS (SELECT 1 FROM events e WHERE e.order_id = $1) $$;
95
- SELECT id FROM orders WHERE fn_has_events(id);
96
- -- plannable: write the semi-join in the query
97
- SELECT o.id FROM orders o WHERE EXISTS (SELECT 1 FROM events e WHERE e.order_id = o.id);
98
- ```
99
-
100
- Tell from the plan: a function name in `Filter` or output with no matching scan nodes. Count calls
101
- with `SET LOCAL track_functions = 'all'` and `pg_stat_xact_user_functions` in the same transaction;
102
- inlined functions are not counted. See [reading plans](reading-plans.md#opaque-function-calls).
103
- Put per-row logic in the query as a join or `EXISTS`, or keep the function a plain expression.
104
-
105
- ## Reading views by key
106
-
107
- PostgreSQL expands a view into the calling query, and a simple view lets the outer filter push
108
- down into its base tables. A view that cannot be flattened (aggregation, `DISTINCT`, `LIMIT`,
109
- set operations, window functions, volatile target-list expressions, a security barrier) is built
110
- before a filter on a value it derives (such as an aggregate) applies, and before a sort, page, or
111
- count over its output. A restriction on a grouping column can still be pushed below an aggregate,
112
- so let the plan decide. Confirm from the
113
- plan (large `Actual Rows` and `Actual Loops` inside the view's nodes), then choose the ids from the
114
- base tables first and read the view by its key, as a correlated `LATERAL` lookup so the page
115
- restriction can reach inside the view. Reach for this only after the plan shows the simple
116
- query builds the whole view, and keep it only if its plan beats the simple query. This works for an aggregate or `GROUP BY` view whose key is
117
- a grouping column; a `LIMIT` in the view blocks pushdown of any qual, so rewrite that view's query
118
- against the base tables instead. A plain join to the page is a join clause, not a restriction
119
- inside the view, so the planner can still build the whole aggregate first.
120
-
121
- ```sql
122
- -- order_summaries aggregates events, so event_count is built for every order, then filtered
123
- SELECT * FROM order_summaries WHERE event_count > 3 ORDER BY id LIMIT 50;
124
- -- choose ids from base tables with an equivalent predicate, then read the view by key
125
- WITH page AS (
126
- SELECT o.id FROM orders o
127
- WHERE (SELECT count(*) FROM events e WHERE e.order_id = o.id) > 3
128
- ORDER BY o.id LIMIT 50
129
- )
130
- SELECT s.id, s.total_cents, s.event_count
131
- FROM page
132
- CROSS JOIN LATERAL (
133
- SELECT * FROM order_summaries WHERE id = page.id
134
- ) s
135
- ORDER BY s.id;
136
- ```
137
-
138
- Filter and sort on indexed base-table columns, and read only the view columns the page needs.
139
- Confirm in the plan that the view's inner nodes run with `Actual Loops` equal to the page size and
140
- read only that page's rows.
141
-
142
- ## Round trips
143
-
144
- Sequential queries can add network round trips when the client waits between statements, and planning
145
- can add latency when PostgreSQL does not reuse a prepared plan; count round trips per request before
146
- tuning individual statements.
147
-
148
- Load a parent and the viewer's relation to it in one query: join the membership row, or use a
149
- lateral subquery, rather than reading the parent and then the relation.
150
-
151
- `Promise.all` over statements on one transaction client is still serial, because one connection
152
- runs one statement at a time. Merge them instead: CTEs, `UNNEST`, or one multi-row statement.
153
-
154
- Write the batch implementation first: it takes an array of keys and returns a keyed map. The
155
- single-item function is a thin wrapper over it (`addUrl(url)` calls `addUrls([url])`), with no
156
- parallel per-item SQL path, for lookups and mutations alike. The batch must give a one-item array the
157
- same atomicity, partial-failure, ordering, duplicate-key, and result-shape semantics as the single
158
- call; if it doesn't, fix the batch rather than keep a per-item path. Call the batch from loops, `.map`
159
- callbacks, and `Promise.all` fan-outs. `no-await-in-loop` misses a helper that queries internally
160
- and `Promise.all(items.map(helper))`; review those call sites by hand.
161
-
162
- Overlap independent cache and PostgreSQL reads with `Promise.all`, such as a rate-limiter check
163
- alongside the user fetch. Serialize only true dependencies, where one result feeds the next call. Suppress the
164
- sequential-await lint only when each step consumes the previous step's result; a shared
165
- transaction client or lock ordering is not a data dependency. A lock that must be taken first
166
- stays a separate, earlier statement; never reorder or parallelize it. Do not keep a lock only
167
- because it exists: one that fails the lock rule in
168
- [schema design](../../postgres-schema-design/SKILL.md) is deleted. Audit every added suppression.
169
-
170
- Correctness comes before round trips. Before folding a statement away, state the guarantee it
171
- gave (what it locked, which snapshot it read) and reject the fold if that weakens. An `EXISTS`
172
- inside a `FOR UPDATE` statement reads a snapshot taken before the lock wait, so it can be stale.
173
-
174
- Run a symmetric check, such as "is either party blocking the other", as one query with an `OR`
175
- or both-direction predicate, not twice with the arguments swapped.
@@ -1,111 +0,0 @@
1
- # Reading plans
2
-
3
- Run `EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT JSON)` at representative cardinality, in a transaction you
4
- roll back when the statement writes. `ANALYZE` executes the statement, and a rollback does not
5
- undo non-transactional effects such as sequence advancement from `nextval()`. Calls that reach
6
- outside the database (requests, messages) still happen even in a disposable database, so use plain
7
- `EXPLAIN` for statements that trigger them, or disable the integrations first. A glance at the top node hides most of the problems below;
8
- walk every node. `VERBOSE` adds each node's `Output` expressions, which is where a select-list
9
- function call shows. In JSON, `Actual Rows`, `Actual Startup Time`, `Actual Total Time`,
10
- `Rows Removed by Filter`, `Rows Removed by Join Filter`, and `Rows Removed by Index Recheck` are
11
- per-loop averages, so multiply each by `Actual Loops` for the total.
12
-
13
- ## Red flags
14
-
15
- ### Rows read per row returned
16
-
17
- A node that reads far more rows than it passes up is doing hidden work. Compare
18
- `Actual Rows` x `Actual Loops` with the rows the parent keeps, and read `Rows Removed by Filter`
19
- `Rows Removed by Join Filter`, and `Rows Removed by Index Recheck` (lossy GiST, BRIN, Bloom, or
20
- bitmap pages; `Actual Rows` is counted after the recheck), each x `Actual Loops`. Millions removed to return tens means the predicate is not an
21
- index condition, the index has the wrong leading columns, or a join filters after it multiplies.
22
- Fix the index or the predicate shape, or filter before joining.
23
-
24
- ### SubPlans whose loops equal the outer row count
25
-
26
- A node with `"Parent Relationship": "SubPlan"` and `Actual Loops` equal to the outer row count
27
- runs once per outer row. Correlated subqueries in the select list or in a `Filter` look like
28
- this. The statements inside a non-inlined function do not appear as SubPlans; see opaque function
29
- calls below. Rewrite as a join, a `LATERAL` with a limit, or a
30
- set-based aggregate computed once. An uncorrelated `InitPlan` runs once, but check its own time, rows, and buffers: one large scan,
31
- sort, or expensive call can still dominate the statement.
32
-
33
- ### `Filter` where an `Index Cond` was expected
34
-
35
- An `Index Cond` narrows the index scan; a `Filter` runs on every row the scan returns. If a
36
- column you expected in `Index Cond` appears in `Filter`, check for a volatile function, a cast or
37
- function wrapping the column, a type or collation mismatch, or a column outside the index's
38
- leading keys. See
39
- [volatile functions in predicates](performance-patterns.md#volatile-functions-in-predicates).
40
-
41
- A partitioned parent whose plan lists every child and shows no `Subplans Removed` may not have
42
- been pruned at plan or executor start. Pruning on an execution-time parameter, such as a value
43
- from the outer side of a nested loop, keeps every child in the plan; check the children's loops,
44
- where children pruned every time show `(never executed)`, and children visited only sometimes
45
- show loops lower than the containing loop count. Constrain the partition key with a constant, a
46
- parameter, or a once-per-statement stable expression; the bound must not be a volatile call.
47
-
48
- ### Opaque function calls
49
-
50
- A plan shows `fn_x(col)` in a `Filter` or output column and nothing about the queries the
51
- function runs. A scalar SQL function whose body contains a subquery, such as `EXISTS`, is never inlined,
52
- so those queries run per row and stay invisible. Count the calls in one transaction:
53
-
54
- ```sql
55
- BEGIN;
56
- SET LOCAL track_functions = 'all'; -- needs superuser or a granted SET privilege
57
- SELECT count(*) FROM orders WHERE fn_is_visible(orders.id);
58
- SELECT funcname, calls FROM pg_stat_xact_user_functions;
59
- ROLLBACK;
60
- ```
61
-
62
- A positive call count proves the function was not inlined. Inlined functions are not counted, but
63
- a missing row is only suggestive: a query that returns no rows or short-circuits the predicate also
64
- never calls the function, so confirm the function body shape before concluding it was inlined.
65
- Tested on
66
- PostgreSQL 18.6: an `EXISTS`-bodied function was counted 90 times for 90 rows, and a
67
- plain-expression function was inlined and not counted. `track_functions = 'pl'` skips
68
- SQL-language functions; use `'all'`. See
69
- [function inlining](performance-patterns.md#function-inlining).
70
-
71
- ### Text join and index conditions
72
-
73
- `Hash Cond`, `Merge Cond`, `Join Filter`, or a join's `Index Cond` comparing `text` or `varchar`
74
- columns (often shown with `::text` casts) means the key is compared under collation and stored in every
75
- referencing row and index. Join on ids and keep the string in a unique column; see
76
- [join on ids](../../postgres-schema-design/references/relations.md#join-on-ids-never-on-text).
77
-
78
- ### Generic plans worse than custom plans
79
-
80
- A prepared statement can switch to a generic plan after several executions, planned without the
81
- parameter values. If a statement is fast in `psql` with literals but slow from the application,
82
- compare `EXPLAIN (GENERIC_PLAN)` for the statement with the plan for a real value. Estimates alone
83
- can hide the problem, and `GENERIC_PLAN` cannot be combined with `ANALYZE`; prepare the statement
84
- and compare `EXPLAIN (ANALYZE, BUFFERS) EXECUTE` for the same skewed value under
85
- `plan_cache_mode = force_generic_plan` and `force_custom_plan`. When the generic plan is much worse, fix the statistics or query shape first; set
86
- `plan_cache_mode = force_custom_plan` for that statement or role only with measured evidence.
87
-
88
- ### Large sequential scans and bad estimates
89
-
90
- A `Seq Scan` over a large table that returns few rows and reads many buffers or removes many rows
91
- by filter is usually a missing or unusable index. A sequential scan on a small table, one that
92
- returns most rows, or one a parent `LIMIT` or `EXISTS` stops early (check the buffers) is fine. Compare `Plan Rows`
93
- with `Actual Rows` on every executed node (`Actual Loops` above zero; a never-executed node has no
94
- observed cardinality) that decides a join (scan inputs and join outputs): an estimate
95
- off by 10x or more can pick the wrong join type or order. Run `ANALYZE`, then consider a higher
96
- statistics target, or extended statistics for correlated columns within one table; extended
97
- statistics do not improve join selectivity, so for a join misestimate look at the join keys'
98
- statistics, the filters feeding the join, or the query shape before changing the query.
99
-
100
- ## Checklist
101
-
102
- 1. Total rows per node versus rows kept; `Rows Removed by ...`.
103
- 2. Any SubPlan with loops equal to the outer rows.
104
- 3. `Filter` that should be `Index Cond`; partition pruning (`Subplans Removed`).
105
- 4. Function calls in `Filter` or output; count them with `pg_stat_xact_user_functions`.
106
- 5. Text keys in join and index conditions.
107
- 6. Generic versus custom plan for prepared statements.
108
- 7. Estimate versus actual on join-deciding nodes.
109
- 8. `Buffers` shared hit plus read totals against the rows returned; the split separates cache
110
- pressure from reads that missed PostgreSQL's shared buffers; use OS or storage metrics
111
- to judge physical I/O, since the OS cache may serve a shared read.
@@ -1,35 +0,0 @@
1
- ---
2
- name: postgres-partitioning-uuid-v7
3
- description: Design PostgreSQL partitions and pruning around UUIDv7.
4
- ---
5
-
6
- # PostgreSQL partitioning with UUIDv7
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/postgres-partitioning-uuid-v7/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- For schema names, references, and canonical table shapes, read
13
- [postgres-schema-design](../postgres-schema-design/SKILL.md).
14
-
15
- Partition only after lifecycle, retention, and query predicates show that it helps.
16
-
17
- - Treat a UUIDv7 as time ordered. Where the meaning matters, keep an explicit business timestamp.
18
- - Align the partition key, primary key, indexes, constraints, and query predicates so partition
19
- pruning is observable.
20
- - Add a parent lower bound to a read of a `RANGE (id)` child table by its parent's UUIDv7 id
21
- (`id >= min_uuidv7(parent time - skew)`) only when both hold: every writer sets the parent column
22
- at insert, to a parent that already exists, and never re-points it to a newer parent; and nothing
23
- mints child ids from a historical time (imports, backfills, seeds). Counterexample: articles
24
- clustered into a story created later are older than their parent, and the bound silently drops
25
- them. See [parent lower bound](references/partition-lifecycle.md#parent-lower-bound).
26
- - A statement that must read every partition declares that, with a reason, on the statement. Do not
27
- use a table-wide exemption: it also silences every future query on that table. See
28
- [cross-partition reads](references/partition-lifecycle.md#declaring-cross-partition-reads).
29
- - Plan creation, retention, migration, and verification as one deployable lifecycle. Include
30
- rollback and independent-reader compatibility.
31
- - Read [partition lifecycle](references/partition-lifecycle.md) before a schema or retention
32
- migration.
33
-
34
- Consumer wrapper owns: partition intervals, migration tooling, retention policy, and deploy
35
- sequencing.
@@ -1,53 +0,0 @@
1
- # Partition lifecycle
2
-
3
- UUIDv7 ordering supports range bounds and index-friendly time windows. Generate bounds from time
4
- instead of extracting timestamps in predicates; use a generated timestamp only when application
5
- semantics require one. Partition on the range key that queries and retention actually constrain.
6
-
7
- Choose a lifecycle. Pre-create future ranges before writes need them, or use on-demand ranges:
8
- `RANGE (id)` with a DEFAULT partition, split into explicit ranges on demand, and a guarded drop
9
- that refuses drops inside the retention window or under legal hold. Move or check rows in the
10
- DEFAULT partition that belong to the range before dropping it. Maintain a default partition
11
- only with an explicit attachment plan. Before attaching a populated range, prove the default partition excludes that range
12
- or move conflicting rows; otherwise attachment can scan and lock the default partition.
13
-
14
- Every primary or unique constraint on a partitioned table must include its partition key. Verify
15
- pruning with predicates on that key, including joins whose other side needs an equivalent range
16
- condition. UUIDv7 values are time ordered, not a promise that independently generated identifiers
17
- have a strict ordering relationship.
18
-
19
- ## Parent lower bound
20
-
21
- A child table partitioned `RANGE (id)` prunes when a reader bounds the child id. A reader that
22
- starts from the parent can derive that bound from the parent's UUIDv7 id, assuming a child is never
23
- older than its parent:
24
-
25
- ```sql
26
- SELECT item.id, item.body
27
- FROM order_items AS item
28
- WHERE item.order_id = $1
29
- AND item.id >= min_uuidv7($2::timestamptz - $3::interval);
30
- ```
31
-
32
- `$2` is the parent's creation time and `$3` the clock skew allowance. The bound is safe only when
33
- both hold:
34
-
35
- - Every writer sets `order_id` at insert, to an order that already exists, and never re-points the
36
- row to a newer order.
37
- - Nothing mints child ids from a historical time: imports, backfills, and seeds.
38
-
39
- Counterexample: `articles` clustered into a `stories` row created later. Each article id is older
40
- than its story id, so `article.id >= min_uuidv7(story time - skew)` silently drops the older
41
- articles. Bound such a read by the child's own window instead.
42
-
43
- ## Declaring cross-partition reads
44
-
45
- A statement that must read every partition says so, with a reason, on the statement itself:
46
-
47
- ```sql
48
- -- cross-partition: nightly integrity check compares order_items totals with orders
49
- SELECT order_id, sum(quantity) FROM order_items GROUP BY order_id;
50
- ```
51
-
52
- Do not exempt the whole table. A table-wide exemption also silences the check for every future
53
- query on that table, including one that forgot its partition key predicate.
@@ -1,31 +0,0 @@
1
- ---
2
- name: postgres-schema-design
3
- description: Design PostgreSQL names, relations, history, work queues, and cursors.
4
- ---
5
-
6
- # PostgreSQL schema design
7
-
8
- Read applicable `AGENTS.md` and the repository's local database adapter when present.
9
- Local policy overrides these portable conventions.
10
-
11
- - Names explain the stored thing; read [naming](references/naming.md) when naming schema objects.
12
- - Columns say their type and FK target; finite sets use enums or lookup tables.
13
- - Joined identities use foreign keys; read [relations](references/relations.md) before modeling references.
14
- - Split differing shapes, share identical values, and keep history documents as JSON.
15
- - Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
16
- - Default to finite retention for everything except user content; see [table shapes](references/table-shapes.md#retention).
17
- - No unnecessary locks. Owner's words: "do we have a rule? no unnecessary locks", "seems like we
18
- have way too many locks for no reason", "keep things simple". Lock (`FOR UPDATE`) only when a
19
- concurrent write would corrupt the rows this transaction writes. Never lock a read set or a
20
- parent row, and never use advisory locks. Caps and "don't remove the last X" guards are best
21
- effort: count up to the cap (`LIMIT cap+1`), then write. Never add counter or projection tables,
22
- slot tables, claim tables, or constraints that exist only to make a cap exact. Remove a lock by
23
- deleting it, not by swapping in another serializer.
24
- - Reuse parameterized trigger functions instead of copying bodies.
25
- - Comment every table, column, and view; document reviewed exceptions explicitly.
26
-
27
- For query shape, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
28
- For partition lifecycle, use [UUIDv7 partitioning](../postgres-partitioning-uuid-v7/SKILL.md).
29
- For how jobs choose, cap, and resume over work-item and cursor tables, read
30
- [bounded iteration](../bounded-iteration/SKILL.md).
31
- Consumer policy owns lifecycle, retention, migration strategy, and enforcement configuration.