Skip to content

Drop AGENTS.md skill pointers that agents do not need to load the skill (PROF-16586) - #986

Merged
rkennke merged 6 commits into
mainfrom
rkennke/PROF-16586-drop-skill-pointers
Nov 12, 2026
Merged

rkennke merged 6 commits into
mainfrom
rkennke/PROF-16586-drop-skill-pointers

Conversation

@rkennke

@rkennke rkennke commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?:

Removes every AGENTS.md pointer to a skill, because each skill loads from its own description:

Pointer Change
verify-profiler-change (Development Guidelines) Pointer clause removed. "Never claim success until all affected tests pass" stays.
ticket-writing, work-planning, ticket-triage (Work Tracking) Pointer sentence removed.
pre-pr-review, pr-review (Agentic Code Review) Section removed.
pr-writing, ci-script-change, doc-writing Their sections held only the pointer, so they are removed. doc-writing already states the CI naming and index check.

It also changes the rules that AGENTS.md sets for itself, since they asked for these pointers:

  • Layering rule. It no longer lists "the obligations that trigger a procedure (review before PR, load a writing skill)" as inline content. A skill's description carries the obligation to run it. AGENTS.md points to a skill only when a test drive shows that the description alone does not load it.
  • Hoisting rule. A section that moves to doc/ still leaves a one-line pointer behind. A section that moves into a skill follows the skill-pointer rule.
  • Review gate row. In pre-pr-review (and its gloss in pr-review), the row named "the AGENTS.md review rules", which was the removed section. It now covers any text in AGENTS.md or a skill that says when a review is required or which reviewer runs.

AGENTS.md goes from 550 to 504 lines (wc -l on origin/main and on this branch).

Motivation:

Every session loads AGENTS.md. Both harnesses already show each skill's name and description at session start, and load the skill when the request matches. A pointer that does not change behavior costs every context for nothing.

The Agentic Code Review section repeated the pre-pr-review skill: the fix-or-waive rule, the reviewer choice, the self-checks, the marker, the no-reviewer sign-off and the hooks. The skill keeps all of them, and the hooks enforce the review.

Additional Notes:

  • Human review is recommended: every session loads AGENTS.md, and the PR changes its own layering rule.
  • Accepted costs:
    • A harness that reads AGENTS.md but neither loads .agents/skills/ nor runs our hooks no longer sees the review obligation.
    • A session that never loads pre-pr-review does not install .githooks/pre-push; the skill's step 0 installs it.
    • Revert this PR to restore the pointers.
  • Pre-PR review:
    • Sphinx, standard effort, on the pointer removals: 0 Critical/High/Medium, 2 Low. One Low is a design decision: the section no longer repeats rules that the skill holds. The other concerned the GitHub-issue tracker path (see below).
    • /code-review high on the section removal: it found that AGENTS.md's layering and hoisting rules still required the pointers, and that the gate row named the removed section. The rule changes above fix both.
    • Sphinx, standard effort, on the section removal and the rule changes: 0 findings.
  • GitHub issues stay. AGENTS.md and doc/WorkTracking.md still name GitHub issues as the tracker for external contributors. The PR ticket reference check and the README still accept and invite that route, so the docs change only together with them, in PROF-16620.

How to test the change?:

Headless skill-load drives, each in a fresh clone of the candidate, without MCP servers and with read-only tools (plus edit tools for ci-script-change, and gh pr view/gh pr diff for pr-review). Each skill has one direct prompt and one borderline prompt that does not name the artifact. Each prompt ran twice in each harness. A load counts only from a tool call: a Skill call in Claude Code, or a read of the skill's SKILL.md in Pi.

Candidate Skills Drives Loaded the skill
3999a644e all 9 72 (36 Claude Code, 36 Pi) 72

Claude Code ran claude-opus-5-5; Pi ran glm-5-3.

After 3999a644e, the branch merges main (#980), then restores the GitHub-issue clause. No skill pointer and no skill description changed after 3999a644e. The merge's only skill change is #980's new rule in the body of pr-writing, and the head's AGENTS.md differs from 3999a644e only in the restored clause.

The merge had one conflict. #980 added "After pushing commits to a branch with an open PR, re-verify the PR description…" to the PR Descriptions section, which this PR removes. The sentence is dropped. The pre-push warning names the pr-writing skill, and the skill holds the rule. /code-review medium found no issue in the resolution.

Local checks on the head (f434515ea):

  • utils/tests/test_quality_check_scripts.sh: PASS: 231 test groups
  • utils/tests/test_review_marker.sh: 268 tests, 0 failed
  • :ddprof-lib:qualityChecks: BUILD SUCCESSFUL, skills: OK (9 skills), doc index: OK (30 docs)

For Datadog employees:

  • If this PR touches code that signs or publishes builds or packages, or handles
    credentials of any kind, I've requested a security review (run the dd:platform-security-review
    skill, or file a request via the PSEC review form).
    bewaire also runs automatically on every PR.
  • This PR doesn't touch any of that.
  • JIRA: PROF-16586

