Skip to content

Commit 7d28ce9

Browse files
authored
docs: exempt tool directives from the comment rules (#2183)
1 parent 15d5a45 commit 7d28ce9

2 files changed

Lines changed: 3 additions & 1 deletion

File tree

AGENTS.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,8 @@ Comments are **not**:
338338

339339
Never reference issues, PRs, or review threads in comments -- they're stale narrative the moment the change merges; that context belongs in the commit message and PR description. Never number comments.
340340

341+
Tool directives are exempt from all of the above: `eslint-disable`, `oxlint-disable`, `@ts-expect-error`, `@ts-ignore`, `prettier-ignore`, `v8 ignore`, and similar are machine instructions, not prose, and the short reason attached to one (`// oxlint-disable-next-line no-await-in-loop -- sequential on purpose`) states why the rule doesn't apply at that site. Keep the reason; don't flag it as justification.
342+
341343
## Imports
342344

343345
- **Internal imports** use `.js` extensions (ESM): `import { X } from "../foo.js"`.

infra/flue-review/.flue/skills/review/SKILL.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ Breadth first, depth second. The two most common ways to fail are to grade the i
5656
- **Resources**: leaked handles/timers/listeners, unbounded growth, missing timeouts, retry without backoff.
5757
- **Tests**: a fix without a reproducing test is not fixed; a mock that returns the thing the test claims to verify is false confidence. A test that cannot fail on a real regression -- a config literal asserted back at itself, an implementation detail asserted straight back (adding a CSS class and testing the class is present), a mocked unit under test, a test exercising only third-party code -- is worse than no test: it inflates coverage and pins intentional changes. Flag it for deletion, or for rewriting against observable behavior.
5858
- **Logged-out query counts**: any new query on a route an anonymous visitor can hit -- including cold-start or first-request-only queries -- needs a _really_ good reason. Check whether it could piggyback on an existing query, batch, defer with `after()`, or use `requestCached`. A query-count snapshot diff that increases a logged-out route is a finding, not bookkeeping.
59-
- **Comments**: comments that restate what the code does, justify the decision ("intentionally", "for safety"), address the reviewer, narrate rejected alternatives, or reference issues/PRs/review threads. Comments are evergreen and for future readers of the code; almost all of these should be deleted (or the code made clearer instead). Numbered comments are always wrong.
59+
- **Comments**: comments that restate what the code does, justify the decision ("intentionally", "for safety"), address the reviewer, narrate rejected alternatives, or reference issues/PRs/review threads. Comments are evergreen and for future readers of the code; almost all of these should be deleted (or the code made clearer instead). Numbered comments are always wrong. Tool directives are exempt: `eslint-disable`, `oxlint-disable`, `@ts-expect-error`, `@ts-ignore`, `prettier-ignore`, `v8 ignore`, and similar are machine instructions, and the short reason attached to one is required context, not justification -- never flag them under this category.
6060
- **AGENTS.md conventions** (see above).
6161

6262
## Severity and verdict

0 commit comments

Comments
 (0)