@groupby/ai-dev 0.5.16 → 0.5.17

package/teams/firstspirit-caas/skills/specify/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: specify
+description: Use when the user asks to specify, flesh out, or write a spec for an existing JIRA ticket — phrases like "specify this ticket", "flesh out HP-1234", "write a spec for this", "specify HP-1234 focus on backend". Triggers on requests to enrich an existing ticket's description in place.
+---
+
+# Specify
+
+## Overview
+
+Turns a vague or incomplete JIRA ticket into a well-formed, lightweight spec by gathering evidence from all available sources, running a brainstorming-style clarification loop to fill any remaining gaps, and updating the ticket description via `mcp__plugin_planetexpress_jira-tools__update_jira_ticket`.
+
+**Core principle:** The description is the *why* and the *what*. Code, file paths, class names, mechanical steps, and counts are excluded by default — included only when the work *is specifically about that thing*. Length follows scope — be concise; don't pad, don't artificially compress.
+
+**Second principle:** If the draft spec adds nothing the original didn't already say, the ticket is already specified — emit the canonical short message instead of rewording in place. See Step 5.
+
+## When to use
+
+- User asks to specify / flesh out / write a spec for an existing JIRA ticket
+- User says "specify this ticket", "flesh out HP-1234", "write a spec for this", or similar
+- User invokes the skill with optional constraints: "specify HP-1234 focus on backend API"
+
+## When NOT to use
+
+- User wants to create a new ticket from scratch — use `create-jira-ticket`
+- User wants to post a summary of completed work — use `summarise-for-jira-comment`
+- User wants to update multiple tickets in one go — no tool supports that; handle individually
+
+## Workflow
+
+### 1. Identify the ticket key
+
+- Default: parse `[A-Z]+-\d+` from the current branch name (e.g. `feature/HP-1615-spring-boot-4` → `HP-1615`)
+- Override: explicit key in user message or constraints
+- Unresolvable or ambiguous: ask before proceeding
+
+### 2. Fetch evidence
+
+Gather before asking any questions:
+- `mcp__plugin_planetexpress_jira-tools__get_jira_ticket` — current description, comments, status, and **`issuetype`** (drives the description shape — see "Description format" below)
+- `mcp__plugin_planetexpress_jira-tools__get_jira_dev_info` — linked PRs, branches, commits
+- Relevant codebase reads — only what the ticket context implies; do not scan the whole codebase to "be thorough"
+
+**Capture the issuetype** from the fetched ticket: `Bug` selects the bug shape; anything else (`Story`, `Task`, `Sub-task`, `Improvement`, `Epic`, or unknown) selects the story shape.
+
+**Extract the true original description** from the fetched description:
+- If the description contains the marker `----\n*Original description:*`, the text *below* that marker is the original (the ticket was already processed by `specify`). Use that as the original.
+- Otherwise, the full current description is the original.
+- Store this as `ORIGINAL` — it will be preserved verbatim in the final update.
+
+### 3. Draft spec + identify follow-on candidates
+
+Internally draft the description in the shape that matches the ticket's `issuetype` (see "Description format" below — Story shape uses `*To achieve:*` / `*I want:*`; Bug shape uses `*Bug:*` / `*Expected behaviour:*`). Simultaneously identify follow-on ticket candidates: out-of-scope items, unrelated bugs found while reading code, prerequisite work that belongs in a separate ticket.
+
+### 4. Mandatory brainstorming gate
+
+**Always** show the draft and ask the user using `AskUserQuestion` before proceeding — this step is **never skipped**.
+
+First, **show the current draft spec** to the user (verbatim, exactly as it would appear in JIRA — apply the composite format from Step 7 if ORIGINAL is non-empty). Then ask:
+
+> "Is the draft spec ready for review, or should we first run `superpowers:brainstorming` to explore it further?"
+
+Options to present:
+- **Proceed to review** — continue to step 5 (novelty check) and then spec approval
+- **Run brainstorming** — invoke `superpowers:brainstorming` with the fetched ticket and current draft as context, then re-draft (return to step 3) and re-ask this gate
+
+When invoking `superpowers:brainstorming`, pass `args: "skip local spec file — output is JIRA wiki markup, not docs/superpowers/specs/"` so the constraint is explicit.
+
+**This gate is not optional.** Do not skip it even when evidence seems complete, even when the user provided constraints up-front, and even when the ticket already looks well-formed.
+
+### 5. Novelty check — does the draft actually add anything?
+
+Hold the draft side-by-side with `ORIGINAL`. The draft is **novel** only if it contributes information not already present in `ORIGINAL` (including its comments/dev info you promoted in):
+
+- surfaces a *why* the original leaves implicit
+- captures non-obvious gotchas or constraints the original omits
+- resolves ambiguity raised during clarification (brainstorming or user-supplied constraints)
+- promotes information from comments, linked PRs, or code reads into the description so the assignee doesn't have to dig
+
+The draft is **not novel** when it only:
+
+- reorders, rephrases, condenses, or restructures the same points
+- changes formatting (bullets ↔ prose, header layout) without new content
+- shortens the original purely for brevity
+
+If the draft is **not novel**, output exactly:
+
+> Ticket is already specified.
+
+Then stop the workflow. Do not present a draft. Do not call `update_jira_ticket`. If genuine follow-on candidates were identified in Step 3 (e.g. unrelated bugs found while reading code), mention them in a single short follow-up sentence and offer to file them; otherwise end the response.
+
+If the draft **is novel**, continue to Step 6.
+
+### 6. Present proposed follow-on tickets (before the spec)
+
+If follow-on candidates exist, present them as a numbered list **before** showing the spec draft:
+
+```
+Proposed follow-on tickets:
+1. [Story] "Extract auth middleware into shared module" — currently bundled in this ticket but is a reusable piece with independent value
+2. [Bug] "Fix null handling in UserService#resolve" — discovered while reading the code; unrelated to this ticket's goal
+```
+
+Ask the user which to keep (or none). Chosen follow-ons inform the spec's out-of-scope line. If no candidates exist, skip this step entirely.
+
+### 7. Present spec for approval
+
+Show the exact content that will be written to JIRA, verbatim. The description is a composite: the new spec on top, then the original preserved below a separator (if there was an original):
+
+**If ORIGINAL is non-empty:**
+```
+<new spec in Jira wiki markup>
+
+&nbsp;
+
+&nbsp;
+
+&nbsp;
+
+----
+*Original description:*
+<ORIGINAL verbatim>
+```
+
+The three `&nbsp;` lines (each separated from its neighbours by a real blank line) are deliberate. Jira's wiki-markup renderer collapses consecutive *empty* blank lines into a single paragraph break, so naïvely writing three `\n` characters in a row produces no extra visible space. Each `&nbsp;` is a non-empty paragraph, which Jira *does* render, giving three visible empty rows above the `----` horizontal rule. Do not omit them and do not replace them with bare blank lines.
+
+**If ORIGINAL is empty / "No description":** show only the new spec (nothing to preserve).
+
+Present this composite to the user exactly as it will appear in JIRA, then end with:
+
+> Reply 'update', 'yes, update', or 'apply it' to apply to \<KEY\>, or give edits.
+
+### 8. Strict approval gate
+
+- Affirmative-and-explicit ("update", "yes, update", "apply it") → proceed
+- Edits ("shorter", "drop that bullet", "add context about X") → revise the spec section only; keep the `ORIGINAL` section unchanged; re-present the full composite verbatim, wait again
+- Anything else (silence, questions, "looks good") → do **not** update; treat as edits or a question
+
+### 9. Update the ticket
+
+Construct the final description exactly as shown in the Step 7 composite (spec + separator + original, or spec only if no original). Pass this to `mcp__plugin_planetexpress_jira-tools__update_jira_ticket`. Report the returned ticket link in chat.
+
+### 10. Chain to `create-jira-ticket`
+
+If no follow-on tickets were chosen (or Step 6 was skipped), stop here. Otherwise, for each chosen follow-on in sequence, invoke the `create-jira-ticket` skill to draft and file the ticket.
+
+## Description format
+
+The shape follows the ticket's **`issuetype`** (captured in Step 2):
+
+- `Bug` → **bug shape** below
+- everything else (`Story`, `Task`, `Sub-task`, `Improvement`, `Epic`, or unknown) → **story shape** below
+
+### Story shape — for Story / Task / Sub-task / Improvement / Epic / unknown
+
+```
+*To achieve:*
+<1–3 sentences describing the goal and motivation — the *why*. Drop in the
+concrete observations that justify the work (numbers, examples) when they
+sharpen the case.>
+
+*I want:*
+<1–2 sentences in user-story voice describing what should happen — the *what*.
+"I want X so that Y" is fine and idiomatic here.>
+
+*Additional:*
+- <non-obvious constraint, gotcha, or note>
+- <only include this section when there is something genuinely non-obvious;
+  otherwise omit it entirely>
+```
+
+### Bug shape — for Bug
+
+```
+*Bug:*
+<1–3 sentences describing the observed wrong behaviour. Include the trigger or
+repro context when it isn't self-evident from the summary.>
+
+*Expected behaviour:*
+<1–2 sentences describing what should happen instead.>
+
+*Additional:*
+- <repro detail, affected environment, related observation, or scope note>
+- <only include this section when something is genuinely non-obvious; omit if
+  the bug/expected pair already says everything that matters>
+```
+
+### Rules common to both shapes
+
+- **Markup:** Jira wiki markup. Use `*bold*` for the section labels above, `-` for bullets, `_italics_` and `{{monospace}}` only when they earn their place. No fenced code blocks unless code is genuinely the point of the ticket.
+- **Voice:** factual and concrete. First-person ("I want…") is correct inside the `*I want:*` section; elsewhere prefer neutral. Avoid corporate filler.
+- **No extra headers:** no `Scope` / `Out of scope` / `Acceptance criteria` / `Risks` / `Reference` sections. No estimates, no counts.
+- **Out-of-scope line:** if chosen follow-ons make something explicitly out of scope, a single line inside `*Additional:*` suffices: `- Out of scope: <what> — tracked in [proposed ticket summary].`
+- **Length:** follows scope. Be concise; don't pad and don't artificially compress. A two-line ticket and a fifteen-line ticket can both be correct — the test is whether every sentence earns its place.
+
+## Strong defaults — exclude unless they are the actual point of the ticket
+
+- Code blocks or inline code
+- File paths, class / method / function names
+- Counts (file counts, import counts, line counts)
+- Mechanical sub-tasks ("rename X → Y", "drop annotation Z")
+- Acceptance criteria, out-of-scope sections, risk lists
+- Time / effort estimates
+
+**Exception clause:** include any of the above when the work *is specifically about that thing*.
+
+## Edge cases
+
+| Situation | Behaviour |
+|---|---|
+| No ticket key resolvable | Ask the user; do not guess |
+| Multiple ticket keys in branch name | Ask which one; do not pick |
+| `get_jira_ticket` returns 404 | Confirm key with user before continuing |
+| Evidence already fully answers why/what/notes | Draft the spec, then still run the mandatory brainstorming gate (Step 4) — the user decides whether to invoke brainstorming |
+| User passed constraints at invocation | Treat as pre-filled answers; still ask the mandatory gate — brainstorming may ask fewer questions if chosen |
+| No follow-on candidates | Skip step 6 entirely |
+| Ticket has no existing description | No original to preserve; write spec only, no separator section. Novelty check still applies — but with empty ORIGINAL, any coherent spec is novel by definition. |
+| Ticket description already has the `----\n*Original description:*` marker | Extract text below marker as ORIGINAL; replace only the spec above the separator |
+| `issuetype` is `Bug` | Use the bug shape (`*Bug:*` / `*Expected behaviour:*`). |
+| `issuetype` is anything else, missing, or `Unknown` | Use the story shape (`*To achieve:*` / `*I want:*`). Don't ask. |
+| Ticket type strongly mismatches its actual content (e.g. a "Story" that describes a bug) | Follow the `issuetype` field — it is the source of truth for format. If the mismatch is glaring, mention it in the chat once but still format by issuetype. |
+| Draft only rephrases / restructures the original — no new content | Output exactly `Ticket is already specified.` Do not present a draft, do not call `update_jira_ticket`. |
+| Draft contributes one small clarification, otherwise rephrases | Still novel — keep that clarification and proceed. The novelty bar is "adds something", not "adds a lot". |
+| `update_jira_ticket` returns an error | Surface verbatim; do not retry silently or claim success |
+| User says "update it" referring to a draft already in chat | Confirm that draft is the one to apply, re-present verbatim, wait for explicit "update" |
+
+## Red flags — STOP and reconsider
+
+| Thought | Reality |
+|---|---|
+| "I should list every affected file" | The assignee greps the codebase. The description is the *why*, not the *where*. |
+| "Acceptance criteria will help reviewers" | Most tickets don't need them. The *what* already implies done. |
+| "Counts make scope concrete" | Counts age fast and add no decision value. Drop them. |
+| "Let me include mechanical steps so the assignee can follow along" | A bullet list of mechanical steps is a plan. Plans go in `./.claude/plans/`, not JIRA. |
+| "User said 'looks good' — that's approval" | Strict gate: needs explicit "update" / "yes, update" / "apply it". Anything else → wait. |
+| "The description is long because the work is genuinely complex" | Long usually means plan-leakage. If the length is earned by scope, keep it; if every other sentence could be cut without losing meaning, cut. |
+| "I'll just tighten the existing description and that counts as specifying" | No. Tightening without adding new information is the "already specified" case — output `Ticket is already specified.` and stop. |
+| "The original is verbose, so my shorter version must be an improvement" | Brevity isn't novelty. If the assignee learns nothing new from your version, don't replace the original. |
+| "I should write the brainstorming output to a local spec file" | No. The specify skill skips the local file. Format the approved design as JIRA wiki markup directly. |
+| "Evidence is complete — I can skip the brainstorming gate" | The mandatory gate (Step 4) is never skipped. Always show the draft first, then ask the user via `AskUserQuestion`. |

