Add perf-review skill for pre-PR hot-path performance review

[dougqh]

What Does This Do

Adds a read-only /perf-review Claude Code skill (.claude/skills/perf-review/) that reviews a diff / branch / PR for tracer performance overhead using the performance rubric, and notes the pre-PR performance review under AGENTS.md's PR conventions (alongside /techdebt).

The skill flags hot-path allocation, unbounded memory, repeated work, escaping objects, native-boundary crossings, and JVM-specific pitfalls (escape analysis, JNI / virtual-thread pinning, backtracking-regex ReDoS, varargs/boxing hashing, String.format, ByteBuddy-Advice anti-patterns).

Posture: do-no-harm / assume-hot, advisory (never blocks a merge), precision over recall (silent when unsure), and verify-don't-verdict (every finding routes to Benchmark → Profile → Improve → Guard). It is read-only — it reports ranked findings and never edits code.

Motivation

Catch any big structural issues - unbounded collections, etc before merge & release
Accumulate small performance wins - to improve the performance of the whole

Additional Notes

Layout

• SKILL.md — posture, workflow, a PR-style output template, and a compact check index.
• references/guide.md — the narrative "how": severity model, hotness rubric, categories with examples.
• references/checks.md — the confidence/severity cost-model: 7 universal checks + Java addendum (J1–J11) + ByteBuddy-Advice fix idioms.
• references/example-review.md — a worked review to calibrate output.

Usage

Run /perf-review before opening a PR. It computes the branch diff against the upstream merge-base (or reviews specific files you point it at) and reports findings with confidence, severity, the reachability path, and a verify-with suggestion.

Validation

Back-tested against a curated perf-review corpus of merged/closed PRs with known expected verdicts — reproduced the expected precision (false-positive traps stay silent), recall (real regressions flagged), and nuance (severity-regime demotion, resolve-via-sink, correctness-lens routing).

Notes

• No tracer runtime code changes — this adds a dev-workflow skill (markdown) plus one AGENTS.md line. tag: no release notes.

🤖 Generated with Claude Code

[datadog-prod-us1-6]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 57.03% (-0.01%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 81ce335 | Docs | Datadog PR Page | Give us feedback!}

[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	13.99 s	13.87 s	[+0.1%; +1.7%] (maybe worse)
startup:insecure-bank:tracing:Agent	12.95 s	13.02 s	[-1.3%; +0.2%] (no difference)
startup:petclinic:appsec:Agent	16.88 s	16.65 s	[+0.3%; +2.4%] (maybe worse)
startup:petclinic:iast:Agent	16.78 s	17.02 s	[-2.3%; -0.5%] (maybe better)
startup:petclinic:profiling:Agent	15.96 s	16.78 s	[-9.1%; -0.6%] (maybe better)
startup:petclinic:sca:Agent	16.90 s	16.74 s	[+0.0%; +1.8%] (maybe worse)
startup:petclinic:tracing:Agent	16.05 s	16.22 s	[-2.0%; -0.1%] (maybe better)

Commit: 81ce335e · 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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 218da4a51f

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[datadog-prod-us1-6]

More details

This PR adds a read-only performance-review skill and documentation for pre-PR hot-path analysis. No tracer code changes. All cited utilities (HashingUtils, Strings, Hashtable, RE2J) are verified to exist; "coming" items are properly marked. One documentation inconsistency: example-review.md embeds reachability information as prose rather than the structured bullet-point format the template requires, which could confuse reviewers on output format consistency.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

_{🤖 Datadog Autotest · Commit 218da4a · What is Autotest? · Any feedback? Reach out in #autotest}

[bm1549]

Overall, this is a solid use of the progressive disclosure pattern and the AGENTS.md pointer to the skill file will likely get the Codex PR reviewer's attention, although it's not fully deterministic. A future iteration can use something like datadog-agent's agentic code review workflow, but that can be a follow-up task

Mostly left comments on the way the skill is structured, rather than the contents of the skill itself. Once these comments are resolved (and Codex's ones are either solved or dismissed), I think this is good to merge

[PerfectSlayer]

I’ll check what we can trim from agent.md to keep it as small as possible, and maybe offload to, or deduplicate rules with the skill description instead

[dd-octo-sts]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-07-13 18:05:38 UTC ℹ️ Start processing command /merge

---

2026-07-13 18:05:42 UTC ℹ️ MergeQueue: pull request added to the queue

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

---

2026-07-13 19:05:13 UTC ℹ️ MergeQueue: This merge request was merged