| name | issue-draft-release-notes |
| codex-short-description | Draft a customer-facing release note for a Jira ticket from ticket + MR context |
| description | Draft a customer-facing release note for a Jira ticket by gathering the ticket context (summary, description, type, fix version, comments) and any linked GitLab merge requests / code changes, then synthesizing a clear, audience- appropriate release note. Runs a clarity-council quality pass over the draft. Read-only by default; the user may opt in at the end to publish the note as a Jira comment (or into a Release Notes field if one exists). Use when user says "draft release notes", "write a release note", "release note for [TICKET-KEY]", "what changed in this ticket", or invokes /issue-draft-release-notes with a ticket key.
|
| allowed-tools | ["Read","Bash","AskUserQuestion","Agent","Skill","mcp__atlassian__jira_get_issue","mcp__atlassian__jira_get_comments","mcp__atlassian__jira_get_remote_links","mcp__atlassian__jira_get_changelog","mcp__atlassian__jira_search","mcp__atlassian__jira_add_comment","mcp__atlassian__jira_update_issue","mcp__gitlab-mcp__list_merge_requests","mcp__gitlab-mcp__get_merge_request","mcp__gitlab-mcp__get_merge_request_diffs","mcp__gitlab-mcp__list_merge_request_changed_files"] |
| related-skills | ["clarity-council","writing-humanize","technical-writer"] |
| loop-eligible | false |
| compatibility | claude-code codex opencode |
Issue — Draft Release Notes
Read-only drafting of a customer-facing release note for a Jira ticket. Gathers ticket context and related MR code changes, synthesizes a release note matched to the audience, runs a quality pass, and (only on opt-in) posts it back to the ticket.
Read-only by default. The skill never modifies code, MRs, Confluence, or Jira fields. The single permitted write is in Phase 6 — and only after explicit user opt-in: posting the note as a Jira comment, or setting a Release Notes field.
Input
A Jira ticket key — pattern [A-Z][A-Z0-9]+-\d+ (e.g. PRJ-1234). Extract from the user's message. If no key is present, ask for one. Default project key (if the user gives only a number) is read from memory (reference_jira_default_project.md).
Workflow
Release-Notes Progress:
- [ ] Phase 1: Gather ticket context
- [ ] Phase 2: Find & analyze related MRs / code changes
- [ ] Phase 3: Determine audience & note type
- [ ] Phase 4: Draft the release note
- [ ] Phase 5: Quality pass (clarity-council + writing-humanize)
- [ ] Phase 6: Optionally publish back to the ticket (user opt-in)
Phase 1 — Gather ticket context
jira_get_issue — summary, description, issue type, status, priority, components, labels, fix version(s), affected version, resolution.jira_get_comments — capture what was actually implemented vs. originally scoped; watch for "done / shipped in" notes.jira_get_remote_links — capture linked GitLab MR URLs and Confluence pages.
The issue type and fix version strongly shape the note: a Bug reads as a fix, a Story/Feature as a capability, a Task may be internal-only (flag it). Compile a short Context Summary and present it.
Phase 2 — Find & analyze related MRs / code changes
Locate merge requests tied to this ticket:
- From remote links — any GitLab MR URLs captured in Phase 1; fetch each via
get_merge_request.
- By search —
list_merge_requests filtered on the ticket key (MR titles and branch names usually embed it, e.g. feature/PRJ-1234-...). Limit to the most relevant 5.
- For each relevant MR: read the title, description, and changed-files list (
list_merge_request_changed_files). Pull diffs (get_merge_request_diffs) only when the description is thin and you need to infer user-visible behavior — release notes describe what changed for the user, not line-level detail. If a diff exceeds ~2000 lines, rely on the file list + MR description.
Resolve the GitLab project path from memory (reference_gitlab_config.md) — do not hardcode URLs. If no MRs are found, note that and draft from the ticket context alone.
Produce a one-line "what actually changed" takeaway per MR.
Phase 3 — Determine audience & note type
Pick the note's framing from the ticket type and content. If genuinely ambiguous, ask the user once via AskUserQuestion:
- Audience — Customer/end-user (default), Operator/admin, or Internal/developer.
- Type —
New feature · Enhancement · Bug fix · Security fix · Deprecation · Breaking change · Internal (no customer-facing note).
If the change is purely internal (refactor, test, CI), recommend Internal — no customer note and confirm before drafting anyway.
Phase 4 — Draft the release note
Write the note in the RELEASE-NOTE-FORMAT.md structure. Core rules:
- No icons or emoji. Plain-text headline and body only.
- Lead with user value, not implementation. "You can now…" / "Fixed an issue where…" — not "Refactored the X handler."
- Plain language. No ticket jargon, no internal class/module names unless the audience is developers.
- One note per ticket, tight: a headline + 1–3 sentences. Add a "Details / Impact" line only when it changes user behavior (action required, defaults changed, migration needed).
- State the fix version if known.
- For bug fixes, describe the symptom the user saw, not the root cause.
- For breaking changes / deprecations, always include an Action required line.
Phase 5 — Quality pass
- Invoke
/clarity-council (multi mode) with personas Technical Writer, Product Owner, and Customer Advocate:
- user_problem: "Is this release note accurate, clear, and appropriately scoped for its audience?"
- context: the draft note + Context Summary + per-MR "what changed" takeaways + chosen audience/type.
- desired_outcome: "A release note that a {audience} reads in 10 seconds and understands what changed and whether they must act. Flag any claim not supported by the ticket/MR evidence, and any leaked internal jargon."
- depth: standard.
- Technical Writer owns clarity and scannability; Product Owner owns value framing and scope accuracy; Customer Advocate owns "does this answer the user's 'what's in it for me / do I need to do anything?'".
- Incorporate the findings. Then run the note prose through the
/writing-humanize skill to strip AI-tells (em-dash overuse, rule-of-three, inflated phrasing) so it reads naturally.
- Present the final note in a fenced ```markdown block, plus a one-line note of the audience/type chosen and any claims that could not be evidenced (so the user can verify).
Phase 6 — Optionally publish back to the ticket
Ask the user via AskUserQuestion:
Publish this release note to {TICKET-KEY}?
- No (recommended default) — end the skill, nothing posted.
- Post as a comment — add it as a Jira comment.
- Set Release Notes field — write it into a Release Notes field (only offer this if such a field exists on the ticket).
If "No": end with one sentence — "Release note kept local. Nothing posted."
If "Post as a comment":
- Read jira-comment-template.md (sibling file).
- Render the note in Jira wiki markup (headings
h2., bold *text*, code {code}, panels {panel}) per the template's mapping — not GitHub markdown.
- Append the AI disclaimer panel from the template verbatim.
- Post via
jira_add_comment (page_id = ticket key, body = rendered note).
- Confirm with the ticket key.
If "Set Release Notes field": only if Phase 1's jira_get_issue revealed a Release Notes custom field. Confirm the exact field name with the user, then jira_update_issue with that field set to the plain-text note (no disclaimer panel — fields are not comments). If no such field exists, fall back to the comment option.
If a write fails (permissions, network), surface the error and offer to retry or keep the note local — never swallow the failure.
Constraints
- Read-only across all systems, with one explicit exception. The only permitted writes are
jira_add_comment or jira_update_issue (Release Notes field), in Phase 6, after explicit opt-in. Never modify code, MRs, or Confluence.
- Never auto-publish. Phase 6 always goes through the explicit prompt, even if the user opted in during a prior session.
- The disclaimer panel is mandatory whenever a comment is posted. Do not edit, soften, or omit it.
- Do not invent changes. Every claim in the note must trace to the ticket or an MR. If evidence is thin, say so and draft conservatively rather than embellish.
- No internal jargon, ticket numbers, or class names in customer/operator notes (developer-audience notes may include them).
- No icons or emoji in the release note body or headline.
- Do not write files to disk unless the user explicitly asks to save the note.
- If no MRs are found and the ticket context is too thin to describe a user-visible change, stop and tell the user — a release note needs something concrete to describe.
Quality Loop
Before returning the artifact, evaluate it and refine if it falls short.
- Generate the artifact via the workflow above.
- Self-evaluate against these criteria:
- Note is written for the target audience (customer-facing, not internal jargon)
- Content is grounded in the ticket + linked MR changes, not invented
- Fix version and issue type are reflected correctly
- Read-only respected — nothing posted unless the user opts in
- Loop — if two or more criteria fail, revise and re-check.
- Exit when all criteria pass, or after two refinement passes (then note which criteria still fall short).
Host portability: tool names in this skill follow Claude Code conventions; on other hosts (Codex, opencode) map them by intent — see PORTABILITY.md.
Self-Evolve Loop
This skill learns across invocations — the full contract is
SELF-EVOLVE.md. Start: read the learnings
journal — ~/.ink-and-agency/learnings/issue-draft-release-notes.md and/or the workspace-local
.ink-and-agency/learnings/issue-draft-release-notes.md — if present, and apply its guidance.
End: self-evaluate the results; optionally ask the user for feedback (never
block on it); append signal-bearing learnings to the journal (user-global when
the sandbox allows writing there, workspace-local otherwise); route
skill-improvement ideas per the contract's tiers — edit the canonical source
when one is present, never the plugin cache.
