WARP Commit Messages

WARP is a commit-message shorthand designed to be scanned quickly and traced easily. Every commit header has exactly three bracketed segments:

[TYPE][Function/FileName][Short Description]

• TYPE — a four-letter (or short) uppercase code for the kind of change
• Function/FileName — the function, class, file, or module the change is centered on
• Short Description — an action-oriented phrase (typically 3–8 words) saying what the change accomplishes

Example: [BUGF][validateUser][Handle empty email input]

For the complete specification — full type table, all scope rules, the examples gallery, best practices, and adoption guidance — read references/warp-spec.md. Load it when the user asks a question about the protocol itself, wants documentation for their team, or hits an edge case not covered below.

Workflow

1. Understand the change. Look at the diff, staged files, or the user's description. If nothing is provided, ask for a one-line summary of what changed (or run git diff --staged if you have a shell).
2. Pick the TYPE from the table below. Choose the primary purpose; a bug fix that also tidies formatting is still BUGF.
3. Pick the scope at the narrowest level that honestly covers the change (function → class → file → module → Multiple).
4. Write the description as an imperative verb phrase: "Add", "Fix", "Remove", "Simplify", "Update".
5. Deliver the header on its own line in a code block so it can be copied directly. If the change genuinely needs more explanation, add a blank line and a short body below the header — WARP governs the header, not the body.

Type codes

Code	Meaning	Code	Meaning
FEAT	Feature addition	DEBG	Debugging / diagnostics
BUGF	Bug fix	INIT	Initial commit
REFA	Refactoring (also RFTR)	MERG	Merge
DOCS	Documentation	CONF	Configuration
TEST	Testing	SECU	Security patch
PERF	Performance	RELE	Release
DEPR	Deprecation	PR	Pull request
STYL	Code style / formatting	CLEA	Cleanup / dead code removal

Prefer REFA over RFTR unless the project already uses RFTR. Teams may add project-specific types when the meaning is obvious; don't invent one when an existing code fits.

Quick disambiguation:

• Behavior changed for the better and it was previously wrong → BUGF
• Behavior unchanged, structure improved → REFA
• Behavior unchanged, only whitespace/formatting/naming → STYL
• Faster or lighter, behavior unchanged → PERF
• Removing unused code → CLEA; marking something as going-away → DEPR
• Build, env, CI, deploy, or settings files → CONF

Scope rules

Match the specificity to what actually changed:

Change touches…	Use	Example
One function or method	function name	[BUGF][validateToken][Handle expired tokens]
One class	class name	[REFA][PaymentProcessor][Simplify transaction handling]
One file	file name with extension	[FEAT][Dashboard.jsx][Add analytics widget]
A feature area / service / component	module name	[PERF][ImageProcessing][Optimize image resizing]
Several unrelated areas	Multiple	[CLEA][Multiple][Remove unused utilities]

Use the real name exactly as it appears in the code (UserService.ts, not user service). Avoid cryptic abbreviations: [FEAT][UA][Add login] is worse than [FEAT][UserAuthenticator][Add biometric login].

Description rules

• Imperative mood, capitalized first word, no trailing period
• Say what was done, not that something was done: [Add fuzzy search] beats [Changes related to searching]
• Keep it short enough that the whole header reads comfortably on one line (aim for under ~72 characters total)
• Don't repeat the scope in the description: [BUGF][Navbar.jsx][Fix mobile alignment], not [BUGF][Navbar.jsx][Fix Navbar mobile alignment]

Examples

Input: "Added JWT-based login to the auth service" Output: [FEAT][AuthService][Add JWT-based login]

Input: "the date parser crashed on empty strings, fixed it in parseDate" Output: [BUGF][parseDate][Handle empty string input]

Input: "ran prettier over the whole components folder" Output: [STYL][Components][Apply Prettier formatting]

Input: "bumped version to 2.3.0 and updated changelog" Output: [RELE][Application][Prepare version 2.3.0]

Input: "deleted three helper functions nobody uses across utils, api, and hooks" Output: [CLEA][Multiple][Remove unused helper functions]

Input: a diff that adds a new endpoint and fixes a null check in the same file Output: Suggest splitting into two commits; if the user wants one, lead with the dominant change: [FEAT][orders.js][Add cancel-order endpoint] and mention the null-check fix in the body.

Validating existing messages

When asked to check or lint messages, test each against:

^\[[A-Z]{2,5}\]\[[^\[\]]+\]\[[^\[\]]+\]$

Then check the softer rules: TYPE is a known code, scope is a real identifier at a sensible level, description is imperative and specific. Report each message as pass, or fix with a corrected version and a one-line reason. Offer this regex (or a stricter one with the exact type list) if the user wants a commit-msg hook or CI check.

Converting from other conventions

Conventional Commits map cleanly: feat(auth): add oauth support → [FEAT][Authentication][Add OAuth support]. Map feat→FEAT, fix→BUGF, refactor→REFA, docs→DOCS, test→TEST, perf→PERF, style→STYL, chore→CONF or CLEA depending on content, ci/build→CONF. Promote the parenthesized scope to the second bracket; if there is none, infer one from the description or diff.