Skip to content

DOC: Add prose-budget for committed text and warning-level commit-msg hook#6241

Merged
hjmjohnson merged 1 commit into
InsightSoftwareConsortium:mainfrom
hjmjohnson:doc-prose-budget
May 8, 2026
Merged

DOC: Add prose-budget for committed text and warning-level commit-msg hook#6241
hjmjohnson merged 1 commit into
InsightSoftwareConsortium:mainfrom
hjmjohnson:doc-prose-budget

Conversation

@hjmjohnson
Copy link
Copy Markdown
Member

Codify hard caps for committed text and add a warning-level commit-msg hook so reviewers stop being asked to redo the same "trim the prose" round-trip on every PR.

What this PR changes

Two new docs, one new hook, three doc edits, one config wire-in.

File Status Purpose
Documentation/AI/prose-budget.md new Single authoritative contract: caps, forbidden content, three-layer rule (subject = WHAT, body = WHY, diff = HOW), self-audit checklist, good/bad examples.
Documentation/AI/code-comments.md new In-source comment policy: default zero comments, max one short line, WHY-only, no references to deleted code, no documentation-comment drive-bys.
Documentation/AI/community-feedback.md new Anonymized ledger of recurring reviewer-rejection patterns, each linked to the document and section that addresses the rule.
Documentation/AI/git-commits.md edited Adds Body budget section (≤ 12 lines, ≤ 72 chars/line, trailers excluded) with forbidden-content list and good/bad commit examples.
Documentation/AI/pull-requests.md edited Adds Visible-summary budget section (≤ 3 sentences, ≤ 250 chars above the first <details>) with forbidden-content list.
AGENTS.md edited Adds two MUST-READ entries for any committed-text task and a Critical Pitfall #7 promoting verbose prose to ship-blocker status.
Utilities/Hooks/kw-prose-budget.py new Commit-msg hook (warning-level by default, blocking under ITK_PROSE_BUDGET_HARD=1) flagging body-length / line-width / forbidden-pattern violations.
.pre-commit-config.yaml edited Wires the new hook adjacent to kw-commit-msg.
Caps at a glance
Artifact Cap
In-source comment 1 short line, ≤ 100 chars
Commit subject ≤ 78 chars (already enforced by kw-commit-msg.py)
Commit body ≤ 12 lines, ≤ 72 chars/line; trailers excluded
PR visible summary ≤ 3 sentences, ≤ 250 chars
PR <details> blocks unbounded (collapsed)
PR HTML comments unbounded (invisible)
Forbidden in committed text
  • AI tool / model identifiers, session timestamps
  • CDash / Azure DevOps / GitHub Actions URLs (transient — links rot)
  • Backstory / transcript narratives
  • References to deleted or prior behavior
  • First-person narrative ("we", "I")
  • Marketing language ("robust", "comprehensive", "elegant", …)
  • Restatements of the commit subject in the first body line
  • Explanations of code that the diff already shows
Hook behavior

The new kw-prose-budget.py runs at commit-msg stage alongside kw-commit-msg.py. By default it prints warnings and exits 0 (commit allowed); set ITK_PROSE_BUDGET_HARD=1 to escalate to blocking. The patterns are conservative — reviewers remain the authoritative gate; the hook reduces round-trips by surfacing the most-cited rejection patterns at commit time.

Smoke-tested locally on a synthetic verbose body — flags transient URLs, AI tool names, marketing language, line-width and line-count caps; allows the commit through with a 1 warning(s); commit allowed. summary line.

@github-actions github-actions Bot added type:Infrastructure Infrastructure/ecosystem related changes, such as CMake or buildbots type:Documentation Documentation improvement or change area:Python wrapping Python bindings for a class area:Documentation Issues affecting the Documentation module labels May 8, 2026
@hjmjohnson hjmjohnson marked this pull request as ready for review May 8, 2026 18:16
@greptile-apps

This comment was marked as resolved.

Comment thread Utilities/Hooks/kw-prose-budget.py
Comment thread Utilities/Hooks/kw-prose-budget.py
Comment thread Utilities/Hooks/kw-prose-budget.py
Codifies hard caps for the three artifacts that carry committed
text (in-source comments, commit-message bodies, PR visible
summaries) and forbids transient URLs, marketing language, AI
tool/session attribution, first-person narrative, and references
to deleted code. Adds a commit-msg hook that warns on body length
or forbidden patterns; ITK_PROSE_BUDGET_HARD=1 escalates to
blocking.

Adds Documentation/AI/{prose-budget,code-comments,community-feedback}.md
and updates AGENTS.md, git-commits.md, pull-requests.md to wire
in the new contract.
@hjmjohnson hjmjohnson merged commit f5d5f29 into InsightSoftwareConsortium:main May 8, 2026
13 of 16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:Documentation Issues affecting the Documentation module area:Python wrapping Python bindings for a class type:Documentation Documentation improvement or change type:Infrastructure Infrastructure/ecosystem related changes, such as CMake or buildbots

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants