v2.1.1

v2.1.1

Patch release. Tightens what the skill puts in a commit body: every line now has to
carry information the diff can't, and omitting the body entirely is documented as the
normal, correct output rather than a gap. No new capability, no change to the four
modes, and the read-only and no-AI-attribution guarantees are untouched.

The problem this fixes: bodies were coming out padded with restatements of the subject,
file-by-file narration, and generic value claims. That costs the reader time and returns
nothing — worse, it teaches them that bodies in the repository carry nothing, so they
start skipping bodies, and the one commit that genuinely needed explaining gets skipped
along with the rest.

What changed

Every claim in a body must trace to evidence — a specific hunk in the diff, an issue
you referenced, or something you said in the session. A body assembled from filenames is
guesswork, and guesswork in permanent history is worse than silence. If no real reason
can be stated from that evidence, the body is omitted rather than invented.

A body earns its place only when it adds one of five things: the problem or trigger
behind the change; a non-obvious decision plus the alternative rejected and why; a
consequence a reader wouldn't predict from the diff; migration, operational, or
compatibility impact; or a reference the diff can't carry, such as an issue ID or an
incident. Anything else, and the commit is subject-only.

The test applied to every line: could a reviewer recover this from git show alone?
If yes, it gets cut.

Now banned outright: restating the subject in longer words; narrating what the diff
already shows ("updated X, then updated Y", file lists); generic value claims not
grounded in the change ("improves maintainability", "enhances readability", "better
developer experience", "for consistency", "for clarity"); preambles ("This commit…", "In
this change…"); and boilerplate section headers on a short message.

There is no minimum body length and no bullet quota. Fewer, denser lines beat more,
thinner ones.

What this looks like

Before — seven lines that narrate the diff and then make claims that would fit any
commit ever written:

refactor(payments): use tenacity for retries

This commit refactors the retry logic in the payment client. The custom
retry loop in `client.py` was replaced with the `tenacity` library, and
`pyproject.toml` was updated to add the dependency.

This improves maintainability and readability, and gives us a more
consistent approach to retries across the codebase.

After — four lines, each carrying something git show doesn't, and a corrected type:

fix(payments): stop retrying non-retryable card errors

The hand-rolled retry loop treated every exception as transient and
retried on 400-class card errors, which double-charged one customer
before we caught it. tenacity retries only on the transport errors we
list, so a declined card fails once.

Refs: INC-204

Pull-request descriptions

The same discipline now applies to mode 3. A section with nothing real to say is
dropped entirely rather than filled with "N/A", "None", or a paraphrase of the
summary — two substantive sections beat five padded ones.

This reverses a previous instruction. Up to 2.1.0 the skill was told to write "None"
under Breaking changes so a reviewer knew the question had been considered rather
than overlooked. The obligation to check for a breaking change is kept; only the
placeholder line is gone. A breaking-changes section that says something substantive
about compatibility — that a new header is optional, that existing clients keep working
— is a real claim and still belongs.

Files updated

• SKILL.md — version bump to 2.1.1; step 5 (Compose the message) carries the body
  ruleset with an explicit omit-unless instruction; step 6 (Self-check) gains the
  git show test; mode 3 gains the drop-empty-sections rule.
• AGENTS.md — the same step 5 and step 6 changes, kept in sync; the Body block
  under "The format" rewritten to carry the full ruleset inline, since AGENTS.md has
  to stand alone.
• references/craft.md — the canonical home for the ruleset: the body section expanded
  with the evidence requirement, the five warranted categories, and the git show test;
  five new entries in the anti-pattern catalogue.
• references/examples.md — new annotated "Cutting a padded body" before/after; existing
  examples audited against the new rules.
• references/pull-requests.md — drop-empty-sections in the description guidance, the
  revised breaking-changes rule, and the worked example updated to lead with substance.

Upgrade notes

Drop-in replacement for 2.1.0. Nothing about how you invoke the skill changes. Expect
two differences in output: more commits come back subject-only, and generated PR
descriptions no longer emit a "Breaking changes: None" line when there is nothing to
report.

Full Changelog: v2.1.0...v2.1.1