Omar SobhandClaude Opus 5
4358964c05
55 of 85 role skill bindings pointed at skills that were never authored,
so 10 of 11 team templates bound a smaller context bundle than their role
prompts assumed. Three roles bound nothing at all (gpu.bench_engineer,
threejs.shader_author, threejs.perf_engineer) while their prompts described
procedures they had no way to read.
The loader comment at team_template_loader.rs:167 already diagnosed this —
snake_case slugs in TOML against kebab-case skill files — and it was
half-fixed: the kebab names were corrected, the snake_case ones left.
It was invisible because both existing tests assert authored ⊆ referenced
(30/30, green) and the second explicitly declines to check the other
direction. So the failing half was the half nobody asserted.
Resolved every name by one of three explicit choices:
- 23 skills authored where the role genuinely needed the procedure
(gpu, threejs, research, analysis, frontend, mobile, backend, platform)
- renames onto authored skills where one existed in substance, including
the four-near-duplicate cases that collapse onto one real skill
- 22 aspirational references deleted — a binding an agent cannot read is
a promise, not a capability
Two tests now hold it. The unit test checks referenced ⊆ authored against
the files. The new integration test runs both loaders in boot order and
asserts the bindings survive the trip through the database, which is a
different question: resolution goes through skills_catalog rows, so a skill
file that exists but fails to ingest still leaves the role empty.
Negative controls: the unit test failed naming all 55; the integration test
fails naming the exact role when one name is reverted.
threejs.shader_author and .perf_engineer gained a second and third skill
after the collapse — pin_in_context pins idx < 2, so a role left with one
skill silently pins less than the policy intends.
Co-Authored-By: Claude Opus 5 <[email protected]>
62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
---
|
|
name: postgres-explain-analyze
|
|
description: Reading an EXPLAIN ANALYZE plan to find why a query is slow, rather than adding indexes hopefully.
|
|
when_to_use: A query is slow, or you want to confirm an index is actually used.
|
|
tags: [backend, postgres]
|
|
---
|
|
|
|
# Read the plan; do not guess at indexes
|
|
|
|
An index added without a plan is as likely to be unused as to help, and each one
|
|
costs write throughput forever.
|
|
|
|
## Always ANALYZE, and usually BUFFERS
|
|
|
|
```sql
|
|
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
|
|
```
|
|
|
|
`EXPLAIN` alone shows the planner's *estimate*. `ANALYZE` executes and shows
|
|
what happened, which is the only thing worth reading. `BUFFERS` shows whether
|
|
the data came from cache or disk — a "slow" query that is entirely
|
|
`shared read` is an I/O problem, not a plan problem.
|
|
|
|
Note that `ANALYZE` actually runs the statement. Wrap a mutation in a
|
|
transaction you roll back.
|
|
|
|
## Read it inside out, and look for two things
|
|
|
|
Plans nest; the innermost node runs first. Scan for:
|
|
|
|
1. **The largest `actual time`,** not the largest estimate. That is where the
|
|
time went.
|
|
2. **Estimate versus actual rows.** `rows=10` with `actual rows=48000` is the
|
|
planner being wrong, and a wrong estimate is usually the *cause* of a bad
|
|
plan — it picked a nested loop because it expected ten rows. Fix the
|
|
statistics (`ANALYZE <table>`, or raise the statistics target) before touching
|
|
the query.
|
|
|
|
## What the node types tell you
|
|
|
|
- **Seq Scan** on a large table with a selective filter → a missing index, or a
|
|
filter the index cannot serve (a function on the column, a leading wildcard).
|
|
- **Nested Loop** with a large outer side → usually the wrong-estimate problem
|
|
above; correct rows would have produced a hash join.
|
|
- **Sort** with `Sort Method: external merge Disk` → `work_mem` too small, or an
|
|
index could provide the order for free.
|
|
- **Bitmap Heap Scan** with high `Rows Removed by Filter` → the index found
|
|
candidates the table had to reject; consider a composite or partial index.
|
|
|
|
## Confirm the index is used, not just present
|
|
|
|
After adding one, re-run the plan. An index that does not appear is dead weight:
|
|
it slows every write and helps nothing. Common causes are a type mismatch, a
|
|
function on the column, or a column order that does not match the predicate —
|
|
see `postgres-index-selection`.
|
|
|
|
## Test against realistic data volume
|
|
|
|
Plans change with size. Every plan is a Seq Scan on a thousand rows, and the
|
|
planner is right to choose it. Validate on production-shaped data or the
|
|
exercise is theatre.
|