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]>
2.5 KiB
name, description, when_to_use, tags
| name | description | when_to_use | tags | ||
|---|---|---|---|---|---|
| postgres-explain-analyze | Reading an EXPLAIN ANALYZE plan to find why a query is slow, rather than adding indexes hopefully. | A query is slow, or you want to confirm an index is actually used. |
|
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
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:
- The largest
actual time, not the largest estimate. That is where the time went. - Estimate versus actual rows.
rows=10withactual rows=48000is 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_memtoo 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.