Index of every page on this site: llms.txt
All skills
scode avatar

/scode-commit-msg-reviewer

@03a9f7f
Run it yourself

Use only when the user explicitly invokes scode-commit-msg-reviewer by name, asks for commit messages to be checked by a fresh-context reader, or their standing instructions say to always use this skill. Do not trigger merely because a commit or PR is being created. Puts commit messages, PR titles/descriptions, and equivalent VCS prose in front of a cold reader who has not seen the change, and rewrites until that reader understands them; after the first signal, applies to all commit-message-like content for the rest of the conversation. Also use when the user says "scode-commit-msg-reviewer feedback: ..." to record feedback about how this skill performed.

  • 4 files
  • 21.9 KB
  • Updated 3 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/scode/dotfiles/scode-commit-msg-reviewer

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈173 tokens for metadata: the name and description. ≈3k when used: this file. ≈2.4k more on demand in 3 files.

Description uses 8.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈691 characters, or 8.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Scode Commit Message Reviewer

Every commit message, PR title, PR description, or equivalent VCS prose (jj/Sapling change descriptions, stacked-PR bodies) you produce goes in front of a cold reader before you use it: a fresh subagent that sees the message and nothing else, and reports back what it understood and what it could not follow. You then rewrite until the reader's understanding matches what you meant. The reader's charter is reviewer.md next to this skill file.

Do not run this skill just because a commit or PR is being created and the skill happens to be available. It activates only on an explicit signal: the user invokes it by name, asks for this kind of check, or has standing instructions saying to always use it. Once triggered, it applies to every commit-message-like text you produce for the rest of the conversation — the user does not re-invoke it per commit.

It applies to messages the agent generated, with or without light guidance from the user. When it is clear from context that the user already has a precise message — they wrote it themselves, pasted one in, or are tweaking wording they authored — do nothing: no reader, no rewrite, not even a suggestion. The loop exists to make agent-written text understandable to a cold reader; a message the user wrote is already what they mean, and running it through the loop would replace their words with the agent's.

Why a cold reader, and why you do the rewriting

The message's only real audience is someone with no context: reading a log or a PR list, deciding whether to open the change, or git-blaming their way here years later to find out why. A message can be accurate in every clause and still fail that reader, because the author knows what "the new helper" and "the second branch" refer to and never notices that the reader does not.

A reviewer who has read the diff cannot catch this either — they know what the references mean too, so the references look fine. The only party that reliably notices a gap in the message is someone who does not have the knowledge to fill it. So the reader is kept ignorant on purpose: no diff, no repo, no conversation, just the message. Its job is not to judge but to report what the words conveyed, in the form of a paraphrase and a list of what it could not follow.

The rewriting stays with you because you are the only one who knows what the message was supposed to mean. A cold reader can tell you where the words fell short; it cannot tell you what should have been there. Rewrite from scratch rather than patching: a fresh draft aimed at the gaps beats an edited one that keeps the old skeleton.

Loop

  1. Draft the message, following the target repo's conventions and the drafting rules below.
  2. Materialize the temp files: the candidate message, the diff it describes, and — when the user gave any explicit instructions about the message's content, structure, length, or wording, at any point before now — an instructions file holding those instructions verbatim (or faithfully paraphrased when verbatim is impractical), including any wording the user wrote by hand that the candidate preserves. Write the instructions file once and reuse it every round: it is what keeps the user's brief intact across rounds and across context compaction, and it is what you reread before each rewrite so the rewrite does not drift from what was asked.
  3. Spawn a subagent with fresh context. Its prompt contains only: an instruction to read reviewer.md (absolute path) and follow it, the candidate file path, the diff file path (which the charter tells it not to open until its second phase), the instructions file path if there is one, and the repo root and convention file paths if any. Nothing else: not your reasoning, not the change history, not earlier rounds. The instructions file tells the reader which wording is the user's, so it reports on it rather than the author being asked to change it.
  4. Read the report. Compare the paraphrase with what you meant, slot by slot. If the reader could not say what was wrong or wanted before the change, the message has no problem statement, and no amount of detail below it will substitute — but only when you are holding a problem statement it failed to convey. The reader reports that slot empty either way, because it cannot tell a why you left out from a why that never existed. You can. Check which one it is before you rewrite, and if the honest answer is that you have no reason for this change beyond what the diff already shows, the empty slot is the message being correct, not the message failing. Do not close it by inference; see "Manufactured motivation" below. Where the paraphrase is vague, hedged, wrong, or missing the point, the message did not carry that point — that is the finding, whether or not the reader listed anything under "could not follow". The "could not follow" list is a diagnosis, not a to-do list: it tells you where the reader lost the thread, not which sentences to insert. "Did not need" is the opposite signal and just as real: sentences the reader could drop without losing anything are length the message charges every future reader for; cut them unless they carry a why the reader missed. "Against the change" names claims to correct. "Conventions" names mechanical fixes.
  5. Decide whether the message is done. It is when the paraphrase matches your intent, nothing is contradicted, and every remaining "could not follow" item is something the message is right not to explain. The reader reports from total ignorance, which is what makes its report trustworthy, but the message's real audience is not totally ignorant: it knows what the project is and what its main tools are called. A reader who cannot tell whether jjstack is a command or a skill, in a repository whose commits are mostly about jjstack, has reported a true fact about the words that is not a defect in the message. That call is yours, and it is the judgment the reader is deliberately not making; make it honestly, against the repository's actual readers, not against your own familiarity. Otherwise rewrite for that reader, and rewrite means start over: begin from the problem statement, in plain words, and tell it through — what was wrong, what this does about it, why this way. Where you have no problem statement to begin from, start at what the change does and stop there; the rewrite is for clarity, and a rewrite that acquires a why between drafts has invented one. Reread the instructions file first, if there is one. Do not answer the reader's items one by one. A draft that answers a list reads like a list of answers to questions the next reader never saw asked, which is exactly the mid-text feel this loop exists to remove; if your new draft could have been produced by inserting sentences into the old one, it is not a rewrite. Then go back to step 3 with a new subagent. Never continue a previous reader: one that has seen an earlier draft is no longer cold. Fresh readers keep finding new things, so expect diminishing returns after the first rewrite and do not chase a report that has stopped changing what you would write.
  6. Hard cap of three readers per message. If the third reader still cannot follow it, stop, show the user the candidate and the last report, and let them decide.

