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]>
54 lines
2.2 KiB
Markdown
54 lines
2.2 KiB
Markdown
---
|
|
name: request-lifecycle-tracing
|
|
description: Following one request from entry to storage and back, so a change can be reasoned about across layers.
|
|
when_to_use: You need to understand how a specific operation works, or where to make a change that crosses layers.
|
|
tags: [analysis, codebase]
|
|
---
|
|
|
|
# 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.
|