package/teams/firstspirit-caas/skills/summarise-for-jira-comment/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: summarise-for-jira-comment
+description: Use when the user asks for a JIRA ticket summary to post as a comment, or says things like "summarise the ticket", "post a summary on HP-1234", "wrap up this ticket". Triggers on requests to produce a high-level recap of work done on a ticket and post it back to JIRA as a comment.
+---
+
+# Summarise for JIRA Comment
+
+## Overview
+
+Drafts a high-level summary of the work done on a JIRA ticket from git evidence, presents it for explicit approval, and posts it as a JIRA comment.
+
+**Core principle:** Git is the evidence. The comment is the high-level recap, not a code walkthrough. Strong defaults exclude code, file paths, and identifiers — exceptions only when those *are* the point of the ticket.
+
+## When to use
+
+- The user asks to summarise a ticket, post a summary, wrap up a ticket, or similar
+- A ticket key is parseable from the current branch, or the user provided one
+- There is committed work on the branch (or an explicit scope override)
+
+## When NOT to use
+
+- The user wants the summary in chat only, not posted to JIRA — produce it directly without this skill
+- The branch is `master`/`main` with no explicit ticket + scope override
+- The user wants a per-commit changelog or release notes — different artifact
+
+## Workflow
+
+**Authority hierarchy: git > user input > ticket.** Higher always wins.
+
+1. **Identify the ticket key**
+   - Default: parse `[A-Z]+-\d+` from the current branch name (e.g., `feature/HP-1615-spring-boot-4` → `HP-1615`)
+   - Override: explicit key the user provided in their message
+   - Multiple keys in branch name, or none resolvable: ask the user
+
+2. **Identify the scope**
+   - Run `git fetch origin` first so `origin/master` is fresh (avoids phantom diff entries)
+   - Default: commits on the current branch since divergence from `origin/master`
+   - Override: explicit range, SHA list, or branch from the user
+   - No commits ahead of master: tell the user, do not fabricate
+
+3. **Gather, in this order**
+   - **Git** (highest): `git log origin/master..HEAD` for messages; `git diff origin/master...HEAD --stat` and targeted reads of the diff to understand intent. Read for *why*, not line-by-line.
+   - **PR if it exists**: `mcp__plugin_planetexpress_jira-tools__get_bitbucket_pr` for title/description, `mcp__plugin_planetexpress_jira-tools__get_bitbucket_pr_changes` for the change overview. Treated as part of git evidence.
+   - **User input** (middle): anything the user said in the conversation
+   - **Ticket** (lowest): `mcp__plugin_planetexpress_jira-tools__get_jira_ticket` for the description and recent comments. Context only; never overrides git.
+
+4. **Conflict resolution**
+   - Git contradicts user input or ticket → trust git, surface the discrepancy in chat (not in the JIRA comment), let the user decide
+
+5. **Draft** in the default voice and format (see next section). Choose format C only with a one-sentence justification.
+
+6. **Present in chat** — show the draft verbatim, exactly as it would appear in JIRA, followed by:
+   > Reply 'post' to publish to <KEY>, or give edits.
+
+7. **Wait for explicit approval (strict gate + edits)**
+   - Affirmative-and-explicit ("post it", "yes, post", "approved", "ship it") → post
+   - Edits ("shorter", "drop the second bullet", "mention X", "use format C") → revise, re-present, wait again
+   - Anything else (silence, questions, mixed feedback) → do **not** post; treat as edits or a question
+
+8. **Post** via `mcp__plugin_planetexpress_jira-tools__add_jira_comment` with the approved text. Confirm in chat with the comment URL/ID returned.
+
+**Pre-post safety:** if the resolved ticket key looks suspicious (parsed key not found, multiple keys in branch name, JIRA returned 404 on the get) — confirm with the user before posting.
+
+## Voice & format
+
+**Default format (B):** 3–6 brief bullets, one line each. Optional one-line lead-in for framing.
+
+**Escalation pressure scales with bullet count.** 3–4 bullets is comfortable B. 5–6 bullets is borderline — pause and check whether they form natural groups (they often do). 7+ bullets almost always means the work has multiple workstreams and belongs in format C with thematic headers; resist the urge to keep flattening.
+
+**Hard escalation to format C** (structured headers — workstream-themed, or *What changed* / *Why* / *Notes*) when bullets cannot carry the message because there is genuine nuance, multiple workstreams, or important context that would be lost in a flat list.
+
+## Breaking changes must stand out
+
+A change that requires action from users / operators / API consumers is a breaking change. It must be visually distinct in the summary, regardless of format.
+
+- **Format B**: prefix the bullet with `**Breaking:**`, or hoist it into a dedicated lead bullet above the rest.
+- **Format C**: give it a dedicated `## Breaking changes` section, separate from the workstream sections. Don't bury it inside *What changed*.
+
+A breaking change in the middle of a flat list reads as routine; the operator decision *do I need to act?* must be answerable from a scan.
+
+**Voice:** past tense, third-person, neutral and factual. Describes what *happened on the ticket*, not what *I* did.
+
+**Strong defaults — exclude unless they are the actual point of the ticket:**
+
+- Code blocks or inline code
+- File paths
+- Class / method / function names
+- Commit hashes, PR numbers (the PR link is on the ticket already)
+- Enumerations of identifier-level adaptations made during the work — annotation renames, method-signature changes, constant collapses, parameter additions — **even when framed as a category** ("Spring Framework 7 API rewrites: ~150 `APPLICATION_JSON_UTF8` collapses, `HttpMessageNotReadableException` constructor change, ..."). Name the category, never enumerate the contents. The PR diff has the contents.
+- Pre-existing state of the codebase — longstanding flaky tests, pre-existing failures, environmental issues, anything true regardless of this ticket. The summary describes what *this ticket* changed, not what's true about the codebase.
+- Bullets that describe routine plumbing the reader would infer from the ticket title alone — "deps realigned to the new baseline", "modularization absorbed", "starters added where the autoconfig moved", "tests updated for new APIs", "compile errors fixed". The title already implies this happened; bullets should describe specific consequences (breaking changes, non-obvious decisions, surprising scope) — never routine work.
+
+**Exception clause:** include any of the above when the work *is* about that specific thing — a ticket whose whole point is "introduce `FooService`" can name it; a ticket about "extract the auth helper" can mention the extraction.
+
+## Headers must not soften impact
+
+A header tells the reader the *kind* of thing they're about to read. A header that re-frames or softens its content is misleading and should be rejected.
+
+| ❌ Wrong | ✅ Right |
+|---|---|
+| Breaking change filed under "Behaviour preserved but worth flagging" | "Breaking change" |
+| Removed feature filed under "Minor cleanup" | "Removed: <feature>" |
+| New required configuration filed under "Internal refactor" | "New required configuration" |
+
+If a header does not fit its content, change the header — never re-cast the content to fit a softer header.
+
+**Length:** scannable. If a bullet runs past one line, it is probably too detailed — collapse or split.
+
+### Example pair
+
+Hypothetical ticket: *"Upgrade Spring Boot to 4.x"*.
+
+**❌ Bad (code-heavy, low-level):**
+
+> I bumped `spring.boot.version` in `gradle.properties` from `3.5.0` to `4.0.0`, then in `api-gateway/build.gradle.kts` I had to update `org.springframework.boot:spring-boot-starter-webflux` to align. The `ServerSecurityConfig.java` had to swap `ServerHttpSecurity#authorizeExchange` for the new `authorizeHttpExchange` API:
+> ```java
+> http.authorizeHttpExchange(spec -> spec.anyExchange().authenticated());
+> ```
+> Also updated `suppressedVulnerabilities.xml` for new Sonatype findings (CVE-2025-XXXX, CVE-2025-YYYY). All tests pass.
+
+**✅ Good (high-level, format B):**
+
+> Upgraded Spring Boot to 4.x across the build.
+>
+> - Reactive security configuration was migrated to the new exchange-authorisation API
+> - Test fixtures in modules using the old security config were updated to match
+> - Suppressions were extended to cover the new Sonatype findings introduced by the upgrade
+> - All module test suites pass on the upgraded baseline
+
+## Edge cases
+
+| Situation | Behaviour |
+|---|---|
+| No ticket key resolvable | Ask the user; do not guess |
+| Multiple ticket keys in branch name | Ask which one; do not pick |
+| No commits ahead of master | Say so; do not fabricate work |
+| Branch is `master`/`main` | Refuse without explicit ticket + scope override |
+| `get_jira_ticket` returns 404 | Confirm key with user before continuing |
+| `add_jira_comment` fails | Surface the error verbatim; do not claim success |
+| User input contradicts git | Trust git; flag the discrepancy in chat (not in the comment) |
+
+## Red flags — STOP and reconsider
+
+These thoughts mean the draft is drifting from the rules. If you catch one, revise before presenting.
+
+| Thought | Reality |
+|---|---|
+| "The reviewer needs the file path so they know where to look" | The PR diff has the path. The ticket comment is the *why*, not the *where*. |
+| "Bullets are too vague — let me add a code block" | Vague bullets need better wording, not code. Code belongs in the PR. |
+| "I should mention every commit so nothing is missed" | The summary is high-level. Commits the user cares about will be obvious from the result; the rest are noise. |
+| "User said 'looks fine' — that's approval" | Strict gate: needs an explicit "post"/"yes, post"/"approved"/"ship it". Anything else means wait. |
+| "The ticket description says X happened, so I'll mention X" | If git does not show X, do not mention X. Surface the discrepancy in chat instead. |
+| "I'll auto-post since the user already said yes once on a previous summary" | Each draft needs its own approval. Edits invalidate the prior approval. |
+| "Without details, the bullet looks empty" | An empty-looking bullet is the goal when the change is genuinely small. Padding with implementation detail violates the principle. |
+| "The category is too abstract — let me list what's in it" | The category is the right level. The enumeration belongs in the PR. |
+| "These aren't renames — they're API *adaptations* / *rewrites*" | Same shape, same exclusion. Both are mechanical adjustments to upstream API changes. Both belong in the PR, not the ticket. |
+| "This bullet about test status sets useful context" | Pre-existing test state is true regardless of the ticket. Anything that was true on master is not what the ticket changed. |
+| "It's a breaking change but I'll soften it under 'worth flagging'" | A breaking change is a breaking change. Headers must not soften impact. |
+| "The breaking-change bullet sits fine in the middle of the list" | Buried = routine-looking. Prefix with `**Breaking:**` or hoist into its own lead bullet / dedicated section. |
+| "I'm at 8 bullets but they all flow as one list" | 7+ bullets almost always means multiple workstreams. Group them with thematic headers (format C). |
+| "Worth listing the deps / starters / packages we touched" | If a reader of the ticket title would assume this happened anyway, the bullet adds nothing. Concrete consequences only — breaking changes, non-obvious decisions, surprising scope. Routine upgrade plumbing belongs in the PR. |
+| "The bullet is generic-sounding but it's still true" | True ≠ informative. Test: would the reader have inferred this from the ticket title alone? If yes, cut. |

