Skip to content

shift-editor/shift / .agents/skills/add-lint

add-lint

Verified

FileKindSize
SKILL.mdskill md8.7 KB
---
name: add-lint
description: Turn a code pattern the user doesn't want into a check that finds it without them — an oxlint rule in `scripts/oxlint/shift-plugin.mjs`, a workspace clippy lint, or a report in `shift-scan` (Rust) or `scan-ts` (TypeScript) — and clean up what it finds. Use when the user says "I don't like X", "we keep doing X", "add a lint/rule/check for X", "make this a rule", "scan for X", "can we catch this automatically", or when the same review comment comes up a second time. Also use to run the scanners on a branch before review or before opening a pull request, and to count where a code pattern occurs across the tree (how many tests reach an internal, how many files do X) instead of grepping: extend a scanner kind or rule and report its hits.
---

# /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.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:

  ```bash
  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:

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