[alexander-yevsyukov]

The rule

On 2026-10-28, while reviewing SpineEventEngine/core-jvm#1699, the owner stated the convention
for .proto doc comments:

we do not add an empty line at the end of one-paragraph type description

An empty line is added after a 2nd and further paragraphs.

They removed a trailing // from the one-paragraph doc of LiveEventsPickedUp by hand. No
reviewer or agent could have flagged it, because the shared guidance did not forbid it.

What was wrong

• guidelines/documentation.md § "Protobuf file headers" named file headers only, and said
  single-paragraph headers "do not require" the trailing //. That reads as optional.
• skills/review-docs/SKILL.md checked only that a multi-paragraph doc comment ends with //.
  An unwanted // after one paragraph was never a finding.
• guidelines/protobuf.md § API documentation already had the rule right, but only for "a type
  or a field". It said "empty line" where it meant an empty comment line.

The change

• documentation.md: the section is now "Protobuf doc comments". It covers every doc comment,
  whatever it documents: the file as a whole, a message, a field, a oneof, an enum or enum
  value, a service, or an RPC. A one-paragraph doc comment must not end with //, and a doc
  comment of two or more paragraphs must. It adds a right/wrong example and links to
  protobuf.md. The copyright notice is exempt, because it is not a doc comment.
• protobuf.md: the same scope, "empty comment line (//)" wording, and copyright exemption.
• review-docs: the Check A bullet makes either mistake a Should-fix. The .proto scope line,
  the authority list, and the Should-fix output list now match.

No other statement of the rule was found in guidelines/, skills/, or claude/. The
proofread skill and english-style.md cover only grammar and the scope of prose, so they are
unchanged. Nothing linked the old #protobuf-file-headers anchor.

Verification

• Markdown only, so there is no build. git diff --check is clean. The longest added line is 96
  characters, under the 100-character limit.
• The review-docs reviewer ran on the diff and returned APPROVE WITH CHANGES. Its should-fixes
  are applied: oneof is in the list, the copyright exemption is in protobuf.md, and the
  cross-reference is corrected.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-28T17:28:39.619332Z	9132962	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[Copilot]

🟢 Approved

No active review issues are reported for the Protobuf documentation convention and review-skill updates.

No open issues 🎉

What changed in this PR

This PR makes the shared Protobuf documentation convention explicit and aligns the documentation-review skill so agents apply it consistently across Spine repositories.

Changes:

• Forbid a trailing empty // line after one-paragraph doc comments and require it after multi-paragraph comments.
• Apply the rule to all Protobuf doc comments, while exempting copyright notices.
• Add correct/incorrect examples and classify either violation as a Should-fix.

File	Description
skills/​review-docs/​SKILL.md	Expands Protobuf review scope and explicitly flags both trailing-line violations.
guidelines/​protobuf.md	Clarifies the rule’s scope, empty-comment-line syntax, and copyright exemption.
guidelines/​documentation.md	Replaces header-only guidance with general doc-comment rules, examples, and cross-references.

_{Review effort: Balanced}