From fd0ae5ad2602ae328f2f72fc36881a4cd1cef957 Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Mon, 9 Nov 2026 17:42:56 +0000 Subject: [PATCH 01/10] Add ticket-writing and work-planning skills (PROF-16542) The ticket and planning conventions were recorded nowhere in the repo: only in the agent-configuration proposal and in how the PROF-16469 and PROF-16542 tickets were run. Two skills now carry them and load at the moment they apply. - ticket-writing: parent Task and Sub-task shape, component, explicit assignee (Jira otherwise assigns the component default), description sections, sign-off and evidence comments, links instead of bare names, and the status each phase maps to. A merged PR with production checks pending stays In Review. - work-planning: effort proportional to size, decisions listed with a recommendation, the environments a design must name, acceptance criteria tagged local, test-drive or production-check, and a Build plan that maps criteria to checks without restating the design. AGENTS.md Work Tracking points to both skills. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/ticket-writing/SKILL.md | 72 ++++++++++++++++++++++++++ .agents/skills/work-planning/SKILL.md | 52 +++++++++++++++++++ AGENTS.md | 5 +- 3 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 .agents/skills/ticket-writing/SKILL.md create mode 100644 .agents/skills/work-planning/SKILL.md diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md new file mode 100644 index 0000000000..6d600cdf11 --- /dev/null +++ b/.agents/skills/ticket-writing/SKILL.md @@ -0,0 +1,72 @@ +--- +name: ticket-writing +description: Conventions for java-profiler Jira tickets in the PROF project, covering how to create a ticket or sub-task, write its Intent, record decisions and evidence, and move its status. Use before creating or editing a Jira ticket or posting a ticket comment, and whenever work on a ticket starts, a PR opens or merges, or its evidence is complete. +--- + +# Ticket writing + +The ticket is the system of record: anyone must be able to pick the work up from it +without the conversation. The phases are in `doc/WorkTracking.md`; this skill covers how +the ticket carries them. External contributors use GitHub issues with the same +structure; the Jira-only rules below (component, assignee, status) do not apply there. + +The `pr-writing` skill's style rules apply to every ticket text and comment. + +## Creating a ticket + +- **Shape.** A parent Task carries the problem and the direction only. Each step is a + Sub-task that carries its own Intent, Design, acceptance criteria and Build plan. + Epics are for program-level work, not for one change. +- **Component.** `library-java` for java-profiler work; `openjdk` for upstream OpenJDK + work. +- **Assignee.** Always set it explicitly. Without one, Jira assigns the component + default, which is another engineer. +- **Status.** A new ticket starts in Committed. Check the status after creating it. +- **Dedupe first.** Search for an existing ticket on the same problem, and link related + tickets instead of restating them. + +## The description + +- **Header line.** Phase, size (S/M/L) with one sentence on why, parent, and the + pattern or previous step it follows. +- **Intent.** What and why, scoped to this ticket, with the owner and the observable + outcome. Never the how. +- **Out of scope.** Name what this ticket deliberately leaves out, and where it goes. +- **Findings.** Facts from the investigation that shape the scope, each checkable + against the code. +- **Decisions.** Each decision the engineer must make is listed separately and, once + made, recorded with who made it and the date. +- Design, acceptance criteria and the Build plan follow the `work-planning` skill. +- Keep the description current: it holds the latest accepted state. History goes in + comments. + +## Comments + +- **Sign-off.** When the engineer accepts the intent, a design or a plan, post a comment + that names who accepted what, and the date. +- **Evidence.** Report every check in a table: criterion, state (`passed` / `failed` / + `blocked` / `inconclusive`), observed result. Name the exact candidate commit. Put the + interpretation in its own paragraph, after the table. +- **A changed candidate invalidates evidence.** Re-run the check, or state why the + change cannot affect it. +- **Links, not bare names.** Every commit, PR and branch is a link. A link to an + unpushed commit does not resolve, so push first, or add the links after the push. +- **No line numbers.** Refer to files and symbols; line numbers go stale. + +## Status follows the work + +| Status | When | +| --- | --- | +| Committed | Intent recorded; no work started | +| In Progress | From the start of Design through Build and Test | +| In Review | Every planned PR is open and review is requested, after the pre-PR review gate | +| Blocked | A decision or another owner stops all work on the ticket | +| Done | Every acceptance criterion has recorded evidence, including the `production-check` criteria | + +- Move the status in the same session as the event that causes it, and say so in the + comment. +- A blocked part, with other parts still moving, is recorded in a comment; the status + does not change. +- A merged PR with production checks still pending stays In Review. Its comment lists + the pending checks. Merging alone is never Done. +- Before Done, post a closing comment that maps every criterion to its evidence. diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md new file mode 100644 index 0000000000..a19b65f530 --- /dev/null +++ b/.agents/skills/work-planning/SKILL.md @@ -0,0 +1,52 @@ +--- +name: work-planning +description: Conventions for the Design, acceptance criteria and Build plan of a java-profiler ticket. Use before writing or revising a design, acceptance criteria or a Build plan, on a ticket or in a PR. +--- + +# Work planning + +The phases and their exit criteria are in `doc/WorkTracking.md`. This skill covers how +to write the two planning artifacts. Both live on the ticket (see the `ticket-writing` +skill) and are accepted by the engineer before the next phase starts. + +## Effort + +- Effort is proportional to size. An S change gets a few lines of design; an L change + gets alternatives and trade-offs. +- Keep both artifacts as short as reasonable. They are review surface, not + documentation. + +## Design + +- **Approach.** State the chosen approach and the rejected alternatives, each with the + reason. Name the constraints that shaped it. +- **Decisions.** List every decision the engineer must make separately, with the + options and a recommendation. Do not bury a decision in the prose. +- **Environments.** List every environment the change must work in: the CI image, a + clean checkout versus a working copy, local tool versions, and each supported agent + harness. An environment the design does not name is where findings come from. +- **Critical areas.** Name any critical review area the change touches (public API, + security, shared-library behavior, signal handlers, perf-critical code) and the + review it needs. + +## Acceptance criteria + +- Write them before code. Each criterion is observable and is tagged with where it is + verified: + - `local`: a hermetic test or a local run; + - `test-drive`: a fresh agent session or a real run on the candidate; + - `production-check`: observed after merge or release, with the signal and the + observation window it needs. +- Say which criteria are permanent tests, committed with the code, and which are + one-time evidence recorded on the ticket. +- A criterion changes only with the engineer's sign-off. + +## Build plan + +- Map each acceptance criterion to the check that proves it, usually as a table: + PR | scope | criteria. Say which PRs are independent and which are stacked. +- Name only what the design leaves open, and any check whose method is not obvious + (how to run it, what to compare against). +- Do not restate the intent or the design, and do not write a step-by-step blueprint + of the implementation: that detail belongs in the PRs. +- When reality diverges, amend the plan on the ticket and get the change accepted. diff --git a/AGENTS.md b/AGENTS.md index a650625bfc..eab4d38ac3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -476,7 +476,10 @@ Work runs in four phases — Intent → Design → Build and Test → Deploy — tracker ticket as the system of record: Jira (`PROF-`) for Datadog engineers, GitHub issues for external contributors. **Read [doc/WorkTracking.md](doc/WorkTracking.md) before starting tracked work** — it is the phase-by-phase process reference; skipping -it must be disclosed per the rule at the top of this file. These rules always apply: +it must be disclosed per the rule at the top of this file. Before creating, updating or +moving a Jira ticket, load the `ticket-writing` skill; before writing a design, +acceptance criteria or a Build plan, load the `work-planning` skill. These rules always +apply: - **Verification first.** No transition happens on claims: acceptance criteria before code, tests and review before merge, production verification before closure. **Fix From 0355d2d6db36dcb76a8462aab58c4693c0fd2b62 Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Mon, 9 Nov 2026 17:49:28 +0000 Subject: [PATCH 02/10] Align the planning skills with WorkTracking.md and clarify status rules (PROF-16542) - work-planning names the ticket description as the one declared source of truth, takes the critical areas from WorkTracking.md instead of a shorter copy, and asks for a rollout and recovery plan. - ticket-writing evidence names the configuration that produced it, and for production checks the deployed revision, environment and window. - Status: the ticket stays In Progress while a planned PR is still to be written; waiting for the engineer's sign-off is not Blocked; a parent Task follows its sub-tasks. - Drop the rules AGENTS.md already keeps loaded (criterion sign-off, evidence states). - WorkTracking.md allows the design in the ticket description and points to both skills; the AGENTS.md pointer covers GitHub issues and links the skill files. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/ticket-writing/SKILL.md | 18 ++++++++++++------ .agents/skills/work-planning/SKILL.md | 14 ++++++++------ AGENTS.md | 8 +++++--- doc/WorkTracking.md | 8 +++++--- 4 files changed, 30 insertions(+), 18 deletions(-) diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md index 6d600cdf11..31ef8876ae 100644 --- a/.agents/skills/ticket-writing/SKILL.md +++ b/.agents/skills/ticket-writing/SKILL.md @@ -44,11 +44,12 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. - **Sign-off.** When the engineer accepts the intent, a design or a plan, post a comment that names who accepted what, and the date. -- **Evidence.** Report every check in a table: criterion, state (`passed` / `failed` / - `blocked` / `inconclusive`), observed result. Name the exact candidate commit. Put the - interpretation in its own paragraph, after the table. -- **A changed candidate invalidates evidence.** Re-run the check, or state why the - change cannot affect it. +- **Evidence.** Report every check in a table: criterion, state, observed result. Name + what produced it: the candidate commit and the configuration (build type, platform, + harness and version); for a production check, the deployed revision, environment and + observation window. Put the interpretation in its own paragraph, after the table. +- **After the candidate changes,** re-run each check, or state why the change cannot + affect it. - **Links, not bare names.** Every commit, PR and branch is a link. A link to an unpushed commit does not resolve, so push first, or add the links after the push. - **No line numbers.** Refer to files and symbols; line numbers go stale. @@ -60,13 +61,18 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. | Committed | Intent recorded; no work started | | In Progress | From the start of Design through Build and Test | | In Review | Every planned PR is open and review is requested, after the pre-PR review gate | -| Blocked | A decision or another owner stops all work on the ticket | +| Blocked | A dependency outside the assignee's control, such as another team or an external decision, stops all work | | Done | Every acceptance criterion has recorded evidence, including the `production-check` criteria | - Move the status in the same session as the event that causes it, and say so in the comment. +- While a planned PR is still to be written, the ticket stays In Progress, even if + earlier PRs, such as the first of a stack, are already in review. +- Waiting for the engineer's sign-off on a design or a decision is not Blocked. - A blocked part, with other parts still moving, is recorded in a comment; the status does not change. +- A parent Task is In Progress while any of its sub-tasks is, and Done when all of + them are Done. - A merged PR with production checks still pending stays In Review. Its comment lists the pending checks. Merging alone is never Done. - Before Done, post a closing comment that maps every criterion to its evidence. diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md index a19b65f530..8419a04d02 100644 --- a/.agents/skills/work-planning/SKILL.md +++ b/.agents/skills/work-planning/SKILL.md @@ -6,8 +6,9 @@ description: Conventions for the Design, acceptance criteria and Build plan of a # Work planning The phases and their exit criteria are in `doc/WorkTracking.md`. This skill covers how -to write the two planning artifacts. Both live on the ticket (see the `ticket-writing` -skill) and are accepted by the engineer before the next phase starts. +to write the two planning artifacts. Both live in the ticket description, which is +their one declared source of truth (see the `ticket-writing` skill), and the engineer +accepts each before the next phase starts. ## Effort @@ -25,9 +26,11 @@ skill) and are accepted by the engineer before the next phase starts. - **Environments.** List every environment the change must work in: the CI image, a clean checkout versus a working copy, local tool versions, and each supported agent harness. An environment the design does not name is where findings come from. -- **Critical areas.** Name any critical review area the change touches (public API, - security, shared-library behavior, signal handlers, perf-critical code) and the - review it needs. +- **Critical areas.** Name each critical area from `doc/WorkTracking.md` the change + touches, and signal-handler code (the AGENTS.md Critical Invariants), with the review + each needs. +- **Rollout and recovery.** State how the change reaches users, and how to stop or + revert it if a production check fails. ## Acceptance criteria @@ -39,7 +42,6 @@ skill) and are accepted by the engineer before the next phase starts. observation window it needs. - Say which criteria are permanent tests, committed with the code, and which are one-time evidence recorded on the ticket. -- A criterion changes only with the engineer's sign-off. ## Build plan diff --git a/AGENTS.md b/AGENTS.md index eab4d38ac3..a5ccd3b4cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -477,9 +477,11 @@ tracker ticket as the system of record: Jira (`PROF-`) for Datadog engineers, GitHub issues for external contributors. **Read [doc/WorkTracking.md](doc/WorkTracking.md) before starting tracked work** — it is the phase-by-phase process reference; skipping it must be disclosed per the rule at the top of this file. Before creating, updating or -moving a Jira ticket, load the `ticket-writing` skill; before writing a design, -acceptance criteria or a Build plan, load the `work-planning` skill. These rules always -apply: +moving a Jira ticket or GitHub issue, load the `ticket-writing` skill +([.agents/skills/ticket-writing/SKILL.md](.agents/skills/ticket-writing/SKILL.md)); before +writing a design, acceptance criteria or a Build plan, load the `work-planning` skill +([.agents/skills/work-planning/SKILL.md](.agents/skills/work-planning/SKILL.md)). These +rules always apply: - **Verification first.** No transition happens on claims: acceptance criteria before code, tests and review before merge, production verification before closure. **Fix diff --git a/doc/WorkTracking.md b/doc/WorkTracking.md index 621e6d3708..eef8fbba03 100644 --- a/doc/WorkTracking.md +++ b/doc/WorkTracking.md @@ -12,7 +12,8 @@ Work runs in four phases — Intent → Design → Build and Test → Deploy — tracker ticket as the system of record: decisions and evidence land there, so anyone can pick the work up without reconstructing a conversation. Datadog engineers track work in Jira (`PROF-`); external contributors use GitHub -issues. +issues. How to write the ticket, the design and the Build plan is in the +`ticket-writing` and `work-planning` agent skills (`.agents/skills/`). ## Intent — what and why @@ -44,8 +45,9 @@ Turn the intent into a proposed solution and a way to verify it. - Human: review trade-offs and assumptions. Engineer steering is mandatory on critical areas: public API, security, formal models, shared-library behavior, schema migrations, new dependencies, perf-critical code. -- Sizing (S/M/L) drives design depth. Output: the design (markdown in a draft - PR), the acceptance criteria, and the identified review requirements. +- Sizing (S/M/L) drives design depth. Output: the design (in the ticket + description, or markdown in a draft PR — one declared source of truth), the + acceptance criteria, and the identified review requirements. - Build-ready when: approach clear enough to implement, verification plan feasible, blocking questions and required alignment resolved. From 624f79917e0313432a4a29ef86f28462e07a6b0b Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Mon, 9 Nov 2026 21:43:45 +0000 Subject: [PATCH 03/10] Honor the planning-artifact locations and evidence invariant (PROF-16542) Codex and Bits review findings on the planning skills: - work-planning forced the design and Build plan into the ticket description. doc/WorkTracking.md also allows a draft PR for the design and a versioned plan.md for the plan. The skill now keeps each artifact in its one declared source of truth, with the ticket as the default, and amends the plan there. - ticket-writing let an agent keep old evidence after the candidate changed, given an explanation. AGENTS.md says a changed candidate invalidates evidence. Checks are now re-run on the new candidate; results from an earlier commit are reported as such. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/ticket-writing/SKILL.md | 4 ++-- .agents/skills/work-planning/SKILL.md | 11 +++++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md index 31ef8876ae..22967ebd69 100644 --- a/.agents/skills/ticket-writing/SKILL.md +++ b/.agents/skills/ticket-writing/SKILL.md @@ -48,8 +48,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. what produced it: the candidate commit and the configuration (build type, platform, harness and version); for a production check, the deployed revision, environment and observation window. Put the interpretation in its own paragraph, after the table. -- **After the candidate changes,** re-run each check, or state why the change cannot - affect it. +- **After the candidate changes,** re-run each check on the new candidate before you + report it as passed. Results from an earlier commit are reported as such. - **Links, not bare names.** Every commit, PR and branch is a link. A link to an unpushed commit does not resolve, so push first, or add the links after the push. - **No line numbers.** Refer to files and symbols; line numbers go stale. diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md index 8419a04d02..7008282245 100644 --- a/.agents/skills/work-planning/SKILL.md +++ b/.agents/skills/work-planning/SKILL.md @@ -6,9 +6,11 @@ description: Conventions for the Design, acceptance criteria and Build plan of a # Work planning The phases and their exit criteria are in `doc/WorkTracking.md`. This skill covers how -to write the two planning artifacts. Both live in the ticket description, which is -their one declared source of truth (see the `ticket-writing` skill), and the engineer -accepts each before the next phase starts. +to write the two planning artifacts. Keep each in one declared source of truth: the +design in the ticket description or a draft PR, the Build plan in the ticket +description or a versioned `plan.md` linked from the ticket. The ticket description +is the default (see the `ticket-writing` skill). The engineer accepts each artifact +before the next phase starts. ## Effort @@ -51,4 +53,5 @@ accepts each before the next phase starts. (how to run it, what to compare against). - Do not restate the intent or the design, and do not write a step-by-step blueprint of the implementation: that detail belongs in the PRs. -- When reality diverges, amend the plan on the ticket and get the change accepted. +- When reality diverges, amend the plan in its source of truth and get the change + accepted. From 8343e410a2d87a800d76bf823712a8e68a8f5512 Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Mon, 9 Nov 2026 21:46:21 +0000 Subject: [PATCH 04/10] Make the ticket the default planning location and map stale evidence (PROF-16542) Review findings on the previous commit: - Offering a "versioned plan.md" on equal footing conflicted with the AGENTS.md rule that plans are never committed without permission. The ticket description is now the default for the design, the acceptance criteria and the Build plan. A draft PR or plan.md is used only when the engineer chooses it, is linked from the ticket and the PR, and a plan.md is committed only with permission. ticket-writing's sub-task shape allows those links. - Amendments cover the design as well as the plan. - A result from an earlier commit is reported as inconclusive for the new candidate, naming its commit, until the check is re-run: one of the four evidence states, not prose. Accepted cost: any candidate change, including a comment fix, needs the checks re-run before they are reported as passed. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/ticket-writing/SKILL.md | 6 ++++-- .agents/skills/work-planning/SKILL.md | 15 ++++++++------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md index 22967ebd69..d6763e9088 100644 --- a/.agents/skills/ticket-writing/SKILL.md +++ b/.agents/skills/ticket-writing/SKILL.md @@ -15,7 +15,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. ## Creating a ticket - **Shape.** A parent Task carries the problem and the direction only. Each step is a - Sub-task that carries its own Intent, Design, acceptance criteria and Build plan. + Sub-task that carries its own Intent, Design, acceptance criteria and Build plan, or + links to them where the `work-planning` skill allows. Epics are for program-level work, not for one change. - **Component.** `library-java` for java-profiler work; `openjdk` for upstream OpenJDK work. @@ -49,7 +50,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. harness and version); for a production check, the deployed revision, environment and observation window. Put the interpretation in its own paragraph, after the table. - **After the candidate changes,** re-run each check on the new candidate before you - report it as passed. Results from an earlier commit are reported as such. + report it as passed. Until then, report it as `inconclusive` for the new candidate + and name the commit the result came from. - **Links, not bare names.** Every commit, PR and branch is a link. A link to an unpushed commit does not resolve, so push first, or add the links after the push. - **No line numbers.** Refer to files and symbols; line numbers go stale. diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md index 7008282245..b129b2aebe 100644 --- a/.agents/skills/work-planning/SKILL.md +++ b/.agents/skills/work-planning/SKILL.md @@ -6,11 +6,12 @@ description: Conventions for the Design, acceptance criteria and Build plan of a # Work planning The phases and their exit criteria are in `doc/WorkTracking.md`. This skill covers how -to write the two planning artifacts. Keep each in one declared source of truth: the -design in the ticket description or a draft PR, the Build plan in the ticket -description or a versioned `plan.md` linked from the ticket. The ticket description -is the default (see the `ticket-writing` skill). The engineer accepts each artifact -before the next phase starts. +to write the two planning artifacts and the acceptance criteria. Keep each in one +source of truth: the ticket description by default (see the `ticket-writing` skill). +`doc/WorkTracking.md` also allows the design in a draft PR and the Build plan in a +`plan.md`; use those only when the engineer chooses them, link them from the ticket +description and the PR, and commit a `plan.md` only with the engineer's permission. +The engineer accepts each artifact before the next phase starts. ## Effort @@ -53,5 +54,5 @@ before the next phase starts. (how to run it, what to compare against). - Do not restate the intent or the design, and do not write a step-by-step blueprint of the implementation: that detail belongs in the PRs. -- When reality diverges, amend the plan in its source of truth and get the change - accepted. +- When reality diverges, amend the design or plan in its source of truth and get the + change accepted. From 8cfa300eb172daffc4d50d85a6b02a7aa1a921d6 Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Mon, 9 Nov 2026 21:48:10 +0000 Subject: [PATCH 05/10] Keep stale failures visible and close the plan.md gap (PROF-16542) - A stale passed result becomes inconclusive for a new candidate; a failed result stays failed, so a known failure is never hidden. - Only the Design and Build plan may be links on a Sub-task; Intent and acceptance criteria stay on the ticket. - A plan.md must be committed to be linkable, which needs the engineer's permission; without it the plan stays in the ticket. The draft-PR design is linked from the ticket, not from itself. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/ticket-writing/SKILL.md | 9 +++++---- .agents/skills/work-planning/SKILL.md | 5 +++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md index d6763e9088..2aa68059aa 100644 --- a/.agents/skills/ticket-writing/SKILL.md +++ b/.agents/skills/ticket-writing/SKILL.md @@ -15,8 +15,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. ## Creating a ticket - **Shape.** A parent Task carries the problem and the direction only. Each step is a - Sub-task that carries its own Intent, Design, acceptance criteria and Build plan, or - links to them where the `work-planning` skill allows. + Sub-task that carries its own Intent, Design, acceptance criteria and Build plan; the + Design and Build plan may instead be links, where the `work-planning` skill allows. Epics are for program-level work, not for one change. - **Component.** `library-java` for java-profiler work; `openjdk` for upstream OpenJDK work. @@ -50,8 +50,9 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. harness and version); for a production check, the deployed revision, environment and observation window. Put the interpretation in its own paragraph, after the table. - **After the candidate changes,** re-run each check on the new candidate before you - report it as passed. Until then, report it as `inconclusive` for the new candidate - and name the commit the result came from. + report it as passed. Until then, a `passed` result from an earlier commit is + `inconclusive` for the new candidate, naming that commit; a `failed` result stays + `failed`. - **Links, not bare names.** Every commit, PR and branch is a link. A link to an unpushed commit does not resolve, so push first, or add the links after the push. - **No line numbers.** Refer to files and symbols; line numbers go stale. diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md index b129b2aebe..3add1ab807 100644 --- a/.agents/skills/work-planning/SKILL.md +++ b/.agents/skills/work-planning/SKILL.md @@ -9,8 +9,9 @@ The phases and their exit criteria are in `doc/WorkTracking.md`. This skill cove to write the two planning artifacts and the acceptance criteria. Keep each in one source of truth: the ticket description by default (see the `ticket-writing` skill). `doc/WorkTracking.md` also allows the design in a draft PR and the Build plan in a -`plan.md`; use those only when the engineer chooses them, link them from the ticket -description and the PR, and commit a `plan.md` only with the engineer's permission. +`plan.md`; use those only when the engineer chooses them, and link them from the +ticket description. A `plan.md` must be committed, which needs the engineer's +permission; without it, keep the plan in the ticket. The engineer accepts each artifact before the next phase starts. ## Effort From 01fc574e07897d10e70202a49eb2e12dd904ec2c Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Tue, 10 Nov 2026 14:48:28 +0000 Subject: [PATCH 06/10] Defer planning locations to WorkTracking.md; stale results are inconclusive (PROF-16542) Each review round found a new conflict between the skill's own location rules, doc/WorkTracking.md and the AGENTS.md rule against committing plans. The skill now keeps the artifacts in the ticket description, unless the engineer chooses another location WorkTracking.md allows, and says that committing a plan or design file needs permission. It no longer restates WorkTracking.md's options. A check result from an earlier commit, passed or failed, is reported as inconclusive for the new candidate, naming that commit and its result. This follows the invariant that a changed candidate invalidates evidence, without hiding an earlier failure. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/ticket-writing/SKILL.md | 9 ++++----- .agents/skills/work-planning/SKILL.md | 11 ++++------- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md index 2aa68059aa..d568182c60 100644 --- a/.agents/skills/ticket-writing/SKILL.md +++ b/.agents/skills/ticket-writing/SKILL.md @@ -15,8 +15,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. ## Creating a ticket - **Shape.** A parent Task carries the problem and the direction only. Each step is a - Sub-task that carries its own Intent, Design, acceptance criteria and Build plan; the - Design and Build plan may instead be links, where the `work-planning` skill allows. + Sub-task that carries its own Intent, Design, acceptance criteria and Build plan, + unless the `work-planning` skill places them elsewhere. Epics are for program-level work, not for one change. - **Component.** `library-java` for java-profiler work; `openjdk` for upstream OpenJDK work. @@ -50,9 +50,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. harness and version); for a production check, the deployed revision, environment and observation window. Put the interpretation in its own paragraph, after the table. - **After the candidate changes,** re-run each check on the new candidate before you - report it as passed. Until then, a `passed` result from an earlier commit is - `inconclusive` for the new candidate, naming that commit; a `failed` result stays - `failed`. + report it as passed. Until then, report the check as `inconclusive` for the new + candidate, and name the earlier commit and its result. - **Links, not bare names.** Every commit, PR and branch is a link. A link to an unpushed commit does not resolve, so push first, or add the links after the push. - **No line numbers.** Refer to files and symbols; line numbers go stale. diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md index 3add1ab807..013be2d4a9 100644 --- a/.agents/skills/work-planning/SKILL.md +++ b/.agents/skills/work-planning/SKILL.md @@ -6,13 +6,10 @@ description: Conventions for the Design, acceptance criteria and Build plan of a # Work planning The phases and their exit criteria are in `doc/WorkTracking.md`. This skill covers how -to write the two planning artifacts and the acceptance criteria. Keep each in one -source of truth: the ticket description by default (see the `ticket-writing` skill). -`doc/WorkTracking.md` also allows the design in a draft PR and the Build plan in a -`plan.md`; use those only when the engineer chooses them, and link them from the -ticket description. A `plan.md` must be committed, which needs the engineer's -permission; without it, keep the plan in the ticket. -The engineer accepts each artifact before the next phase starts. +to write the two planning artifacts and the acceptance criteria. Keep them in the +ticket description, unless the engineer chooses another location that +`doc/WorkTracking.md` allows. Committing a plan or design file needs the engineer's +permission (AGENTS.md). The engineer accepts each artifact before the next phase starts. ## Effort From bd2396b3afba847ed24e814b4d64465309615cd8 Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Tue, 10 Nov 2026 14:53:33 +0000 Subject: [PATCH 07/10] Link the AI Native SDLC Playbook from Work Tracking (PROF-16542) The work-tracking process, the skills and the agent-configuration rules follow the Datadog AI Native SDLC Playbook. AGENTS.md now links it from the Work Tracking section, scoped to planning tracked work, changing the process, and changing the agent configuration, so other tasks do not open it. The link is Datadog-internal. The text says so and that it is kept on purpose: the repo is public so that customers can inspect the code that runs in their processes, and it takes no outside contributions to the process, so a link outsiders cannot open does no harm. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a5ccd3b4cc..10d96bca97 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -480,8 +480,11 @@ it must be disclosed per the rule at the top of this file. Before creating, upda moving a Jira ticket or GitHub issue, load the `ticket-writing` skill ([.agents/skills/ticket-writing/SKILL.md](.agents/skills/ticket-writing/SKILL.md)); before writing a design, acceptance criteria or a Build plan, load the `work-planning` skill -([.agents/skills/work-planning/SKILL.md](.agents/skills/work-planning/SKILL.md)). These -rules always apply: +([.agents/skills/work-planning/SKILL.md](.agents/skills/work-planning/SKILL.md)). +The process follows the [Datadog AI Native SDLC Playbook](https://datadoghq.atlassian.net/wiki/spaces/ENG/pages/7376601403/Datadog+AI+Native+SDLC+Playbook) +(Datadog-internal link, kept on purpose; outside readers cannot open it). Open it only +when planning tracked work, changing this process, or changing the agent configuration +(this file, skills, hooks). These rules always apply: - **Verification first.** No transition happens on claims: acceptance criteria before code, tests and review before merge, production verification before closure. **Fix From 91ae9f0cd329a7bff16f36fd1d648c80851a678d Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Tue, 10 Nov 2026 14:55:57 +0000 Subject: [PATCH 08/10] Revert "Link the AI Native SDLC Playbook from Work Tracking (PROF-16542)" This reverts commit bd2396b3a. The link is an explicit exception to keeping internal links out of the public repo, unrelated to the skills in this PR, so it moves to its own PR under PROF-16466. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 10d96bca97..a5ccd3b4cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -480,11 +480,8 @@ it must be disclosed per the rule at the top of this file. Before creating, upda moving a Jira ticket or GitHub issue, load the `ticket-writing` skill ([.agents/skills/ticket-writing/SKILL.md](.agents/skills/ticket-writing/SKILL.md)); before writing a design, acceptance criteria or a Build plan, load the `work-planning` skill -([.agents/skills/work-planning/SKILL.md](.agents/skills/work-planning/SKILL.md)). -The process follows the [Datadog AI Native SDLC Playbook](https://datadoghq.atlassian.net/wiki/spaces/ENG/pages/7376601403/Datadog+AI+Native+SDLC+Playbook) -(Datadog-internal link, kept on purpose; outside readers cannot open it). Open it only -when planning tracked work, changing this process, or changing the agent configuration -(this file, skills, hooks). These rules always apply: +([.agents/skills/work-planning/SKILL.md](.agents/skills/work-planning/SKILL.md)). These +rules always apply: - **Verification first.** No transition happens on claims: acceptance criteria before code, tests and review before merge, production verification before closure. **Fix From f81430e0313de33a8982aa2a50835659a86d71af Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Tue, 10 Nov 2026 16:43:36 +0000 Subject: [PATCH 09/10] Drop external contributors, size the ticket layout by judgment, record review needs (PROF-16542) - The repo takes no outside contributions, so ticket-writing and its AGENTS.md pointer no longer mention GitHub issues for external contributors. - ticket-writing's Shape rule no longer prescribes a parent Task with a Sub-task per step. The layout fits the size of the work by judgment: one ticket and one PR for a small change, a parent with sub-tickets and several PRs for a large one. - work-planning's design names the human reviews a change requires or recommends, with reasons; pr-writing repeats that under Additional Notes, because reviewers read the PR, not the ticket. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/pr-writing/SKILL.md | 2 ++ .agents/skills/ticket-writing/SKILL.md | 12 ++++++------ .agents/skills/work-planning/SKILL.md | 8 +++++--- AGENTS.md | 2 +- 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/.agents/skills/pr-writing/SKILL.md b/.agents/skills/pr-writing/SKILL.md index 9d27ee1795..c7d22b4f57 100644 --- a/.agents/skills/pr-writing/SKILL.md +++ b/.agents/skills/pr-writing/SKILL.md @@ -40,6 +40,8 @@ or say they are from an earlier commit. scopes) or accepts a recurring per-call or footprint cost, state the decision and the accepted cost explicitly and flag it for reviewer acknowledgment — never leave it implicit in code, a test rename, or a leftover template marker. +- **Human review.** Under Additional Notes, state whether human review is required or + recommended, and why, as the ticket's design records it. - **Only the final state matters.** Never include ephemeral working knowledge — investigation detours, dead-end hypotheses, intermediate states, tool runs, session history. If a detail did not survive into the final change, it does not diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md index d568182c60..8e0617b780 100644 --- a/.agents/skills/ticket-writing/SKILL.md +++ b/.agents/skills/ticket-writing/SKILL.md @@ -7,17 +7,17 @@ description: Conventions for java-profiler Jira tickets in the PROF project, cov The ticket is the system of record: anyone must be able to pick the work up from it without the conversation. The phases are in `doc/WorkTracking.md`; this skill covers how -the ticket carries them. External contributors use GitHub issues with the same -structure; the Jira-only rules below (component, assignee, status) do not apply there. +the ticket carries them. The `pr-writing` skill's style rules apply to every ticket text and comment. ## Creating a ticket -- **Shape.** A parent Task carries the problem and the direction only. Each step is a - Sub-task that carries its own Intent, Design, acceptance criteria and Build plan, - unless the `work-planning` skill places them elsewhere. - Epics are for program-level work, not for one change. +- **Shape.** Fit the layout to the size of the work, by judgment. A small change may + keep its Intent, Design, acceptance criteria and evidence in one ticket with one PR. + A large one may use a parent ticket for the problem and direction, with sub-tickets + that each carry their own plan and one or more PRs. Epics are for program-level work, + not for one change. - **Component.** `library-java` for java-profiler work; `openjdk` for upstream OpenJDK work. - **Assignee.** Always set it explicitly. Without one, Jira assigns the component diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md index 013be2d4a9..e19c29d3fa 100644 --- a/.agents/skills/work-planning/SKILL.md +++ b/.agents/skills/work-planning/SKILL.md @@ -27,9 +27,11 @@ permission (AGENTS.md). The engineer accepts each artifact before the next phase - **Environments.** List every environment the change must work in: the CI image, a clean checkout versus a working copy, local tool versions, and each supported agent harness. An environment the design does not name is where findings come from. -- **Critical areas.** Name each critical area from `doc/WorkTracking.md` the change - touches, and signal-handler code (the AGENTS.md Critical Invariants), with the review - each needs. +- **Critical areas and human review.** Name each critical area from + `doc/WorkTracking.md` the change touches, and signal-handler code (the AGENTS.md + Critical Invariants). State which human reviews are required (for example a second + profiling reviewer for `.claude/settings.json`) and which are recommended (for + example for `AGENTS.md` changes, which every session loads), each with its reason. - **Rollout and recovery.** State how the change reaches users, and how to stop or revert it if a production check fails. diff --git a/AGENTS.md b/AGENTS.md index 730b7bb5c4..e37a405363 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -477,7 +477,7 @@ tracker ticket as the system of record: Jira (`PROF-`) for Datadog engineers, GitHub issues for external contributors. **Read [doc/WorkTracking.md](doc/WorkTracking.md) before starting tracked work** — it is the phase-by-phase process reference; skipping it must be disclosed per the rule at the top of this file. Before creating, updating or -moving a Jira ticket or GitHub issue, load the `ticket-writing` skill +moving a Jira ticket, load the `ticket-writing` skill ([.agents/skills/ticket-writing/SKILL.md](.agents/skills/ticket-writing/SKILL.md)); before writing a design, acceptance criteria or a Build plan, load the `work-planning` skill ([.agents/skills/work-planning/SKILL.md](.agents/skills/work-planning/SKILL.md)). These From d275af757d51f195960345b0c36f386929587e9e Mon Sep 17 00:00:00 2001 From: Roman Kennke Date: Tue, 10 Nov 2026 16:45:27 +0000 Subject: [PATCH 10/10] Restore what a sub-ticket carries; scope the review rules (PROF-16542) /code-review findings on the previous commit: - Sub-tickets again carry their own Design, acceptance criteria and Build plan, or link them where work-planning allows, so every step keeps criteria to verify. - The status rule and the header line no longer assume a parent Task with Jira Sub-tasks: a parent ticket follows its child tickets, and the header names a parent only when there is one. - work-planning no longer cites a second reviewer for .claude/settings.json as an example; no rule in the repo requires it. - pr-writing's human-review line applies to descriptions only; without a recorded requirement, the agent states its own assessment. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/pr-writing/SKILL.md | 5 +++-- .agents/skills/ticket-writing/SKILL.md | 11 ++++++----- .agents/skills/work-planning/SKILL.md | 6 +++--- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/.agents/skills/pr-writing/SKILL.md b/.agents/skills/pr-writing/SKILL.md index c7d22b4f57..709383c3e3 100644 --- a/.agents/skills/pr-writing/SKILL.md +++ b/.agents/skills/pr-writing/SKILL.md @@ -40,8 +40,9 @@ or say they are from an earlier commit. scopes) or accepts a recurring per-call or footprint cost, state the decision and the accepted cost explicitly and flag it for reviewer acknowledgment — never leave it implicit in code, a test rename, or a leftover template marker. -- **Human review.** Under Additional Notes, state whether human review is required or - recommended, and why, as the ticket's design records it. +- **Human review** (descriptions only). Under Additional Notes, state whether human + review is required or recommended, and why, as the ticket's design records it. If the + ticket records none, state your own assessment. - **Only the final state matters.** Never include ephemeral working knowledge — investigation detours, dead-end hypotheses, intermediate states, tool runs, session history. If a detail did not survive into the final change, it does not diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md index 8e0617b780..91d8c2face 100644 --- a/.agents/skills/ticket-writing/SKILL.md +++ b/.agents/skills/ticket-writing/SKILL.md @@ -16,7 +16,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. - **Shape.** Fit the layout to the size of the work, by judgment. A small change may keep its Intent, Design, acceptance criteria and evidence in one ticket with one PR. A large one may use a parent ticket for the problem and direction, with sub-tickets - that each carry their own plan and one or more PRs. Epics are for program-level work, + that each carry their own Design, acceptance criteria and Build plan (or link them, + as the `work-planning` skill allows) and one or more PRs. Epics are for program-level work, not for one change. - **Component.** `library-java` for java-profiler work; `openjdk` for upstream OpenJDK work. @@ -28,8 +29,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. ## The description -- **Header line.** Phase, size (S/M/L) with one sentence on why, parent, and the - pattern or previous step it follows. +- **Header line.** Phase, size (S/M/L) with one sentence on why, the parent if any, + and the pattern or previous step it follows. - **Intent.** What and why, scoped to this ticket, with the owner and the observable outcome. Never the how. - **Out of scope.** Name what this ticket deliberately leaves out, and where it goes. @@ -73,8 +74,8 @@ The `pr-writing` skill's style rules apply to every ticket text and comment. - Waiting for the engineer's sign-off on a design or a decision is not Blocked. - A blocked part, with other parts still moving, is recorded in a comment; the status does not change. -- A parent Task is In Progress while any of its sub-tasks is, and Done when all of - them are Done. +- A parent ticket is In Progress while any of its child tickets is, and Done when all + of them are Done. - A merged PR with production checks still pending stays In Review. Its comment lists the pending checks. Merging alone is never Done. - Before Done, post a closing comment that maps every criterion to its evidence. diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md index e19c29d3fa..2ef1bdaf79 100644 --- a/.agents/skills/work-planning/SKILL.md +++ b/.agents/skills/work-planning/SKILL.md @@ -29,9 +29,9 @@ permission (AGENTS.md). The engineer accepts each artifact before the next phase harness. An environment the design does not name is where findings come from. - **Critical areas and human review.** Name each critical area from `doc/WorkTracking.md` the change touches, and signal-handler code (the AGENTS.md - Critical Invariants). State which human reviews are required (for example a second - profiling reviewer for `.claude/settings.json`) and which are recommended (for - example for `AGENTS.md` changes, which every session loads), each with its reason. + Critical Invariants). State which human reviews are required (for example for a + critical area) and which are recommended (for example for `AGENTS.md` changes, which + every session loads), each with its reason. - **Rollout and recovery.** State how the change reaches users, and how to stop or revert it if a production check fails.