Skip to content

shift-editor/shift / .agents/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 isPut it inEffect
Decidable in one TypeScript file, from syntaxa rule in scripts/oxlint/shift-plugin.mjs, enabled in .oxlintrc.jsonblocks in pnpm lint:check and CI
Covered by an existing clippy lint[workspace.lints.clippy] in Cargo.tomlblocks in clippy and CI
Covered by a clippy lint with too many hits to fix nowa key in clippy-ratchet.jsonblocks 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.mjspnpm scan:ts reports
Rust structure clippy can't see (free functions, shared shapes, chains)a Kind in crates/shift-scanratcheted 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.messages saying what to write instead, create(context) returning node visitors). Add describe cases to scripts/oxlint/shift-plugin.test.mjs for a flagged line and an unflagged look-alike; run pnpm test:lint-rules.

  • scan-ts kind: add it to KINDS, check it in FileScan#check (or across files in TsScan#findings), add a test in scripts/scan/scan-ts.test.mjs; run pnpm test:scan.

  • shift-scan kind: add a Kind variant (doc comment, as_str, ALL, scope), report it from the module its theme lives in (see crates/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 baseline
    

    The kinds today:

    • method-candidate — a free function whose first argument is a type of the same crate
    • trait-candidate — the same public method name and arity on three or more types
    • long-chain — a method chain of six or more steps that walks a collection
    • repeated-error-mapping — one error built by ok_or_else/map_err three or more times in a file
    • field-copy-conversion — a From/TryFrom literal copying four or more fields off its parameter
    • duplicate-body — a function body alike one elsewhere: the same tokens or the same arithmetic
    • collect-turbofish — collect::<Vec<_>>() where the field, argument or return type fixes it
    • duplicate-type — a struct or enum whose field or variant names match another's, or 80% of the larger
    • type-name-collision — a struct or enum name declared more than once in the workspace
    • get-prefix — a public get_* function (not get_mut, get_or_*, get_index)
    • iter-suffix — a public *_iter function
    • ctor-with-prefix — an associated with_* function without self (not with_id, with_capacity)
    • id-param-name — a FooId parameter named foo
    • generic-suffix — a type named *Data, *Info or *State
    • stringly-error — Result<_, String>, an error variant with a message field, an error variant built from format! or error.to_string(), or .map_err to text
    • inline-not-found — a *Error::*NotFound or MissingEntity built outside a require_*/or_* helper
    • tuple-return — a function returning a tuple, bare or in Result/Option
    • panicking-conversion — an impl From, Default, Display, Index or other infallible trait that can panic
    • napi-without-catch-unwind — an exported #[napi] function without catch_unwind
    • parallel-first-error — a parallel iterator collected into a Result, or try_for_each on one
    • leaked-static — Box::leak, String::leak or .leak()
    • unguarded-recursion — a function calling itself with no depth, budget, visited set or cycle check in sight
    • owned-id-accessor — an id accessor that clones the id it returns
    • linear-lookup — find/position comparing an id or name
    • large-inline-tests — an inline test module over 300 lines
    • crate-header — a crate root with no //! header
    • test-calls-private — a unit test calling a non-pub function its own test module doesn't define
    • test-only-pub — a public function only test code names (napi, WebAssembly and test_support exempt)
    • long-test — a test body over 40 lines
    • near-duplicate-tests — a test with at least 85% of its token pairs in common with another in its file
    • repeated-test-helper — a test helper defined in two or more test files by name, or with an alike body
    • weak-error-assert — assert!(r.is_err()), or an error's to_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.

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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
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: 192kUpdated Claude CodeCodexVerifiedInstall