Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.
TypeScript ai-sdkclaude-codeclicode-searchcodexcoding-agentscontext-retrievaldeveloper-toolsjevsemantic-searchtypescriptvercel-ai-gateway
skills(refactor-clean): sweep names in every touched path
David Zhanga41ac692e37a
diff --git a/.agents/skills/refactor-clean/SKILL.md b/.agents/skills/refactor-clean/SKILL.mdindex 8d06956..be6fc70 100644--- a/.agents/skills/refactor-clean/SKILL.md+++ b/.agents/skills/refactor-clean/SKILL.md@@ -1,6 +1,6 @@---name: refactor-clean-description: Refactor cleanly instead of layering sediment. Use when a change reveals duplicated concepts, local adapters, obsolete owners, redundant inputs or guards, compatibility wrappers, parallel abstractions, an over-large module that has accreted many responsibilities, or "just tack this on" pressure in any code area.+description: Refactor cleanly instead of layering sediment. Use for rename requests, stale or misleading names, changed scope, or when a change reveals duplicated concepts, local adapters, obsolete owners, redundant inputs or guards, compatibility wrappers, parallel abstractions, an over-large module that has accreted many responsibilities, or "just tack this on" pressure in any code area.---# Clean Refactoring@@ -13,28 +13,33 @@ module into the several owners it was hiding.## Workflow-1. Name the concept that lacks one clear owner — duplicated across several owners,+1. Sweep names in every touched path, even when no structural refactor is needed.+ Ask whether each name describes the concept's current scope. Rename misleading+ files, symbols, imported bindings and shared exports immediately; update every+ consumer, test, doc and agent instruction in the same pass. Keep scenario names+ only for scenario-specific code, then search again for stale references.+2. Name the concept that lacks one clear owner — duplicated across several owners,or several concepts fused into one over-loaded module. Identify the thing(s)that should each have one owner: environment, pricing rule, geometry source,state machine, data contract, renderer phase, API shape, UI state, or testoracle.-2. Find every current owner and consumer. Treat wrappers, aliases, pass-local+3. Find every current owner and consumer. Treat wrappers, aliases, pass-localconstants, copied structs, and "temporary" branches as sediment until provenotherwise.-3. Run a deletion pass before relaxing checks or making inputs optional. For each+4. Run a deletion pass before relaxing checks or making inputs optional. For eachinput, flag, guard, fallback, and adapter in the affected path, ask what requiredbehavior breaks if it disappears. Trace its writers, transport, readers,validators, and consumers; compare them with the authoritative owner. Making aredundant input optional is not completion. If removing it preserves requiredbehavior, delete the mechanism and its call-site, test, and documentation residue.-4. Promote any remaining concept to its natural home. Pick the module that would+5. Promote any remaining concept to its natural home. Pick the module that wouldown it from scratch, then make old call sites consume that owner directly.Delete or collapse the stale path in the same pass.-5. Retain compatibility only for an identified consumer and a concrete behavior+6. Retain compatibility only for an identified consumer and a concrete behaviorthat removal would break. Old inputs that can safely be ignored need no parser,validator, or adapter just because they may still arrive. If a bridge is needed,keep it tiny and give it a removal condition; hypothetical callers do not count.-6. Verify behavior through consumers, including affected failure and retry paths.+7. Verify behavior through consumers, including affected failure and retry paths.Search again for the removed mechanism across code, tests, docs, and agentinstructions. Finish only when each retained mechanism in the affected pathhas a named consumer and behavior it preserves; report retained bridges and@@ -131,6 +136,12 @@ module into the several owners it was hiding.not in identifiers. The same rule kills lineage comments ("previously thiswas...", "moved from X") — they describe the diff, not the code, and rot themoment the referent disappears.+ Renaming is routine maintenance, not a separate project or a reason to ask for+ permission. Do it proactively at whatever scale the consumers require; a large+ mechanical diff is not a reason to retain a misleading name. Distinguish internal+ identifiers from persisted keys and external contracts: retain the latter only+ for an identified consumer, under the compatibility rule above. Do not leave+ internal aliases that preserve the old vocabulary.- **Prefer the idempotent contract over the refusal.** When an operation can beasked for twice — a retry after a lost response, a user clicking the samebutton again, a replayed webhook — reaching the requested end state should