The user's explicit instructions outrank anything a reader reports. Never remove or rephrase something the user asked for because a reader did not follow it; keep the user's version and mention the tension to them instead.

If the environment cannot spawn subagents at all, tell the user the cold read could not run, then do the best substitute available: reread the message pretending you have not seen the diff, and rewrite anything you would not have understood.

Drafting rules

These are the things a good message does and the traps a bad one falls into. Apply them when drafting and when rewriting; the cold reader will catch some of them indirectly, but it is cheaper not to write them in the first place.

The reader model: cold, no code knowledge, reads the message before the diff. Plain language, with jargon only where a plainer word would lose real meaning. Every reference introduced in the message itself. Nothing that presumes the reader is looking at the patch.

The title is very concise and describes the user-visible effect of the change, at the altitude of someone scanning a list of titles: the kind of change and roughly where it lives, not an inventory of its contents. Naming the component the change lives in — a skill, a subsystem, a command — is orientation and belongs there; a type name or an internal codename that only someone who has read the code can parse does not. A bug fix that required heavy refactoring is still a fix. If the repo mandates a format such as Conventional Commits, get the type right.

The body carries the why: motivation, constraints, tradeoffs, rejected alternatives, surprising omissions, follow-up risks — the context a future reader cannot recover from the diff. Order it big picture to detail: the purpose or problem first, mechanics and side points later. Length is fine when the material is useful; filler because a body field exists is worse than nothing, and an empty body is often the right one.

Traps, each a reason to rewrite:

  • Diff narration. Listing or paraphrasing what changed. The diff shows that; the message should say why. A short map of a genuinely large change is different from an inventory.
  • Manufactured motivation. Dressing routine work in an invented rationale. "Libraries were out of date" is not a problem being solved; a dependency bump says so plainly or says nothing. Problem/Solution headings only when there is real explanatory context. What separates a why worth writing from a fabricated one is where it came from, not how plausible it sounds. Write the why you already hold: the user told you, you diagnosed the failure, you hit the constraint and picked this way around it, you rejected the obvious alternative for a reason you can name. Never write one you derived by looking at the change and reasoning about what it is probably for. That reasoning is fluent and it produces sentences indistinguishable from real motivation, which is exactly the danger — the future reader who git-blames their way here cannot tell your guess from the truth, will believe it, and will stop looking. A missing why leaves them to dig; a wrong one stops them digging. When you hold none, the body is empty, and that is the finished message rather than a gap to fill. Bug fixes are never this case: what was broken is a why you necessarily have, because you could not have fixed it otherwise, and a fix that does not name the failure is withholding something it knows.
  • Softened bug framing. A fix should say directly what was broken, at the level the affected reader cares about, before any mechanism. Be suspicious of openings that narrate call flow or evidence instead of naming the failure.
  • Justification before the decision. Arguing for a choice the reader has not yet been told exists. Name the decision, then defend it.
  • Buried purpose. Hundreds of characters before the reader knows why the change matters.
  • Validation and attribution boilerplate. "Tests run: …" lines, tool-credit trailers and badges — out unless the repo's own rules require them. An honest caveat about how much to trust a section is not a badge.
  • Marketing register. Enthusiasm, buzzwords, "robust", exclamation marks.
  • Vague or overlong title. "fix bug", "update code", or a first line that runs on.

Feedback capture

When the user says "scode-commit-msg-reviewer feedback: ..." (or clearly signals feedback about how this skill performed), read feedback.md next to this skill file and follow it.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 03a9f7f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 months ago

README badge

README badge for scode/dotfiles/scode-commit-msg-reviewer