feature-lint

name	feature-lint
description	Resolve residual Biome lint findings on a feature branch's changed files — the rules `biome check --write` can't safely auto-fix. Invoked by /feature-qc as its final pass; also runnable standalone on a branch (/feature-lint). NOT for a one-off lint of a single file — run `pnpm lint:fix` directly for that.
argument-hint	[base ref, default main]
allowed-tools	Bash(git *) Bash(pnpm *)
model	inherit

Lint resolve — clear the residual, safely

biome check --write already auto-handles formatting, import order, and every lint rule with a safe fix in one pass. What's left is the residual: rules with no fix (most next rules, e.g. noImgElement) or an unsafe fix (react/useExhaustiveDependencies). Those need a human-style edit. This skill clears that residual on the feature's changed files without bloating the main conversation — it fans the fixes out to isolated sub-agents and returns only a compact report.

Correctness is the constraint

Correctness is priority one. The only automated safety net here is pnpm build (TypeScript + Next compile) — there is no test runner and browser checks are out. A fix that compiles can still change behavior. That single fact drives the design: fixes are risk-tiered, and the dangerous tier is escalated to a higher-effort pass and flagged for review rather than shipped silently.

Sequence

1. Scope to the feature diff. Base defaults to main (or $ARGUMENTS). Exclude deletions so Biome isn't handed missing paths:

   base="${ARGUMENTS:-main}"
   files=$(git diff --name-only --diff-filter=ACMR "$base...HEAD" \
     -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.mjs' '*.cjs')
   

   Empty → nothing to do; stop.

2. Auto-pass — format + safe fixes over those files only:

   echo "$files" | xargs pnpm exec biome check --write --no-errors-on-unmatched
   

3. Extract the residual as JSON (write to the session scratch dir, not the repo):

   echo "$files" | xargs pnpm exec biome lint --reporter=json --no-errors-on-unmatched > <scratch>/residual.json
   

   Parse it into { file → [findings] }. Each finding carries a rule id (e.g. lint/correctness/useExhaustiveDependencies), a location, and a message.

4. Risk-tier every finding by what its fix can break — tier by category, not a frozen rule list, so new rules slot in by principle:

   • High — behavior-changing. The fix alters runtime semantics: effect/callback timing, re-render behavior, control flow. Anchor case react/useExhaustiveDependencies (editing a hook's dependency array changes when it fires — or loops). pnpm build cannot catch a regression here.
   • Low/medium — mechanical or layout. Adding an a11y attribute, a list key, or swapping <img>→next/image (needs real width/height; can shift layout, but the failure is visible/compile-checked, not silent).

5. Inline vs. fan-out. If the residual is tiny (≈≤3 findings across ≤2 files), just fix it inline — dispatch overhead isn't worth it. Otherwise partition by file (each file is owned by exactly one sub-agent — never two agents in the same file) and dispatch in parallel:

   • Every tier → lint-fixer, many in parallel. The one agent handles both kinds: mechanical fixes directly, behavior-changing fixes with care and a ⚠ REVIEW flag. Give each sub-agent only its file(s), that file's findings, and each finding's risk tier. The agent definition already carries the rules (no --unsafe, stay in-assignment, don't build); don't restate them — just pass the work.

6. Normalize + gate. After the sub-agents converge:

   echo "$files" | xargs pnpm exec biome check --write --no-errors-on-unmatched   # format their edits
   pnpm build                                                                       # the only authority
   

   A clean pnpm build is the completion gate. If it fails, the error names the file — fix and re-run build.

7. Report. Return a compact summary: findings resolved per file, anything still unresolved, and a prominent ⚠ Review these section collecting every high-tier behavior-changing fix the careful lane flagged. Surface that section to the user — those are the changes pnpm build can't vouch for.

Notes

• Scope is changed files only — never fix pre-existing findings in untouched code. That's scope creep; surface them to the user instead of fixing them here.
• This is the single place Biome and pnpm build run in the feature workflow.