Add a skill to clarify Java comments

[bric3]

What Does This Do

Adds the clarify-java-comments Codex skill for reviewing or rewriting Java
Javadocs and explanatory comments.

The skill provides source-grounded guidance for:

• preserving contracts, material constraints, and non-obvious JVM behavior;
• removing narration of visible code and intermediate inferences;
• repairing Javadoc tags and inline markup;
• editing documentation locally by file, class, or member; and

Tip

At this time, this skill works WAY better with codex.

Motivation

Claude-generated Javadoc and comments often narrate every inference instead of providing useful documentation for human readers. This makes contracts, invariants, and important JVM behavior harder to find and understand.

The skill defines a reusable boundary: retain verified explanations that materially affect the contract, correctness, safe modification, compatibility, or performance
when they are not readily recoverable from nearby code. It should express that reasoning as the shortest useful causal chain and remove the rest.

Additional Notes

• This is documentation-only tooling and never perform executable code changes.
• Local edits, GitHub mutations, review replies, and review submission have separate
  authorization boundaries.

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels
• Avoid using close, fix, or any linking keywords when referencing an issue
  Use solves instead, and assign the PR milestone to the issue
• Update the CODEOWNERS file on source file addition, migration, or deletion
• Update public documentation with any new configuration flags or behaviors
• Once approved, use merge queue to merge the PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-01T15:19:09.927997Z	f6d8a8d	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[datadog-datadog-prod-us1]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 58.83% (-0.03%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 104ac01 | Docs | View more details | Give us feedback!}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d87ee17e25

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[datadog-datadog-prod-us1]

The skill cannot run its required Gradle checks because it names a command that this repository does not provide.

_{Open Bits AI session}

_{🤖 Datadog Autotest · Commit d87ee17 · What is Autotest? · @DataDog review to ask questions · Any feedback? Reach out in #autotest}

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.85 s	14.78 s	[-0.4%; +1.4%] (no difference)
startup:insecure-bank:tracing:Agent	13.68 s	13.72 s	[-1.2%; +0.5%] (no difference)
startup:petclinic:appsec:Agent	17.45 s	17.40 s	[-0.6%; +1.2%] (no difference)
startup:petclinic:iast:Agent	17.44 s	17.55 s	[-1.4%; +0.2%] (no difference)
startup:petclinic:profiling:Agent	17.37 s	17.28 s	[-0.7%; +1.7%] (no difference)
startup:petclinic:sca:Agent	17.49 s	17.38 s	[-0.1%; +1.4%] (no difference)
startup:petclinic:tracing:Agent	16.61 s	16.65 s	[-1.3%; +0.9%] (no difference)

Commit: 104ac016 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

[bric3]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f6d8a8d65e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dougqh]

One question on the new SKILL.md frontmatter: it only declares name and description. Every other skill under .agents/skills/ (techdebt, perf-review, apm-integrations, etc.) also sets user-invocable: true, and the ones that do file edits / gh mutations / gradle invocations declare context: fork and/or an explicit allowed-tools list (e.g. perf-review marks itself read-only via allowed-tools).

Given this skill can edit local files, post GitHub review comments, and run ./gradlew, was omitting those fields intentional (inherit everything from the invoking session) or an oversight? Worth aligning with the sibling skills' convention either way.

[sarahchen6]

I support this skill given more and more AI contributions!

In general, I think the skill is a bit verbose though. I started leaving some comment suggestions, but we should rework to keep instructions minimal so not to overwhelm the context of the AI using this, similar to existing skills like for techdebt: https://github.com/DataDog/dd-trace-java/blob/master/.agents/skills/techdebt/SKILL.md.

WDYT about centering the skill around existing best practices like https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/? I think defining these 9 rules plus a bit of context is sufficient and straightforward.

[sarahchen6]

Let's try it out!

[bric3]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-09-04 08:34:40 UTC ℹ️ Start processing command /merge

---

2026-09-04 08:34:46 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 1h (p90).

---

2026-09-04 09:30:16 UTC ℹ️ MergeQueue: This merge request was merged

[bric3]

Related to

• Add dd-apm-sdk-review skill and repo overrides, replace perf-review #12364