---
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](references/javadoc.md) for whole-comment rewrites or explicit tag
  repair.
- [Local edits](references/local-edit.md) before changing documentation in the
  checkout. A path selects a target but does not authorize an edit.
- [GitHub reviews](references/github-review.md) 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.