Add a skill to clarify Java comments

.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 `<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.
+
+## 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 `<code>` 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 <script>.java`; keep shell usage to simple
+commands such as `gh`, `rg`, and `sed`.
+
+## GitHub suggestion mode
+
+External review mutations require explicit user authorization. Otherwise, return
+copy-ready suggestion blocks without posting them.
+
+When authorized to add suggestions to a pending review:
+
+- Resolve the authenticated user's existing `PENDING` review and confirm its commit
+  matches the current PR head. Inspect all existing review threads as well as the
+  pending comments before adding anything.
+- If no matching authenticated-user `PENDING` review exists, or its commit does not
+  equal the current PR head, stop without creating, replacing, rebasing, or mutating
+  a review and report the mismatch. Those operations require separate authorization.
+- Add a new draft comment only through an operation that explicitly attaches it to
+  the resolved `PENDING` review ID. Never fall back to a standalone review-comment or
+  reply endpoint. If the available API cannot attach the comment to that review,
+  stop and return the copy-ready suggestion without posting.
+- If a published conversation already covers the same path and line range and
+  concerns Javadoc or comment wording, do not start another conversation. Surface it
+  and skip the duplicate. Do not reply under pending-review authorization: publishing
+  a reply requires separate explicit authorization. Only refine a comment already
+  owned by the authenticated user's matching `PENDING` review.
+- Prefix every GitHub comment created or edited by this skill, including a copy-ready
+  comment returned without posting, with the exact Conventional Comments label
+  `**suggestion:** `. Put the one-sentence reason immediately after the prefix, then
+  add a blank line before the suggestion block. Do not vary the label or casing.
+- Put the exact replacement in a GitHub `suggestion` code block. Keep the prose
+  outside the block to one short reason for the rewrite.
+- Anchor a multi-line suggestion within one diff hunk. If a rewrite crosses hunk
+  boundaries, split it into coherent suggestions or preserve the unchanged trailing
+  lines.
+- Refine an existing draft comment in place instead of adding a duplicate. Pending
+  comments may return `404` through the individual REST endpoint; resolve their node
+  IDs through the pending review and use the review-comment update API when needed.
+- Never submit the review while adding or editing comments. After suggestion
+  mutations, verify the PR head is unchanged and the review still reports
+  `state: PENDING` with no submission timestamp.
+
+Review submission is a separate mode. Require the user to choose `COMMENT`,
+`APPROVE`, or `REQUEST_CHANGES`; ask if the event is unspecified. Immediately before
+submission, re-resolve the authenticated user's `PENDING` review, re-fetch its body
+and comments, and confirm its commit matches the current PR head. Stop and report any
+mismatch or concurrent content change. Submit the existing body unchanged unless
+editing it was separately authorized. After submission, verify and report the
+selected terminal state and submission timestamp.
+
+Do not commit, push, create a pull request, publish a reply, or submit a review unless
+the user separately authorizes the corresponding action.
+
+## 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.