bkinsey808/lint-first-authoring

Requires: file-read, terminal (linting/testing). No network access needed.

Full reference: /docs/lint-best-practices.md

Use when

• Writing new code in this repo.
• Refactoring existing code with minimal drift.
• Prompting an agent to avoid predictable lint failures on first pass.

Do not use when

• The primary task is resolving existing lint, ESLint, oxlint, or TypeScript errors.
• The task is docs-only or otherwise unrelated to code authoring.

Preconditions

• Read AGENTS.md and docs/ai/rules.md.
• Read the file being changed and at least one nearby file that already follows the local pattern.
• Load the most relevant companion skill for the area being edited.

Execution workflow

1. Read /docs/lint-best-practices.md and apply the relevant sections before editing.
2. Match the surrounding file’s structure, naming, and import style.
3. Keep the change minimal and local to the requested behavior.
4. Reuse existing helpers and established patterns instead of inventing new ones.
5. Run npm run lint after meaningful changes and fix any issues before finishing.

Validation note:

• npm run lint is the repo-standard lint command.
• Most project linting comes from oxlint; do not swap in npx eslint unless a specialized check explicitly requires it.

Defaults

• No any; use unknown plus guards or schema validation.
• No barrel files; import directly from source files.
• Use import type when appropriate.
• Prefer explicit return types.
• Add a comment directly above every useEffect.
• Do not add lint-disable comments in test files.
• Do not add manual memoization unless the task explicitly requires it and surrounding code already supports it.

Prompt Template

Use this prompt when the user wants an agent to write lint-clean code:

Read AGENTS.md, docs/ai/rules.md, and docs/lint-best-practices.md first.
Match surrounding patterns exactly.
No any, no barrel files, no test-file lint disables, and no unnecessary memoization.
Use explicit types, safe validation, direct imports, and useEffect comments.
Run npm run lint after editing and fix any issues before finishing.

Companion skills

• TypeScript files: typescript-best-practices
• React components/hooks: react-best-practices
• Existing lint failures: lint-error-resolution
• Unit tests: unit-test-best-practices
• Hook tests: unit-test-hook-best-practices

Output format

• Apply the code change directly.
• Report which repo-specific rules were applied.
• Report whether npm run lint was run and whether it passed.

Evaluations (I/O examples)

Input: "Add a new React hook and keep it lint-safe." Expected: Reads the target file and nearby patterns, loads react-best-practices, writes the hook without any or manual memoization, adds any required useEffect comments, runs npm run lint, and reports the validation result.

Input: "Generate a new API helper that should pass lint on first try." Expected: Reads nearby API helpers, avoids unsafe assertions, prefers schema validation or guards, uses direct imports, runs npm run lint, and reports what was checked.