From 80b9a38b286d6651a2171db24278a0391b90acb9 Mon Sep 17 00:00:00 2001 From: Severin Kohler Date: Fri, 16 Oct 2026 13:24:27 +0200 Subject: [PATCH 1/2] feat(openehr-specs): add tracker-writing skill for Jira and PR text --- CHANGELOG.md | 4 + plugins/openehr-specs/README.md | 1 + .../skills/tracker-writing/SKILL.md | 133 ++++++++++++++++++ .../tracker-writing/references/examples.md | 93 ++++++++++++ 4 files changed, 231 insertions(+) create mode 100644 plugins/openehr-specs/skills/tracker-writing/SKILL.md create mode 100644 plugins/openehr-specs/skills/tracker-writing/references/examples.md diff --git a/CHANGELOG.md b/CHANGELOG.md index fc8a128..9b43163 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ Notable changes to the plugins in this repository. The format follows [Keep a Ch ## Unreleased +### Added + +- `tracker-writing` skill: Jira issues, Jira comments and GitHub pull request bodies in a fixed structure with hard word caps (issue 120, PR 80, comment 40). When content does not fit, the agent shows the draft and asks before posting; it never cuts silently. Before/after examples in `references/examples.md`. + ## openehr-specs 0.6.0 (2026-10-09) ### Added diff --git a/plugins/openehr-specs/README.md b/plugins/openehr-specs/README.md index a75e6ef..7fb69d9 100644 --- a/plugins/openehr-specs/README.md +++ b/plugins/openehr-specs/README.md @@ -29,6 +29,7 @@ Add the marketplace from this repository (or a fork), then install `openehr-spec | `its-rest` | ITS-REST OpenAPI YAML and operation descriptions | | `class-generation` | Generate class tables and UML diagrams from BMM via `bmm-publisher` | | `bmm-authoring` | Write or change a component's BMM schema (P_BMM JSON) and check it before rendering (needs `python3`) | +| `tracker-writing` | Jira issues, Jira comments and GitHub pull requests: hard caps (120/80/40 words), fixed structure, ask before going over | ### User-only action skills diff --git a/plugins/openehr-specs/skills/tracker-writing/SKILL.md b/plugins/openehr-specs/skills/tracker-writing/SKILL.md new file mode 100644 index 0000000..c68d996 --- /dev/null +++ b/plugins/openehr-specs/skills/tracker-writing/SKILL.md @@ -0,0 +1,133 @@ +--- +name: tracker-writing +description: > + Write Jira issues, Jira comments, and GitHub pull request titles and bodies for the openEHR + specification trackers and repos. Use whenever text is about to be posted to Jira or GitHub: + create or edit an issue, comment, open a PR, write a review comment. Hard length caps, a fixed + structure per text type, ask before going over. Not for commit messages (repo AGENTS.md), + amendment entries (amendment-record), or spec prose (authoring, content-patterns). +argument-hint: "[issue | comment | pr] - what the text is about" +--- + +# Tracker Writing: Jira issues, comments and pull requests + +Text posted to a tracker is read by busy SEC members on a phone, in a notification, or in a +list of fifty issues. Every word they do not need costs attention. This skill makes every +Jira issue, Jira comment and GitHub PR short, structured the same way, and precise. + +## Style + +- **Clear.** One idea per sentence. Say what is wrong, where, and what should change. +- **Precise.** Name the class, attribute, section or file. Quote the exact wording in question. + Never paraphrase a spec statement when the exact words fit. +- **Consistent.** Same structure every time, same order of parts, same labels. A reader who has + seen one of our tickets can scan the next one. +- **Not wordy.** No preamble, no restating what the reader already sees (the title, the diff, + the parent ticket), no "please note", no closing thanks, no explanation of how the text was + produced. Facts and asks only. + +## Hard caps + +| Text | Cap | Counted on | +|---|---|---| +| Jira issue body | **120 words** | description field, all parts together | +| Pull request body | **80 words** | PR description | +| Jira comment / PR review comment | **40 words** | comment body | +| Jira summary / PR title | **80 characters** | one line, no trailing period | + +Counting: every whitespace-separated token is a word; a URL or an issue key counts as one. +Code spans count. Headings and list markers do not. + +The caps are hard. The agent does not post text that exceeds them. When the content cannot +fit without dropping something the reader needs, follow **Over the cap** below. + +## Over the cap + +Some texts legitimately need more: a design proposal with options and a fallback, a +reproduction with several steps, a review that lists many defects. The rule is: + +1. Draft the text in the short form first. Remove context, repetition and hedging before + removing facts. +2. If it still does not fit, **do not post**. Show the user the draft with its word count and ask + one question: post the long form as is, or drop named parts to fit the cap. +3. Post what the user chooses. Never cut silently, and never post a long form without that + confirmation. + +A long form that was approved keeps the same structure, opens with a one-line TL;DR, and keeps +each part to one paragraph. + +## Structure per text type + +Use these parts, in this order, with these labels. Omit a part only when it is empty; never add +parts. + +### Jira issue (problem report or change request) + +``` + + +Where: ,
[, file path] +Change: +Origin: +``` + +Summary line: `: `. Examples: +`EHR Extract: EXTRACT_SPEC.priority should be a coded value`, +`ADL2: single regex String constraint instead of value list?`. + +A question to a person goes in the Change line as a plain question, not a paragraph. The +assignee is set in the field, not in the text. + +### Jira comment + +``` +. .[ ] +``` + +Examples: +`Resolved Won't Do. SM component retired by SEC decision 2026-10-09.` +`Fixed by PR specifications-TERM #28 (merged 2026-10-16). Resolving.` +`Proposal: remove the five service classes from the RM; fallback is P_BMM_INTERFACE. Remove, or interface?` + +Mention a person with @ only when their answer is needed. + +### Pull request + +Title: `: ` for one ticket, `/: ...` for several, or +` (editorial)` when there is no ticket. Match the commit convention in the repo's +`AGENTS.md` when it differs. + +Body: + +``` + +Why: +Amendment record: > +[Check: ] +``` + +Do not list the changed files, the diff shows them. Do not add a checklist unless the reviewer +has to tick something. + +### PR review comment + +Same form as a Jira comment: the defect, the fix, in one or two sentences. Quote the line only +when the position does not identify it. + +## Batches + +When creating several issues or comments from one task (a clean-up sweep, a review with many +findings), the shared context is written once: in the first issue, in a parent or linking +ticket, or in the PR. Each individual issue carries only what differs: the location and the +specific point. Never repeat an origin paragraph or a question paragraph across a batch. + +## Before posting + +- Word count within the cap, or the user has approved the long form. +- First line stands alone: a reader who stops there knows the defect or the action. +- Every identifier (class, attribute, section, key, PR number) is one the agent has seen in the + repo, the spec, or the tracker. No invented keys. +- No part repeats the title, the diff, or the parent ticket. +- Labels, assignee, component, priority are set in fields, not described in the text. + +Worked before/after examples are in **`references/examples.md`**. diff --git a/plugins/openehr-specs/skills/tracker-writing/references/examples.md b/plugins/openehr-specs/skills/tracker-writing/references/examples.md new file mode 100644 index 0000000..2347d3b --- /dev/null +++ b/plugins/openehr-specs/skills/tracker-writing/references/examples.md @@ -0,0 +1,93 @@ +# Tracker writing: before and after + +Real texts from the October 2026 SPECPR clean-up, as first written and as the skill wants them. + +## Jira issue + +### Before (SPECPR-510 as created, 168 words) + +> **Origin:** author note removed from the generated class table by specifications-RM PR #40, +> recorded here so the topic is not lost. +> +> **Location:** EHR Extract specification, `EXTRACT_SPEC` class table, attribute `priority: +> Integer` ("Requested priority of this request to be handled by server. Priority schemes are +> likely to be local, and use values agreed by both ends."). +> +> **Note text:** +> > TBD: alternative is standard coded terms +> +> **Note:** the class table (`docs/UML/classes/org.openehr.rm.ehr_extract.extract_spec.adoc`) +> is generated from the UML model, and the mirrored `openehr_rm_*.bmm` files in +> specifications-ITS-BMM still carry the note. Whatever the decision, the UML attribute +> documentation needs the same edit, or the note will come back at the next export. +> +> **Question for Thomas Beale:** is this still an open topic, i.e. should `priority` become a +> coded value? If yes, we will turn it into a CR on the RM tracker. If no, resolve this ticket as +> Won't Do and we remove the note from the UML source. + +### After (58 words) + +Summary: `EHR Extract: EXTRACT_SPEC.priority as Integer or coded value?` + +> `EXTRACT_SPEC.priority` is an `Integer` with locally agreed values; an author note proposed +> standard coded terms instead. +> +> Where: RM EHR Extract, `EXTRACT_SPEC.priority`; note also in the UML source and the ITS-BMM +> `openehr_rm_*.bmm` files +> Change: decide coded value or keep Integer; either way remove the note from the UML source +> Origin: specifications-RM #40 + +What went: the origin paragraph (one link suffices), the quoted attribute documentation (the +reader opens the class table), the two-branch instruction to the assignee (the field says who, +the Change line says what). + +## Pull request + +### Before (specifications-LANG #8 as opened, 95 words plus a 10-item checklist) + +> Editorial: removes the leftover `TBD` author notes from the LANG specification text. Nothing +> normative changes. +> +> The notes are preserved below so each one can be picked up as a proper CR if it is still +> relevant. +> +> @wolandscat these all look like they came from you. Is any of them still an open topic? Please +> tick the ones that are and we will raise a Jira ticket for each; the rest we consider closed. +> +> - [ ] `docs/BEL/master03-language.adoc`: do we need `Integer64` and `Real64`? +> - ... (nine more) + +### After (34 words) + +Title: `Remove leftover TBD author notes (editorial)` + +> Removes ten `[.tbd]` author notes from BEL, EL and BMM3, and one empty section heading. +> No normative change. +> Why: each note now has a SPECPR ticket (SPECPR-495 to SPECPR-503). +> Amendment record: not needed, editorial. + +What went: the checklist (the tickets hold the notes), the question to the author (asked in the +tickets, where the answer is tracked). + +## Jira comment + +### Before (46 words) + +> Thanks for the update. I had a look at the PR and I think this is now fully covered by the +> change that Sebastian approved, so from my side we can resolve this ticket as Fixed once the +> merge is done. Let me know if you disagree. + +### After (14 words) + +> Fixed by PR specifications-ITS-REST #133 (approved, merge pending). Resolving Fixed after merge. + +## Over the cap: a proposal comment + +SPECPR-446, comment of 2026-10-16, about 330 words: current state, a two-step removal +proposal, a fallback, the effect on SPECPR-493/452/456, and a question to the SEC. It got a +decision within an hour. Removing the state or the fallback would have made the question +unanswerable. + +Correct handling under this skill: draft it, report "comment, 330 words, cap 40; parts: state, +proposal, fallback, impact, question", and ask the user whether to post as is or drop parts. +Post only after the answer. The posted long form keeps the one-line TL;DR first. From e547a496522084629ba837d840a6c76214bb73f8 Mon Sep 17 00:00:00 2001 From: Severin Kohler Date: Fri, 16 Oct 2026 13:27:59 +0200 Subject: [PATCH 2/2] docs(openehr-specs): add tracker-writing to the prompting guide Co-Authored-By: Claude Opus 5.5 --- docs/prompting-guide.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/prompting-guide.md b/docs/prompting-guide.md index 0363826..c48d54b 100644 --- a/docs/prompting-guide.md +++ b/docs/prompting-guide.md @@ -20,6 +20,7 @@ In the prompts, `` is a component id such as `RM`, `BASE` or `AM`, and ``. Claude takes the key from you, then from the branch name (`feat/SPECXX-42-`), and writes no key when it has none, rather than guessing. + +## Write a Jira issue, comment or pull request + +```text +Raise a SPECPR for the missing EXPR_VALUE_REF table in BEL. +Open the PR for this branch. +``` + +The `tracker-writing` skill gives each text a fixed structure and a hard cap: 120 words for an issue, 80 for a PR body, 40 for a comment. When the content does not fit, Claude shows you the draft with its word count and asks whether to post it long or drop parts. It does not cut on its own.