clarify-java-comments

name	clarify-java-comments
description	Clarify or review Java Javadocs, Javadoc tags, and explanatory code comments for legibility, accuracy, and source alignment. Use when asked to simplify verbose or generated comments, edit documentation in a local file, class, or member, repair Javadoc markup, propose copy-ready replacements, or add GitHub suggestions to an existing pending PR review. Documentation-focused: never change executable code or turn the task into a general code review. Do not submit a review unless explicitly requested.
user-invocable	true
context	fork
allowed-tools	["Bash","Read","Edit","Glob","Grep"]

Clarify Java Comments

Produce concise documentation that preserves the contract, useful conclusions, and important hidden behavior without narrating every inference or obvious implementation step. Treat existing comments and PR descriptions as claims to verify against the current source.

Scope the work

• Review or edit only the Javadocs and explanatory code comments changed by the diff or explicitly named by the user.
• Read enough surrounding implementation, tests, and callers to verify every retained claim. Report an inaccurate claim instead of preserving it in smoother prose.
• Before shortening a comment, inventory its distinct technical claims and invariants. Classify each as supported and important, obvious or redundant, or unsupported. Preserve every supported non-obvious item in the rewrite.
• Stay documentation-focused. Do not expand into a general correctness or performance review unless a behavioral issue makes the proposed Javadoc false.

Route the workflow

Read all references that apply to the request:

• Javadoc tags for whole-comment rewrites or explicit tag repair.
• Local edits before changing documentation in the checkout. A path selects a target but does not authorize an edit.
• GitHub reviews before any GitHub review workflow. Posting, replying, editing, and submitting each require the separate authorizations defined there.

Decide what deserves explanation

Use this deletion test before shortening or removing explanatory detail: would its absence make a competent maintainer likely to miss a material constraint or have to reconstruct it through specialist knowledge or non-local investigation?

• Keep a verified explanation when it affects the API contract, correctness, safe modification, compatibility, or performance and is not cheaply recoverable from the signature and nearby straight-line code using ordinary Java knowledge.
• Treat behavior as non-obvious when it is implicit in the platform or runtime, such as JVM, Java Memory Model, or JIT behavior; when its cause or effect lies elsewhere, such as in a caller, lifecycle, generated bytecode, or downstream consumer; or when the local code requires specialist reasoning about synchronization, memory visibility, interleavings, type profiling, allocation, or escape analysis.
• Preserve the shortest causal chain that explains the constraint: the condition or mechanism, the resulting effect or invariant, and why it matters to callers or future changes. Omit intermediate proof steps once that chain is understandable.
• Omit prose that only restates names, types, syntax, or visible control flow; repeats the same contract or conclusion; catalogs irrelevant alternatives or history; or adds technical detail without a reader-relevant consequence.
• Do not equate proximity with obviousness. Nearby code can require explanation, and distant or technical behavior should be retained only when it materially matters.

Rewrite for readers

• Lead with the API contract or purpose. Apply the decision rule above to any explanatory detail beyond that contract.
• Express each retained explanation as a compact causal chain rather than narrating every inference.
• Do not remove JVM internals merely because they are arcane. When relevant, retain matters such as Java Memory Model publication and happens-before guarantees, safe traversal through retained links, HotSpot escape analysis or devirtualization, composite-key allocation, identity fast paths and boxing, atomic updater and reservation accounting, or type erasure in runtime containers such as AtomicReferenceArray. These are examples of details to preserve, not a checklist of content to invent.
• Define specialist terms on first use. Prefer one compact explanation over a historical detour or a list of what the code does not do.
• State a supported conclusion once. Retain only the reasoning needed to satisfy the decision rule above and make the conclusion safe to act on.
• Use a one-line Javadoc for an obvious delegate or predicate. Use paragraphs only when they carry distinct information.
• For benchmark documentation, separate inputs and setup from measured results and conclusions. Keep existing JMH result tables and numbers when present unless the user asks to remove them or evidence shows that they are stale or invalid. Retain the environment details needed to interpret the numbers, and remove speculation that was not measured. If results are unreliable, flag the problem instead of silently replacing the evidence with prose.
• Prefer <pre>{@code ...}</pre> for a useful copy-ready example. Do not add an example when the signature already makes usage clear.
• When a claim depends on JVM, library, or tool behavior outside the repository, verify it with primary sources such as OpenJDK source or the maintained project's official documentation. Do not rely on commercial aggregator sites.
• Use plain international English. Remove stacked parentheticals, repeated claims, conversational asides, promotional adjectives, and long "not to be confused with" passages.

Write for one-pass reading

A rewrite must be easier to understand, not merely shorter. Aim for an informative, concise, legible, blog-like technical style.

• Put the main point first. Use a concrete subject and an active verb where practical.
• Keep one idea per sentence and one purpose per paragraph. Split nested clauses and long parenthetical chains.
• Name the relevant method, state, or JVM mechanism instead of relying on an unclear pronoun or distant antecedent.
• Keep the connective sentence that makes a causal relationship understandable. Concision must not make the text compressed, cryptic, or abrupt.
• Use terminology that matches the code and domain. Replace vague generated labels with names a maintainer would naturally use.
• Read the replacement once in its surrounding context. If understanding a sentence requires backtracking to find its subject, condition, or conclusion, rewrite it.

Reword explanatory code comments

Apply the same source-grounded rewrite to // and /* ... */ comments that narrate obvious steps, repeat conclusions, stack caveats, or otherwise read like generated verbiage.

• Preserve the comment's form and scope; do not turn an implementation comment into Javadoc unless the user requests an API documentation change.
• Keep comments that record an invariant, a non-obvious reason, a compatibility constraint, or a deliberate tradeoff. Remove line-by-line narration of code that is already clear.
• Never modify suppression directives, generated markers, license text, or tooling instructions in this skill. Preserve TODO/FIXME ownership and status; rewrite only their explanatory prose when the user explicitly names it.

Check the replacement

Before presenting, applying, or posting a replacement:

1. Compare each sentence with the exact source and relevant tests.
2. Check reused state, cached values, version-dependent behavior, and benchmark setup; these commonly make plausible Javadoc claims false.
3. Verify links and tags name real types, members, and parameters.
4. Keep the replacement compatible with the original comment kind, surrounding delimiters, and repository formatting.
5. For prose-only local edits, run the narrowest formatting check. When links, tags, or examples changed, also run the narrowest available Javadoc or doclint task and any compilation needed to resolve referenced symbols. Run Gradle with ./gradlew .... After a GitHub mutation, re-fetch and verify the exact body, path, range, commit, owning review, and expected review state.
6. If verification cannot run, state exactly what was not run and why. Do not turn an environment or unrelated pre-existing failure into a finding about the rewrite.

If the workflow needs non-trivial scripting, use a Java 25 source-file launch script and run it directly with java --source 25 <script>.java; keep shell usage to simple commands such as gh, rg, and sed.

Report the outcome

Summarize which Javadocs or draft comments were changed or proposed, call out corrected factual claims, and state the verification performed. After suggestion-only mutations, confirm the review remains pending. After submission, report the selected event, terminal state, and submission timestamp.