🤖 Generated with Claude Code

rkennke and others added 2 commits November 12, 2026 12:59
…gger (PROF-16586)

The skills load from their descriptions, so the pointers cost every session's
context without changing behavior. Agentic Code Review shrinks to one line:
the pre-pr-review skill holds the procedure and the hooks enforce it. The
Work Tracking paragraph drops GitHub issues for external contributors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…OF-16586)

The page now names Jira as the tracker, as AGENTS.md's Work Tracking
paragraph does. The PR ticket check still accepts a GitHub issue #<n>.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dd-octo-sts

dd-octo-sts Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Scan-Build Report

User:runner@runnervmwuk1x
Working Directory:/home/runner/work/java-profiler/java-profiler/ddprof-lib/src/test/make
Command Line:make -j4 all
Clang Version:Ubuntu clang version 21.1.8 (6ubuntu1)
Date:Thu Nov 12 15:23:47 2026

Bug Summary

Bug TypeQuantityDisplay?
All Bugs2
Logic error
Dereference of null pointer1
Unused code
Dead initialization1

Filter Results by File

Reports

Bug Group Bug Type ▾ File Function/Method Line Path Length
Unused codeDead initializationreferenceChains.cppapplyOomRamp4971
Logic errorDereference of null pointerperfEvents_linux.cppunregisterThread72026

rkennke and others added 2 commits November 12, 2026 13:27
The pre-pr-review skill loads from its description and holds the whole
procedure, and the hooks enforce it. The comment-budget rule now names the
agentic pre-PR review directly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e row (PROF-16586)

AGENTS.md said that the obligations that trigger a procedure stay inline and
that a hoisted section leaves a pointer behind, which this change no longer
follows. A skill's description now carries the obligation to run it, and
AGENTS.md points to a skill only when a test drive shows the description does
not load it. The pre-pr-review gate row named the removed AGENTS.md review
section; it now covers any text that says when a review is required or which
reviewer runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dd-octo-sts

dd-octo-sts Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

CI Test Results

Run: #43440850263 | Commit: ee04da8 | Duration: 20m 6s (longest job)

✅ All 32 test jobs passed

Status Overview

JDK glibc-aarch64/debug glibc-amd64/debug musl-aarch64/debug musl-amd64/debug
8 - ✅ - -
8-ibm - ✅ - -
8-j9 ✅ ✅ - -
8-librca - - ✅ ✅
8-orcl - ✅ - -
11 - ✅ - -
11-j9 ✅ ✅ - -
11-librca - - ✅ ✅
17 ✅ ✅ - -
17-graal ✅ ✅ - -
17-j9 ✅ ✅ - -
17-librca - - ✅ ✅
21 ✅ ✅ - -
21-graal ✅ ✅ - -
21-librca - - ✅ ✅
25 ✅ ✅ - -
25-graal ✅ ✅ - -
25-librca - - ✅ ✅

Legend: ✅ passed | ❌ failed | ⚪ skipped | 🚫 cancelled

Summary: Total: 32 | Passed: 32 | Failed: 0


Updated: 2026-11-13 14:37:55 UTC

@dd-octo-sts

dd-octo-sts Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

✅ All 40 integration tests passed

📊 Dashboard · 👷 Pipeline · 📦 f434515e

@rkennke
rkennke marked this pull request as ready for review November 12, 2026 14:22
@rkennke
rkennke requested a review from a team as a code owner November 12, 2026 14:22
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-12T14:24:41.469036Z 3999a64 Draft marked ready
ℹ️ 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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3999a644ea

ℹ️ 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".

Comment thread doc/WorkTracking.md Resolved

@datadog-prod-us1-4 datadog-prod-us1-4 Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bits Code Review: PASS

More details

Skill descriptions retain the removed procedure triggers, and reviewer selection still covers review gates in AGENTS.md and skills. Harnesses without skill discovery or hooks lose the explicit review obligation, an accepted limitation documented in the PR.

Was this helpful? React 👍 or 👎

Open Bits AI session

🤖 Bits Code Review · Commit 3999a64

rkennke and others added 2 commits November 12, 2026 14:32
Conflict in AGENTS.md: main added a sentence to the PR Descriptions section,
which this branch removes. The sentence is dropped: the pre-push hook warning
names the pr-writing skill, and the skill holds the re-verify rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The PR ticket check and the README still accept and invite GitHub-issue
contributions, so the docs keep that path until all three change together.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rkennke
rkennke requested a review from jbachorik November 12, 2026 15:29
@datadog-prod-us1-4

datadog-prod-us1-4 Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Pipelines

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

@rkennke
rkennke merged commit ee04da8 into main Nov 12, 2026
121 checks passed
@rkennke
rkennke deleted the rkennke/PROF-16586-drop-skill-pointers branch November 12, 2026 16:10
@github-actions github-actions Bot added this to the 1.53.0 milestone Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants