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.1 KiB
Markdown
54 lines
2.1 KiB
Markdown
---
|
|
name: ast-grep-repo-index
|
|
description: Building a structural map of an unfamiliar repository — entry points, module boundaries, and where the real logic lives.
|
|
when_to_use: You are mapping a codebase you did not write, before changing anything in it.
|
|
tags: [analysis, codebase]
|
|
---
|
|
|
|
# Map the shape before reading the code
|
|
|
|
An unfamiliar repository is mostly scaffolding. The goal of a first pass is to
|
|
find the small fraction that matters and ignore the rest deliberately.
|
|
|
|
## Start at the edges, not the top
|
|
|
|
```bash
|
|
rg -l 'fn main\(|async fn main' --type rust # entry points
|
|
rg -n 'route\(|\.get\(|\.post\(' | head -50 # HTTP surface
|
|
ls migrations/ | tail -20 # what the data recently grew
|
|
```
|
|
|
|
Entry points, the request surface and the schema tell you what the system *does*
|
|
in about ten minutes. Reading `lib.rs` top-down tells you how it is organised,
|
|
which is a different and less useful question early on.
|
|
|
|
## Size is a signal
|
|
|
|
```bash
|
|
find . -name '*.rs' -not -path './target/*' | xargs wc -l | sort -rn | head -20
|
|
```
|
|
|
|
The largest files are either the core logic or an accumulation nobody split.
|
|
Both are worth knowing before you touch anything nearby.
|
|
|
|
## Structural search beats text search for call graphs
|
|
|
|
Text grep for a function name matches its definition, its calls, its doc
|
|
comments and any string containing it. When you need call sites specifically,
|
|
search the shape — `ast-grep --pattern 'foo($$$)'` — or at minimum anchor the
|
|
text: `rg '\bfoo\('.
|
|
|
|
## Follow one request end to end
|
|
|
|
The single most valuable early exercise: pick one endpoint and trace it from
|
|
route registration to database and back. It crosses every layer the codebase
|
|
has, in the order the codebase thinks about them, and it tells you more than any
|
|
architecture document. See `request-lifecycle-tracing`.
|
|
|
|
## Write down the map
|
|
|
|
A map that lives only in your head has to be rebuilt by the next person. Record
|
|
entry points, the three or four modules with the real logic, and — most
|
|
valuable — what you *expected* to find and did not. The gaps between a reasonable
|
|
mental model and the actual structure are where future bugs live.
|