Repository navigation
Add ticket-writing and work-planning skills (PROF-16542) - #960
Merged
Merged
Conversation
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 <noreply@anthropic.com>
…es (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 <noreply@anthropic.com>
Contributor
Scan-Build Report
Bug Summary
Filter Results by FileReports
|
|||||||||||||||||||||||||||||||||||||||||||||||||
Contributor
CI Test ResultsRun: #42857976983 | Commit:
Status Overview
Legend: ✅ passed | ❌ failed | ⚪ skipped | 🚫 cancelled Summary: Total: 32 | Passed: 32 | Failed: 0 Updated: 2026-11-10 17:11:46 UTC |
rkennke
marked this pull request as ready for review
November 9, 2026 20:44
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![datadog-prod-us1-3[bot]](https://avatars.githubusercontent.com/u/365230?s=60&v=4){kind=small}
There was a problem hiding this comment.
The new mandatory skill in SKILL.md requires both the design and Build-plan artifacts to live in the ticket description, directly conflicting with doc/WorkTracking.md, which explicitly permits those artifacts to reside in a draft PR or a linked plan.md. The skill's amendment instruction also risks leaving the accepted plan stale or creating duplicate copies when the canonical source is outside the ticket.
🤖 Bits Code Review · Commit 0355d2d
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0355d2d6db
ℹ️ 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".
…542) 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 <noreply@anthropic.com>
…(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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
…lusive (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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…42)" This reverts commit bd2396b. 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 <noreply@anthropic.com>
There was a problem hiding this comment.
More details
The planning skills preserve the permitted artifact locations and require fresh evidence after candidate changes. The completed static review found no actionable conflicts with the tracking guidance.
🤖 Bits Code Review · Commit 91ae9f0
Contributor
…PROF-16542-planning-skills
…d 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 <noreply@anthropic.com>
/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 <noreply@anthropic.com>
jbachorik
approved these changes
Nov 11, 2026
Contributor
|
Automated review of this PR found 9 items. All are consistency issues in the new skill docs, not code defects. Not yet verified line-by-line against the final text.
|
2 of 3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?:
Adds two agent skills for the ticket and planning conventions, which the repo did not record anywhere until now:
.agents/skills/ticket-writing/:.agents/skills/work-planning/:local,test-driveorproduction-check;AGENTS.mdWork Tracking points to both skills.doc/WorkTracking.mdpoints to them and allows the design to live in the ticket description.Stacked on #959, which adds the
check-skills.pygate that these skills pass.Motivation:
These conventions lived only in the agent-configuration proposal and in how PROF-16469 and PROF-16542 were run. A fresh session did not know them. On
main, a headless session asked to draft a sub-task left it "Unassigned", which makes Jira assign the component default, another engineer. Asked about a merged PR with production checks pending, it answered "In Progress". Step 2 of PROF-16466; design on PROF-16542.Additional Notes:
ticket-writingdoes not prescribe a structure per size. A small change may live in one ticket with one PR; a large one may use a parent with sub-tickets that each carry their own design, criteria and plan.work-planningasks which human reviews a change requires or recommends, with reasons;pr-writinggains one line to state that in PR descriptions.AGENTS.mdpointer do not mention GitHub issues for external contributors. Older mentions inAGENTS.mdWork Tracking anddoc/WorkTracking.mdare unchanged.doc/WorkTracking.mdused to place the design in a draft PR. It now allows the ticket description as the one declared source of truth, matching how these tickets are run./code-review(medium) on the first commit found 10 issues: disagreements withdoc/WorkTracking.md, unclear status rules, and duplicated rules. The second commit fixes all 10./code-review(low) on the fix found nothing. No Sphinx run, because the PR changes only Markdown.work-planningforced the design and plan into the ticket, whiledoc/WorkTracking.mdallows other locations. The skill now keeps them in the ticket unless the engineer chooses a location WorkTracking.md allows. Committing a plan or design file needs permission.ticket-writinglet old evidence stand after a candidate change. A check is now re-run, and until then it isinconclusive, naming the earlier commit and its result./code-reviewrounds on these fixes kept finding new wording edges. The rounds stopped under the Add review depth, self-check and repeated-failure steps to pre-pr-review (PROF-16542) #962 stop rule.AGENTS.md, which every agent session loads, and sets new team conventions for tickets and planning.How to test the change?:
python3 utils/check-skills.pybash utils/tests/test_quality_check_scripts.shticket-writingandwork-planningin both harnessesmainvs. this branchlibrary-javaand an explicit assignee (onmain: unassigned, placeholder component); the status answer is In Review (onmain: In Progress); Build plans are a criteria table of about 370–460 words (onmain: 892 and 1375 words)For Datadog employees:
credentials of any kind, I've requested a security review (run the
dd:platform-security-reviewskill, or file a request via the PSEC review form).
bewairealso runs automatically on every PR.🤖 Generated with Claude Code