package/teams/firstspirit-caas/skills/write-releasenotes/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: write-releasenotes
+description: Use when the user asks to write, create, update, or generate release notes for the current ticket branch — phrases like "write the release notes", "update releasenotes for HP-1234", "generate release notes", "add a changelog entry for this ticket". Triggers on requests to produce AsciiDoc release-note entries for a FirstSpirit/Gradle project's releasenotes subproject.
+---
+
+# Release Notes
+
+## Overview
+
+Writes or updates concise AsciiDoc release-note entries for the current ticket, in the project's `releasenotes` subproject. Entries are per-ticket, per-language (`de` and `en`), named typically `<ticket>-<type>.adoc`, and live in the "next" (unreleased) folders. If the placeholder files don't exist, generate them with the project's Gradle task (`createChore` / `createBugfix` / `createFeature`), then fill them from the **committed** changes on the ticket branch, matching the style of existing `releasenote*.adoc` files.
+
+**Core principle:** Release notes describe *what changed for the reader* — concise, user-facing, present-tense. Not a commit log, not a file list. Match the existing house style exactly; when in doubt, imitate a real example rather than invent format.
+
+**Applicability principle:** This skill only applies to projects wired for this release-notes mechanism. If there are no release-note files **and** no `create*` Gradle tasks, the skill is **not applicable** — say so and exit. Not applicable is a notice, not an error.
+
+## When to use
+
+- User asks to write / update / generate release notes for the current work
+- User invokes the skill with an explicit ticket: "release notes for HP-1234"
+- Finishing a ticket branch and the changelog entry is still missing
+
+## When NOT to use
+
+- User wants a JIRA comment recap of the work — use `summarise-for-jira-comment`
+- User wants a full commit message — that is not this skill
+- Project has no releasenotes subproject and no `create*` Gradle tasks — this skill is **not applicable** (see Step 2)
+
+## Workflow
+
+### 1. Identify ticket key and type
+
+- **Key** — default: parse `[A-Z]+-\d+` from the current branch name (e.g. `feature/HP-1615-spring-boot-4` → `HP-1615`). Override: explicit key in the user message. Unresolvable or ambiguous (multiple keys) → ask; do not guess.
+- **Type** — one of `chore` / `bugfix` / `feature`. **`chore` is the default.** Only pick `bugfix` or `feature` when the branch's committed changes are *obviously* a product bug fix or a product feature. The type drives both the filename and which Gradle task generates the placeholder.
+  - **Chore is the default** — use `chore` (`createChore`) whenever the work is not obviously a product feature or a product bug fix. In particular, when the changes are **primarily dependency/CVE bumps or small version updates**, the type is `chore` regardless of the JIRA `issuetype`.
+  - **Feature / bugfix** — use `feature` / `bugfix` only when the committed changes clearly implement a product feature or fix a product bug. The JIRA `issuetype` (fetched via `mcp__plugin_planetexpress_jira-tools__get_jira_ticket`) is a hint, not the deciding factor:
+    - `Bug` → lean `bugfix` — but confirm the diff is an actual product fix, not a dependency bump filed as a Bug.
+    - `Story` / `Improvement` / `New Feature` / `Epic` → lean `feature` — but if the diff is just version/CVE bumps, it is still a `chore`.
+  - Let the **committed diff win over the issuetype** when they disagree. **Never ask the user which type** — deciding this from the diff is the skill's job. When genuinely on the fence, fall back to `chore` (the safe default). Only `bugfix`/`feature` require positive evidence in the diff.
+
+### 2. Locate the releasenotes mechanism (applicability gate)
+
+Discover, do not assume paths:
+
+- **Existing note files** — find the releasenotes subproject and its examples:
+  ```
+  find . -iname 'releasenote*.adoc' -not -path '*/build/*'
+  ```
+  Also look for a directory named `releasenotes` (the subproject) and, under it, "next"/"unreleased" folders holding per-language notes.
+- **Gradle tasks** — check the create tasks exist:
+  ```
+  ./gradlew tasks --all -q 2>/dev/null | grep -iE 'create(Chore|Bugfix|Feature)'
+  ```
+  (Use `gradlew.bat` on Windows; use the wrapper if present, else `gradle`.)
+
+**Decision:**
+
+| Existing `.adoc` notes | `create*` tasks | Action |
+|---|---|---|
+| yes | — | Applicable — proceed (use tasks if present to scaffold, else write files directly matching examples) |
+| no | yes | Applicable — proceed (scaffold with the task) |
+| no | no | **Not applicable** — emit the notice below and stop |
+
+Not-applicable notice (verbatim intent, one message, then stop):
+
+> This project has no release-notes files and no `createChore`/`createBugfix`/`createFeature` Gradle tasks. The release-notes skill is not applicable here.
+
+### 3. Check whether this ticket's note files already exist
+
+Look for the per-language files for this ticket in the "next" folders, typically:
+
+- `<ticket>-<type>.adoc` for **de**
+- `<ticket>-<type>.adoc` for **en**
+
+(The exact folder split by language follows the project layout — infer it from where existing `releasenote*.adoc` examples live. Some projects use `next/de/` + `next/en/`, others a language suffix. Match what you observe.)
+
+- **Both exist** → skip Step 4; go to Step 5 to update them.
+- **Missing (either)** → Step 4 to generate placeholders.
+
+### 4. Generate placeholder files via Gradle
+
+Run the task matching the type. Task naming convention:
+
+| Type | Task |
+|---|---|
+| chore | `./gradlew createChore` |
+| bugfix | `./gradlew createBugfix` |
+| feature | `./gradlew createFeature` |
+
+- These create the placeholder `.adoc` files in the next folders and **may bump the project version** — that side effect is the task's, not yours; report it if it happens.
+- The task may prompt for a ticket/summary or take properties (e.g. `-Pticket=HP-1234`). Inspect existing filenames and, if the task fails on missing input, surface its output and ask the user for the exact invocation rather than guessing flags.
+- If the task exits non-zero, surface stderr verbatim and stop. Do not hand-create files as a silent fallback unless the user asks.
+
+Re-check that the expected `<ticket>-<type>.adoc` files now exist before continuing.
+
+### 5. Gather the committed changes (source of truth)
+
+Only **committed** changes on the ticket branch are relevant — ignore the working tree and staged-but-uncommitted edits.
+
+- Base = the main branch (usually `main`). Compute the range:
+  ```
+  git log --oneline $(git merge-base main HEAD)..HEAD
+  git diff $(git merge-base main HEAD)..HEAD --stat
+  ```
+- Read commit messages and the diff to understand *what changed for the reader*. Pull the JIRA summary/description (Step 1 fetch) for the user-facing framing.
+- If there are no commits on the branch beyond base, say so and ask whether to proceed (nothing to describe yet).
+
+### 6. Draft — concise, house-style, both languages
+
+- **Study first.** Open 1–3 existing `releasenote*.adoc` examples and match their AsciiDoc structure, heading level, bullet vs prose, tense, and length exactly. Imitate; don't invent format.
+- **Concise.** One entry per ticket. Typically 1–3 lines / a short bullet. Describe the change and its user impact, not the mechanics. No file paths, class names, or commit hashes unless the change *is* about that.
+- **Both languages.** Write `de` and `en` entries with equivalent meaning — the `de` version in German, the `en` in English. Keep them in sync; don't leave one as a placeholder.
+- Preserve any template tokens/attributes the placeholder came with (ticket reference, version attribute) — fill them, don't delete them.
+
+**Security / dependency content policy (mandatory):**
+
+Release notes describe *product* changes for the reader. They are not a security bulletin.
+
+- **Never name CVEs.** No `CVE-YYYY-NNNNN` identifiers in the notes. If a dependency was bumped, just state that it was updated — keep it short. Prefer the *what*, not the *why-security*.
+- **Never mention CVE suppressions**, `dependency-check` suppressions, `suppressedVulnerabilities.xml`, or any suppression bookkeeping. That is internal maintenance, never reader-facing. Omit it entirely.
+- **Dependency updates are fine** to mention — but framed as a product-relevant update, concise, and without the security rationale. New capability or behaviour from the bump is worth a line; a routine version bump for hygiene is a one-liner or folded into a general "dependencies updated" note.
+- If the *only* substance of the ticket is CVE/suppression handling with no reader-facing effect, the entry is a short chore note that dependencies were updated — not a list of vulnerabilities addressed.
+
+Rewrite, don't transcribe. Bad → good:
+
+- Bad: `Logback wurde auf Version 1.5.38 aktualisiert, um CVE-2026-13006 zu beheben. Die Dependency-Check-Unterdrückungen für die ausstehenden Micrometer-CVEs wurden aktualisiert.`
+  Good: `Logback wurde auf Version 1.5.38 aktualisiert.`
+- Bad: `Das AWS SDK wurde aktualisiert, um die transitiven Denial-of-Service-Schwachstellen CVE-2026-54399 und CVE-2026-54428 in Apache HttpComponents Core (httpcore5) zu beheben.`
+  Good: `Das AWS SDK wurde aktualisiert.`
+
+### 7. Present for approval, then write
+
+**Pre-approval at invocation:** if the user pre-authorized writing when invoking the skill — e.g. "write the release notes and apply them", "no need to confirm", "just do it", "and commit" — skip the gate below and write directly. Still show the final content in chat after writing. Pre-approval covers only writing the files; it never extends to committing unless the user said so explicitly.
+
+Otherwise, show the exact content for both files verbatim (path + body), then:
+
+> Reply 'write' / 'apply' to write these files, or give edits.
+
+- Affirmative-and-explicit → write both files with `Edit`/`Write`.
+- Edits → revise and re-present; wait again.
+- Anything else (silence, "looks good", a question) → treat as edits/question; do **not** write.
+
+Do not commit. Report the written file paths. If Step 4 bumped the version, mention it.
+
+## Edge cases
+
+| Situation | Behaviour |
+|---|---|
+| No ticket key resolvable from branch or message | Ask; do not guess |
+| Multiple ticket keys in branch name | Ask which one |
+| No `.adoc` notes and no `create*` tasks | Not applicable — emit the notice, stop (not an error) |
+| `get_jira_ticket` fails / type unclear | Decide from the committed diff; fall back to `chore`. Never ask the user for the type |
+| Gradle task not found though examples exist | Write the files directly, matching an existing example's layout |
+| Gradle task fails or needs unknown input | Surface output verbatim; ask for the exact invocation; don't guess flags |
+| Gradle task bumps the version | Report the version change; it is the task's side effect, not yours |
+| Note files already exist for this ticket | Skip generation; update them in place |
+| No commits on branch beyond base | Say so; ask whether to proceed |
+| Only uncommitted/working-tree changes | Ignore them — committed changes only; tell the user to commit first if the branch is empty |
+| Language layout unclear | Infer from where existing examples live; if genuinely ambiguous, ask |
+| User approves for one language only | Write only what was approved; re-present the other |
+| User pre-approved at invocation ("write and apply", "just do it") | Skip the approval gate; write directly, then show the content. Commit only if the user also said so explicitly |
+
+## Red flags — STOP and reconsider
+
+| Thought | Reality |
+|---|---|
+| "I'll invent a clean AsciiDoc format" | Match the existing `releasenote*.adoc` house style. Imitate a real example. |
+| "I'll list the changed files / classes" | Release notes are user-facing. Describe the change's impact, not the mechanics. |
+| "I'll describe my uncommitted work too" | Only committed changes on the branch count. |
+| "English is enough" | Both `de` and `en` must be written and in sync. |
+| "No release-notes setup — I'll create the whole mechanism" | If there are no notes and no `create*` tasks, the skill is not applicable. Say so and stop. |
+| "I'll hand-create placeholders instead of running Gradle" | Use the `create*` task when it exists — it also handles version/layout. Hand-create only when tasks are absent or the user asks. |
+| "Longer notes look more complete" | Concise wins. One short entry per ticket. |
+| "I'll name the CVE so the reader knows what was fixed" | Never name CVEs in release notes. A bumped dependency is just "updated to X" — keep it short. |
+| "I'll note that the suppressions were updated" | CVE/dependency-check suppressions are internal bookkeeping — never reader-facing. Omit entirely. |
+| "The JIRA type is Story, so it's a feature" | Type follows the committed diff, not the issuetype. CVE/version-bump work is a `chore` even when filed as a Story/Bug. Default to `chore` unless it's obviously a product feature or product bug fix. |
+| "I'll just write the files, they're only release notes" | Present both files for approval first — unless the user pre-approved at invocation. Otherwise write only on explicit go. |
+| "User said 'write and apply' but I'll confirm anyway to be safe" | Pre-approval means skip the gate. Write directly, then show what you wrote. |