diff --git a/.agents/skills/clarify-java-comments/SKILL.md b/.agents/skills/clarify-java-comments/SKILL.md new file mode 100644 index 00000000000..63cba6152e5 --- /dev/null +++ b/.agents/skills/clarify-java-comments/SKILL.md @@ -0,0 +1,275 @@ +--- +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. +--- + +# 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. +- For a PR, pin the live head and base before drafting suggestions. Refresh them + before posting because comment ranges and conclusions are revision-specific. +- Preserve unrelated tracked and untracked work. Keep any authorized local edit + limited to the comments in scope, and do not switch branches in a dirty checkout + merely to inspect a PR. +- Stay documentation-focused. Do not expand into a general correctness or + performance review unless a behavioral issue makes the proposed Javadoc false. + +## 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. + +## Repair Javadoc tags as a bonus pass + +When rewriting a Javadoc, also fix missing, stale, malformed, or misused tags in +that same comment when the source makes the intended contract clear. Preserve the +project's local ordering and style, and do not invent guarantees merely to fill a +tag. Apply this bonus pass only to a whole-comment rewrite or an explicit tag-repair +request. For a sentence-, typo-, or wording-limited request, leave unrelated tags +unchanged and report any separate defect. + +- Use `@param` for each documented type parameter, record component, and method or + constructor parameter. Describe its role, constraints, or special values instead + of repeating its name or type. +- Use `@return` for the result contract, including meaningful `null`, empty, cached, + or sentinel behavior. Do not hide the return contract in the opening prose. +- Use `@throws` only for exceptions the implementation or contract can actually + expose, and state the condition that triggers each one. Remove stale exception + tags and avoid cataloguing incidental unchecked exceptions. +- Use `@see` for genuinely useful related API. Use an inline `{@link Type#member}` + instead when the reference belongs naturally in a sentence. +- Use `{@code ...}` for identifiers, literals, expressions, and short code fragments + that should render verbatim. Prefer it to raw `` markup and unnecessary + quotation marks. +- Use `{@link Type#member}` when navigation adds value; add a label only when it + reads better in context. Verify that the target and member syntax resolve, and + do not turn every type or method name into a link. +- Keep all tags aligned with the current signature: add missing parameter tags, + remove renamed or deleted parameters, and preserve declaration order. Retain + other valid tags such as `@since`, `@deprecated`, and `@implNote` unless the + requested rewrite makes a source-backed correction necessary. + +## 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. + +## Local edit mode + +A file path, class, or member selects the target; it does not by itself authorize a +mutation. Enter local edit mode only when the user explicitly asks to edit, rewrite, +fix, update, or otherwise change the documentation in place. + +- Without an explicit affirmative request to mutate the checkout, stay read-only + and return findings with copy-ready replacements. Negated, hypothetical, quoted, + or suggestion-only wording does not authorize edits. In PR context, ask when the + user has not distinguished editing local source from posting GitHub suggestions. +- Resolve a file path directly. Resolve a class or member from its qualified name, + repository context, imports, and enclosing types. Ask only when multiple plausible + targets remain and the choice would materially change the result. +- Treat every member target, whether qualified or resolved from surrounding context, + as declaration-scoped. If the named type only inherits the member, or the member + is generated and has no source declaration there, report the actual declaring + source and ask before expanding the edit to it. +- Before editing, resolve the target's canonical path and inspect symlinks. If the + canonical target falls outside the explicitly named checkout or workspace, stop + and ask for authorization for that actual target. +- Before editing, record the initial worktree status, exact target-file content, and + both staged and unstaged target-file diffs, including the full baseline for an + untracked file. Compare the result with that baseline and verify the new delta + touches only authorized comment spans. Never normalize or rewrite the whole file + when that would alter pre-existing work. +- For a file, edit only its Javadocs and explanatory comments. For a class-wide + request, include the class and its direct members, but do not recurse into nested, + local, or anonymous types. If the user names only the class Javadoc, edit only the + comment attached to the type declaration. For a member, include its attached + Javadoc and explanatory comments lexically inside its declaration or body. Ask + before changing documentation shared with another declaration. Exclude comments + attached to or inside nested, local, or anonymous type declarations unless the + user explicitly includes those nested bodies. +- Do not change executable code, declarations, annotations, string literals, + executable test code, or unrelated documentation. Preserve comment form unless + the user requests a Javadoc or comment-kind change. +- Apply the same source investigation, explanation boundary, writing rules, and + Javadoc-tag repairs used for review suggestions. +- Inspect the resulting diff and run the narrowest practical validation described + below. Report any source claim corrected by the edit and any validation that could + not run. + +## 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