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.2 KiB
name, description, when_to_use, tags
| name | description | when_to_use | tags | ||
|---|---|---|---|---|---|
| request-lifecycle-tracing | Following one request from entry to storage and back, so a change can be reasoned about across layers. | You need to understand how a specific operation works, or where to make a change that crosses layers. |
|
One request, every layer, in order
Tracing a single path end to end is the fastest way to learn a system, and the only reliable way to know where a cross-cutting change must land.
The trace
route registration which handler, which method, what middleware
extractors / auth what must be true before the handler body runs
handler validation, then the call into real logic
domain / service the actual decision
persistence the query, the transaction boundary
response what is serialised, what is deliberately omitted
side effects events, jobs, background work
The last line is the one most often missed and the most likely to break: an operation that also enqueues a job, writes an event or invalidates a cache has consequences the response does not mention.
Follow the data, not the call stack
Call stacks show structure; data flow shows behaviour. For each step ask what changed shape and what was dropped. A field silently discarded between the handler and the query is a bug that no test asserting the response will catch.
Find the transaction boundary explicitly
Where does the transaction begin and commit? Anything outside it is not atomic with the write, and that is where "the row exists but the event never fired" comes from. Note it during the trace — reconstructing it later, mid-incident, is much harder.
Note what happens on failure
Walk it a second time asking what happens when each step fails. Errors that are logged and swallowed are where silent failures live: the operation reports success while a step did nothing. If a step's failure produces no observable signal, that is a finding, not a detail.
Record the trace with file:line
The output is a short document with a line per layer and the file and line for each. That is what makes the next change — or the next incident — cheap, and it is checkable by whoever reads it next.