// Draft a commit message for an Axiom commit. Use when the user asks to write, draft, or compose a commit message for an Axiom change. Encodes the project's content rules so the draft is showable without a separate review pass.
| name | write-commit-message |
| description | Draft a commit message for an Axiom commit. Use when the user asks to write, draft, or compose a commit message for an Axiom change. Encodes the project's content rules so the draft is showable without a separate review pass. |
Drafts a commit message that follows the rules in .claude/CLAUDE.md (sections "Commit Messages" and "Body length and shape"). The rules there are authoritative — this skill is the workflow for applying them.
Write to orient a reviewer, not to defend the change. A commit message's job is to orient the reader to the change — not to enumerate every affected file, restate every claim at multiple abstraction levels, or hedge against "you didn't mention X". The diff and the version-control history are the system of record. The message picks the smallest set of facts the reader needs to navigate the diff, and stops.
Apply the would-I-say-this-aloud test to every sentence: read it as if briefing a teammate verbally. Sentences that exist to prove a claim, recite enum values, attribute jargon to a subsystem, or acknowledge symbols by name die on first contact with speech. Sentences that orient — "this query failed", "Velox doesn't support it", "treat it as a regular function call" — survive. If a sentence wouldn't survive being spoken aloud, delete it.
The per-pattern rules below all derive from this principle. If a draft passes the rules but still reads like a legal brief, trust the principle and trim further.
Read the rules — Open .claude/CLAUDE.md and re-read the "Commit Messages" and "Body length and shape" sections. Do not draft from memory.
Gather facts from the diff itself — Never draft from the conversation alone. The conversation has scaffolding; the diff is the truth.
Draft — Match length to the change. Each paragraph is one long line (no hard wraps). The right shape depends on what the diff actually does:
Title: [Axiom] type(scope): Description — capital start, no trailing period, ≤67 chars. Type ∈ {feat, fix, refactor, test, docs}. Scope optional.
Body paragraphs (include only those that carry weight for this change):
Prose clarity — write so a tired reader gets each sentence on first read.
Prefer short sentences. If a sentence has two clauses joined by "so", "because", "but", "even though", "although", or a comma + participle, consider splitting it. Contrastive joiners ("but X", "even though Y") are especially risky when both halves introduce a fact the reader does not already have — pack two new facts into one sentence and the reader stalls. State each rule in its own sentence, then connect them.
Avoid stacked abstractions like "left the outer scope advertising the column as X" or "the projection inherits the source's reverseLookup names". Replace with a concrete chain.
Avoid compiler/optimizer jargon ("outer reference", "outer scope", "binding context", "name resolution scope") unless the rest of the paragraph already established it. If you must use it, define it inline with a tiny example.
Prefer plain verbs (used, dropped, kept) over jargon verbs (advertise, surface, propagate, materialize) unless the jargon is the precise term.
Avoid hyphenated compound-noun stacks ("user-written case", "lookup-based fallback", "context-aware resolver"). They require the reader to unpack a modifier chain before getting to the noun. Rewrite as a relative clause ("the case the user wrote") or a single concrete noun.
Prefer the word with one obvious meaning in this context. "Case" can mean legal case, match case, or upper/lower case — use "capitalization" when you mean letter case. Similarly: "operator" vs "function", "key" vs "column", "type" vs "kind" — pick the one a SQL reader and a C++ reader both interpret the same way.
Show a complete example query that demonstrates the failure, paired with the resulting error. Don't describe a query in prose ("a reference to X from an outer query") when you can show one (SELECT x FROM (...)); the example carries the meaning without the reader holding context across sentences.
Break any long code, query, or error string out into a fenced block on its own line. "Long" means more than ~6 words or anything that wraps the surrounding paragraph awkwardly. This applies whether the long string is paired with another or stands alone — a single long error string embedded mid-sentence still overloads the reader. Patterns:
Lead with the error, then explain:
Planning failed with:
Ranking filter limit not consumed by RowNumber or TopNRowNumber
This happened for ranking queries whose ORDER BY became empty after redundancy elimination.
Query + result:
For example:
SELECT x FROM (SELECT x_2024 AS x FROM src)
fails with `Cannot resolve column` — the inner subquery produces a column named `x_2024`, not `x`.
Short fragments (a single column name, a flag, a 2-3-word error name) stay inline.
Any enumeration of 3+ items goes in a sub-bullet list, not in a sentence — even a short one. Examples: list of recognized constructs, list of new flags, list of test scenarios. Forcing the reader to parse a list while tracking the surrounding clause overloads them.
For deletions and additions, lead with the active verb: "Removes the foo helper — no longer needed." not "The foo helper is no longer needed and is removed." Easier to skim and locate.
When in doubt, read the paragraph aloud. If you pause mid-sentence to decode it, split or simplify it.
Self-check before showing — Walk every item; do not skip any.
[Axiom] type(scope): Description, capital, no period, ≤67 chars.\`escaped\`.If any item fails, fix the draft before showing.
Show the draft — Present the final draft. Mention any facts you could not verify and want the user to confirm.
These are the patterns drafts most often hit, and that this skill exists to prevent:
Subfield.h:28-33 enumerates only ..."), restating the same fact at two abstraction levels ("step has no Velox representation" + "Velox doesn't support pushdown"), enumerating removed symbols/files in a cleanup tail ("Removes the dead enum, its handlers in A/B/C, and the X::registerY/y() accessors"), or hedging title phrasings ("X without crash"). All five derive from writing for a future challenger instead of a present reader. Apply the would-I-say-this-aloud test; cut everything that wouldn't survive being spoken.foo(), we now do A. In bar(), we adjust B." The reviewer reads the diff for that. Collapse into the single mechanism.Foo, Bar, Baz, Qux, and Quux." or "Updated across N call sites." The diff is the source of truth for scope. Naming the touched symbols eats space without informing the reader. Exception: name a specific file only when its role in the change is not obvious from the title (e.g., the test file that needed expectation updates, or the one production file the rest of the diff supports).For all other Axiom commit-message work — drafting, revising, or rewriting — invoke this skill.