shift-editor/shift / .claude/skills/add-lint
add-lint
Verified/add-lint — Catch a pattern once, not in every review
Every pattern the user has to point out twice should be found by a tool after that. A rule that blocks is better than a report; a report is better than a reviewer remembering.
1. Pin the pattern down
Write a before/after for the pattern from real code (file:line), and one case that looks similar
but is fine. Show it with show_code and agree it with the user before writing the check: a rule
that flags the wrong thing teaches everyone to ignore it.
2. Pick where it lives
| The pattern is | Put it in | Effect |
|---|---|---|
| Decidable in one TypeScript file, from syntax | a rule in scripts/oxlint/shift-plugin.mjs, enabled in .oxlintrc.json | blocks in pnpm lint:check and CI |
| Covered by an existing clippy lint | [workspace.lints.clippy] in Cargo.toml | blocks in clippy and CI |
| Covered by a clippy lint with too many hits to fix now | a key in clippy-ratchet.json | blocks new hits per crate in CI |
Covered by an oxlint built-in or a plugin rule (@shadcn/lint for the design system) | .oxlintrc.json (the root, or a package's for its own rules) | blocks |
| Needs other files, types, or a reviewer's judgement (TypeScript) | a kind in scripts/scan/scan-ts.mjs | pnpm scan:ts reports |
| Rust structure clippy can't see (free functions, shared shapes, chains) | a Kind in crates/shift-scan | ratcheted by pnpm scan:rust --check in CI |
Prefer the first row that fits. A scanner kind is right when some hits are correct code (a free
numeric helper, a cache that really is a cache), so it can't block outright. Its count per crate is
held to crates/shift-scan/baseline.json instead: CI fails when a count rises (listing the new
hits) or falls without pnpm scan:rust --update.
3. Count before enabling
Run the new check over the tree first (pnpm lint:check, pnpm scan:ts --kind <kind>,
pnpm scan:rust --kind <kind>) and report the count with a few real hits.
- 0 hits: enable it as an error and stop.
- A handful: fix them in the same branch, one commit for the rule and one for the fixes.
- Many: ask. Usually the rule lands with its fixes in batches by area; never land a rule with a blanket disable. A disable comment on one line says why that line is the exception.
lint:check runs with --deny-warnings, so a "warn" rule blocks as well as "error".
A clippy lint with many hits is ratcheted rather than enabled: add "<lint>": {} to
clippy-ratchet.json and run pnpm lint:rust-ratchet --update, which records today's hits per
crate. CI then fails when any count changes; each fix lowers the file, and at 0 the lint moves to
Cargo.toml.
4. Write it like the existing ones
-
oxlint rule: copy the shape of a nearby rule in
shift-plugin.mjs(meta.messagessaying what to write instead,create(context)returning node visitors). Adddescribecases toscripts/oxlint/shift-plugin.test.mjsfor a flagged line and an unflagged look-alike; runpnpm test:lint-rules. -
scan-ts kind: add it to
KINDS, check it inFileScan#check(or across files inTsScan#findings), add a test inscripts/scan/scan-ts.test.mjs; runpnpm test:scan. -
shift-scan kind: add a
Kindvariant (doc comment,as_str,ALL,scope), report it from the module its theme lives in (seecrates/shift-scan/docs/DOCS.md), and add a test there. Add its line below and its row in the DOCS.md table. Then run:cargo test -p shift-scan cargo clippy -p shift-scan --all-targets -- -D warnings cargo fmt -p shift-scan pnpm scan:rust --update # record its count in the baselineThe kinds today:
method-candidate— a free function whose first argument is a type of the same cratetrait-candidate— the same public method name and arity on three or more typeslong-chain— a method chain of six or more steps that walks a collectionrepeated-error-mapping— one error built byok_or_else/map_errthree or more times in a filefield-copy-conversion— aFrom/TryFromliteral copying four or more fields off its parameterduplicate-body— a function body alike one elsewhere: the same tokens or the same arithmeticcollect-turbofish—collect::<Vec<_>>()where the field, argument or return type fixes itduplicate-type— a struct or enum whose field or variant names match another's, or 80% of the largertype-name-collision— a struct or enum name declared more than once in the workspaceget-prefix— a publicget_*function (notget_mut,get_or_*,get_index)iter-suffix— a public*_iterfunctionctor-with-prefix— an associatedwith_*function withoutself(notwith_id,with_capacity)id-param-name— aFooIdparameter namedfoogeneric-suffix— a type named*Data,*Infoor*Statestringly-error—Result<_, String>, an error variant with amessagefield, an error variant built fromformat!orerror.to_string(), or.map_errto textinline-not-found— a*Error::*NotFoundorMissingEntitybuilt outside arequire_*/or_*helpertuple-return— a function returning a tuple, bare or inResult/Optionpanicking-conversion— animpl From,Default,Display,Indexor other infallible trait that can panicnapi-without-catch-unwind— an exported#[napi]function withoutcatch_unwindparallel-first-error— a parallel iterator collected into aResult, ortry_for_eachon oneleaked-static—Box::leak,String::leakor.leak()unguarded-recursion— a function calling itself with no depth, budget, visited set or cycle check in sightowned-id-accessor— an id accessor that clones the id it returnslinear-lookup—find/positioncomparing an id or namelarge-inline-tests— an inline test module over 300 linescrate-header— a crate root with no//!headertest-calls-private— a unit test calling a non-pubfunction its own test module doesn't definetest-only-pub— a public function only test code names (napi, WebAssembly andtest_supportexempt)long-test— a test body over 40 linesnear-duplicate-tests— a test with at least 85% of its token pairs in common with another in its filerepeated-test-helper— a test helper defined in two or more test files by name, or with an alike bodyweak-error-assert—assert!(r.is_err()), or an error'sto_string().contains(..)test-setup-copy— a test opening with the same two statements as four or more others in its crate
5. Write the rule down where it's read
Add or update the rule's line in the skill that owns it (typescript, rust, signals,
writing-tests, ui, jsdoc) and end it with "Enforced by shift/<rule>" or "Reported by
pnpm scan:ts --kind <kind>". AGENTS.md's anti-slop list holds only rules no tool checks;
remove a rule from it once a check covers it.
Running the scanners on a branch
Before review, report only what the branch touches:
pnpm scan:ts --since origin/main
pnpm scan:rust --since origin/main
Treat each finding as a question, not a failure: say for each whether to fix it in the branch, leave it (and why), or turn it into a rule.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |