diff --git a/.agents/skills/clarify-java-comments/SKILL.md b/.agents/skills/clarify-java-comments/SKILL.md new file mode 100644 index 00000000000..10d6156aaf9 --- /dev/null +++ b/.agents/skills/clarify-java-comments/SKILL.md @@ -0,0 +1,169 @@ +--- +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 `
{@code ...}
` 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