Problem
## Verb-led function names in packages/agents/content/skills/_data/naming-conventions.md requires a transitive verb but gives no basis for choosing one. Its common-verbs list -- build, create, compute, fetch, find, get, load, parse, resolve, validate -- is flat, so get reads as a peer of the rest rather than as a fallback. A codebase following the rule as written can still name an array-returning function, a Set-returning one, a single-or-undefined one, a formatted-string one, and a scalar retrieval all get*, which is what williamthorsen/toolbelt#100 found across six packages.
Proposed solution
Add a return-kind rule to ## Verb-led function names, so the verb is chosen by what the function returns and what it does rather than picked from an unranked list.
| Returns |
Name |
| one or none |
find* |
| an array |
list* |
| any other container |
the most specific accurate verb, with the container named in the tail (*Set) |
| a scalar or a record |
the most specific accurate verb |
get* is the fallback for when no more specific verb is accurate, not the default.
The container-in-the-tail clause is the existing ## Kind in the tail rule applied to a return value, so the two sections agree rather than compete.
Placement is naming-conventions.md, not a new rulebook: williamthorsen-code-layout-preferences already delegates identifier naming there, and get's mis-ranking is in that file's own list. Should the convention be judged personal rather than shared, it belongs in that rulebook instead, with the shared file keeping only the demotion of get.
Acceptance criteria
Must have
Problem
## Verb-led function namesinpackages/agents/content/skills/_data/naming-conventions.mdrequires a transitive verb but gives no basis for choosing one. Its common-verbs list --build,create,compute,fetch,find,get,load,parse,resolve,validate-- is flat, sogetreads as a peer of the rest rather than as a fallback. A codebase following the rule as written can still name an array-returning function, a Set-returning one, a single-or-undefined one, a formatted-string one, and a scalar retrieval allget*, which is what williamthorsen/toolbelt#100 found across six packages.Proposed solution
Add a return-kind rule to
## Verb-led function names, so the verb is chosen by what the function returns and what it does rather than picked from an unranked list.find*list**Set)get*is the fallback for when no more specific verb is accurate, not the default.The container-in-the-tail clause is the existing
## Kind in the tailrule applied to a return value, so the two sections agree rather than compete.Placement is
naming-conventions.md, not a new rulebook:williamthorsen-code-layout-preferencesalready delegates identifier naming there, andget's mis-ranking is in that file's own list. Should the convention be judged personal rather than shared, it belongs in that rulebook instead, with the shared file keeping only the demotion ofget.Acceptance criteria
Must have
getis described as the fallback rather than listed as a peer verb.## Kind in the tailare consistent about naming a returned container.