diff --git a/.agents/skills/pr-writing/SKILL.md b/.agents/skills/pr-writing/SKILL.md index 9d27ee1795..709383c3e3 100644 --- a/.agents/skills/pr-writing/SKILL.md +++ b/.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 diff --git a/.agents/skills/ticket-writing/SKILL.md b/.agents/skills/ticket-writing/SKILL.md new file mode 100644 index 0000000000..91d8c2face --- /dev/null +++ b/.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. diff --git a/.agents/skills/work-planning/SKILL.md b/.agents/skills/work-planning/SKILL.md new file mode 100644 index 0000000000..2ef1bdaf79 --- /dev/null +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md index cb9ceb465e..e37a405363 100644 --- a/AGENTS.md +++ b/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-`) 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 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.