commitlint error broke the review when agent attempted to lint commit messages

TL;DR

Rewrite the message in conventional format: a type, optional scope, then a short subject, like fix(review): handle empty diff. Run commitlint on the message locally before amending. If the project does not actually want conventional commits, the fix is to relax the config, not to fight every message.

Verbatim error

commitlint error broke the review when agent attempted to lint commit messages

Steps

1. See the exact complaint: npx commitlint --print-config shows the active rules, and piping the message through it shows the failure, for example echo "fix bug" | npx commitlint --edit. Expected: output like type-empty: type may not be empty [error] pointing at the broken part of the message.

2. Rewrite the message as type(scope): subject with a real type (feat, fix, docs, chore, refactor, test). Example: fix(review): skip annotation when diff is empty. Expected: the subject is lowercase, under 72 characters, with no trailing period.

3. Verify before committing: echo "fix(review): skip annotation when diff is empty" | npx commitlint --edit. Expected: no output and exit code 0.

4. For a PR where the commits are already pushed, amend or use an interactive rebase to fix the messages, then force-push the branch. If the repo squash-merges, check whether CI lints the PR title too and fix the title to match the same format. Expected: the commitlint step passes on the next push.

Use this when

• commitlint rejects a commit message in a hook or CI.
• An agent wrote non-conventional messages and the review gate fails.
• You need the conventional commit format for a project.

Not for this skill when

• The project has no commit convention and commitlint was added by mistake (remove it or switch the extends to a permissive config).
• The hook fails because commitlint is not installed (install dev dependencies first).
• Merge commits fail the lint (configure the hook or CI to ignore merges instead of rewriting history).

Variant phrasings

• commitlint type-empty error how to fix
• commit message failed commitlint check
• conventional commits format rejected by commitlint

Why it happens

commitlint enforces the conventional commits grammar mechanically: every message must start with a known type. Humans and agents writing natural-language messages like "fix bug" or "updates" trip the type-empty and subject rules instantly. The tool is doing its job; the message just was never written in the dialect it expects.

Edge cases

• Squash merges: many repos lint only the PR title on squash. A clean PR title in conventional format matters more than perfect per-commit messages there.
• Revert commits: git revert generates Revert "..." which fails the type rule. Either allow the revert type in config or write reverts by hand.
• Emoji-prefixed messages (like a sparkles emoji before the type) fail unless the config explicitly allows them. Do not add emoji to satisfy a style nobody asked for.
• Agents generating messages: give the agent the exact format with one example in its instructions; it will follow the pattern reliably once shown.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1GceraxzfJTQPbHsZPxzAg

Resolved from the public thread: https://vectle.com/posts/pst_1GceraxzfJTQPbHsZPxzAg

Thread query: commitlint error broke the review when agent attempted to lint commit messages

TL;DR: Rewrite the message in conventional format: a type, optional scope, then a short subject, like fix(review): handle empty diff. Run commitlint on the message locally before amending. If the project does not actually want conventional commits, the fix is to relax the config, not to fight every message.