// Per-context tone rubrics for developer communication: commit messages, PR descriptions, code comments, API docs, emails, inline chat. Use when judging whether the register and formality of a piece of text fit its destination, not just whether it is grammatical.
| name | tone-calibration |
| description | Per-context tone rubrics for developer communication: commit messages, PR descriptions, code comments, API docs, emails, inline chat. Use when judging whether the register and formality of a piece of text fit its destination, not just whether it is grammatical. |
| version | 0.1.0 |
Tone is fit-for-purpose: a sentence can be perfectly grammatical and still wrong for its context. Rubrics below are drawn from the legacy writing-guide plus the Google Developer Documentation Style Guide and Strunk & White on concise phrasing.
For commit messages, code comments, CLI help, and short docs, prefer the imperative — it is shorter and clearer than the indicative.
| Weak | Strong |
|---|---|
| "You should run the tests" | "Run the tests" |
| "It would be good to add logging" | "Add logging" |
| "We need to refactor this" | "Refactor this" |
Cut filler. From Strunk & White, "Omit needless words."
| Wordy | Concise |
|---|---|
| "In order to" | "To" |
| "Due to the fact that" | "Because" |
| "At this point in time" | "Now" |
| "In the event that" | "If" |
| "Has the ability to" | "Can" |
| "Is going to" | "Will" |
| Dimension | Requirement |
|---|---|
| Mood | Imperative (Fix, Add, Refactor — not Fixed, Fixes, Fixing) |
| Tense | Present / imperative ("Fix parser crash"), never past |
| Subject length | ≤72 characters, 50 recommended |
| Terminal period on subject | None |
| Leading article | Drop ("Fix parser crash", not "Fix the parser crash") |
| Body | Optional; wrap at 72 chars; separated from subject by one blank line |
| Why vs what | Subject = what; body = why (if the what isn't self-evident) |
| Bad | Good |
|---|---|
| "Fixed bug" | "Fix null pointer in session handler" |
| "Updated code" | "Refactor auth module to use token-based validation" |
| "Changes" | "Add rate limiting to API endpoints" |
Rule: imperative mood, present tense, specific. "Fix X" not "Fixed X" or "Fixes X".
| Dimension | Requirement |
|---|---|
| Mood | Indicative, present tense ("This change adds…") |
| Sentences | Full sentences |
| Sections | Summary / Changes / Test plan (or equivalent) |
| Links | Link issues, commits, and external discussion |
| Voice | Active preferred ("I removed the cache" > "The cache was removed") |
| Dimension | Requirement |
|---|---|
| Mood | Imperative or indicative present |
| Length | One line per logical thought; ≤100 chars per line |
| Trailing punctuation | Period if the comment is a full sentence; none if it is a label |
| Purpose | Explain WHY, not WHAT (the code shows what) |
Avoid:
// increment counter next to counter++| Dimension | Requirement |
|---|---|
| Mood | Indicative present ("Returns the user object") |
| Person | Avoid "we"; use imperative for instructions ("Pass a non-empty string") |
| Formality | Full sentences, no contractions |
| Terminology | Consistent — pick one term per concept and keep it |
| Capitalization | Match the canonical form of tool/framework names (React, not react; npm, not NPM) |
| Dimension | Requirement |
|---|---|
| Opening | Greeting line matched to recipient (first-name basis vs "Dear …") |
| Body | Full sentences; one topic per paragraph |
| Closing | Sign-off matched to formality ("Thanks," "Best," "Regards,") |
| Tone | Professional but warm; avoid both stiffness and slang |
| Requests | Direct — state the ask in the first paragraph |
| Dimension | Requirement |
|---|---|
| Formality | Informal — contractions, sentence fragments, and lower-case sentence starts are fine |
| Emoji | Fine if the team uses them |
| Code | Use backticks or code blocks for anything runnable |
| Question vs statement | End questions with ?; do not end statements with ! unless warranted |
Before emitting a tone judgement, ask:
If any of (1)–(5) is off, that is a tone issue — even if every word is correctly spelled.
This skill covers tone and register only. Related concerns live in sibling skills:
Recurring error patterns from non-native English speakers in developer contexts: article misuse, preposition confusion, tense mismatch, 'I am agree'-style anti-patterns, and other frequent L2 slips. Use when scanning for patterns a reader can map back to familiar mistakes rather than rediscover from first principles.
Core English grammar rules most likely to trip non-native developers: articles, subject-verb agreement, tense consistency, prepositions, countable vs mass nouns, comparatives. Use when reviewing grammar correctness of prose written for developer contexts (commits, docs, emails).
Punctuation conventions for developer prose: commas (serial, Oxford, clause-joining), semicolons, colons, hyphens vs en-dashes vs em-dashes, apostrophes, quotation marks. Use when reviewing punctuation of documentation, commit messages, or any prose where mis-pointing changes meaning.
Technical writing patterns for developer prose: API documentation structure, README shape, error-message wording, terminology consistency, and the active vs passive voice trade-off. Use when the text under review is documentation, a README, an API reference, or an error string.
Meta-skill that routes to the five focused writing skills in this plugin. Loads nothing substantive on its own — read this to decide which of grammar-fundamentals, punctuation-rules, tone-calibration, technical-writing, or common-non-native-mistakes to consult.