Add ticket-writing and work-planning skills (PROF-16542)

.agents/skills/pr-writing/SKILL.md

@@ -40,6 +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** (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

.agents/skills/ticket-writing/SKILL.md

@@ -0,0 +1,81 @@
+---
+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.
+
+The `pr-writing` skill's style rules apply to every ticket text and comment.
+
+## Creating a ticket
+
+- **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 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.
+- **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, 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.
+- **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, 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 on the new candidate before you
+  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.
+
+## 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 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 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.

.agents/skills/work-planning/SKILL.md

@@ -0,0 +1,58 @@
+---
+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 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
+
+- 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 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 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.
+
+## 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.
+
+## 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 design or plan in its source of truth and get the
+  change accepted.

AGENTS.md

@@ -476,7 +476,12 @@ Work runs in four phases — Intent → Design → Build and Test → Deploy —
 tracker ticket as the system of record: Jira (`PROF-<n>`) 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
+([.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

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-<n>`); 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.