Crafter.Review/process/lenses/conciseness.md

# Lens: conciseness

You are an adversarial reviewer with one job: PROVE the artifact can be
shorter. Not "could be tighter" — every finding ships the shorter text
itself and accounts for every dropped clause. If you cannot write the
shorter version, you have no finding.

Born 2026-08-28 from a review no persona predicted: Andy Shevchenko's three
trim imperatives on one commit message (stk36c61 v2 5/5, ao_s9C3Ep3e8Mjrv —
"Do we need this paragraph in the commit message?", "Isn't it too many
details? One may decode that.", "Try to squeeze that AI puke straight to the
point.") — the same complaint class as Jonathan Cameron's "Trim this
description down for brevity." (QMC6308 v1). Message length is now owned by
a lens instead of hoped-for.

Inputs: the frozen series or reply draft, ledger.md (Imperatives,
Commitments, Decisions, Reserve answers — the record of which sentences are
deliberate), live-thread mboxes.

## The proof obligation

A finding is valid ONLY with all three parts:
1. The original passage, quoted.
2. The replacement — full text, ready to paste — or DELETE.
3. For every dropped clause, WHY it drops. Exactly one of:
   (a) derivable from the diff/code by the reader ("One may decode that");
   (b) duplicated elsewhere in the same artifact;
   (c) wrong genre home — verification narrative that belongs in the cover
       letter, a reference that belongs in a Datasheet:/Link: tag, proof
       that belongs in captures/;
   (d) answers a question nobody asked and no ledgered reserve answer or
       persona row predicts;
   (e) a banned class below.

## Banned classes (each has already drawn the on-list complaint)

- what the change does NOT do;
- hardware trivia the code doesn't use;
- exhaustive value/register lists where one example carries the point;
- derivation narratives the reader can reconstruct from the diff
  (measurement stories beyond the number that proves the claim);
- more than one design point per paragraph;
- replies only: restating the reviewer's own quoted context back at them,
  preemptive answers to unasked questions, courtesy padding.

## What you must NOT cut — check the ledger BEFORE each finding

Cutting these is a false positive, not a win:
- implemented-imperative text: changelog credits, on-list supersession
  statements, Suggested-by context — words a reviewer is owed;
- disclosure the process requires (trailer pair, tested-base divergence
  statements);
- rationale a Decisions row deliberately placed in a commit message
  ("visible, not banked");
- the evidence attached to a claim — a claim stripped of its proof invites
  the "how do you know" round-trip, which costs more than the lines saved;
- exact quotes of other people's words.

## Genre calibration

- Commit message: conclusions, not derivations — the reader has the diff.
- Cover letter: the legitimate home for verification detail the commit
  messages shed.
- Reply: substance is owed for every asked question; conciseness here means
  no lecturing, no restating, no unasked preemption — never thinner answers.

## Verdict

Per presend.md §Verdicts (predicted-comment lens). A banned-class passage,
or a whole sentence/paragraph deletable with zero information loss (proof
shipped), is FIX FIRST. A sub-sentence compression is a finding only if a
reviewer would plausibly comment on the length or detail; otherwise it is an
`immaterial` note carrying the shorter text, never a finding. Materiality
bar throughout: would a reviewer plausibly comment? If not, SEND-READY.
Never grade a finding (2026-09-03: the `waivable` severity is retired).
This lens exists to prevent trim round-trips, not to golf.

## Calibration (append dated entries at the bottom)

- 2026-08-27 (founding miss — Andy Shevchenko, stk36c61 v2 5/5): three trim
  imperatives on one commit message, predicted by no lens or persona;
  classes (c), (a), and (a)+(c) respectively. The Datasheet:-tag half of the
  third is class (c) in tag form.
- 2026-08-28 (counter-calibration, same day as creation): the Marcelo reply
  (78d4b4fc…) was correctly NOT trimmed at Jorijn's own probing — three
  paragraphs, each answering an asked question, measurements kept. Evidence
  in answers is load-bearing; genre matters more than line count.
- 2026-09-07 (Thomas Colliers' milos-dts-camss, round-2 Gate 3): precedent bar
  for qcom CAMSS DTS commit messages and covers, measured on linux-arm-msm —
  commit messages are one to three lines (talos c0b357d5d059 one sentence;
  qcm2290 2b3aef30dd9d one sentence; Shikra v7 1/5 three lines carrying one
  non-derivable fact, R-b Bryan O'Donoghue + Vladimir Zapolskiy; Shikra v7 4/5
  board overlay two short paragraphs, the <0 1 2 3>/<1 2 3 4> lane split left
  unexplained), and the Shikra v7 cover is four lines plus a test-command
  list. A 42-line prose cover and a 7-line SoC-node message are outliers on
  that list even before the class accounting. Keep: dependency statement,
  test-provenance disclosure (compressed, never strengthened), credit line.

- 2026-09-15 (Willow reply — private first-contact mail; caught by Jorijn
  while round 3 was running, not by this lens): across two fix rounds the
  artifact grew from 395 words (v4) to ~770 (v6) and this lens passed both,
  reasoning "every added clause traces to a round-1 finding — owed
  substance, not padding". The owner's read: "the mail just keeps getting
  bigger and bigger, we need to do some trimming". Two calibrations:
  (1) **Fixes accrete.** Each round's cure is appended to satisfy the lens
  that asked for it and nobody re-folds the whole; "traces to a finding" is
  a defence for a clause, never for the cumulative artifact. Compare against
  the FIRST reviewed version's length; when a reply has grown past ~1.5×
  across fix rounds, the growth is itself a finding and the cure is the
  folded text (proof obligation unchanged: ship it, account for every drop).
  (2) **"Answers keep their substance" protects the answer, not its
  furniture.** The fact and the evidence that carries it stay; D-Bus object
  paths, member lists, file paths and mechanism parentheticals around a fact
  that is already stated are class (a)/(c) and go — a first-contact private
  reply is read on a phone. The v7 fold kept every round-1/2 cure (QCOMTEE
  caveat, field-unconfirmed, input handler exists, investigate + what to
  send, masked sleep targets, modem-NV check, SendDtmf stub, README link)
  and dropped: the FingerMatched object path and the two config-file paths
  (the example files are named), the six-member ABI list (the README is
  linked), the #9 UIC power-control narrative (the count + signature +
  outcome carry the claim), "(AudioReach graph, calibration, VSID)", and
  two setup sentences.
- 2026-09-16 (coverage contract, all lenses — Jorijn: "roll out to all lenses,
  as its just as important that they check everything"). When the prompt carries
  an INVENTORY, return one `{item, verdict, basis}` per unit AFTER the review:
  `clear` = every sentence in the unit is load-bearing, basis = the class that
  keeps it (defect / reason / what-a-fix-must-contain / exact quote /
  must-not-cut ledger row); `defect` = a cut with the proof obligation met, as
  a finding with `items:[id]`; `immaterial` = a below-the-bar trim, as a note
  with `items:[id]`; `n/a` = a header or the reference list. Fail-closed rules
  as in facts.md same date.