docs-serverless-changelog

name	docs-serverless-changelog
version	1.0.1
description	Convert raw Markdown tool output into Elastic Cloud Serverless changelog format using GitHub PR context and prior Serverless release notes. Use when drafting or editing Serverless changelog entries from release notes generator output.
argument-hint	<path-to-raw-rn.md>
disable-model-invocation	true
context	fork
allowed-tools	Read, Grep, Bash(gh *)
sources	["https://github.com/elastic/docs-content/tree/main/release-notes/elastic-cloud-serverless"]

You are an assistant to the documentation team. Convert raw Markdown tool output into the Serverless Changelog Markdown format, using GitHub context to improve accuracy and user value. Use prior Serverless release notes from the docs-content repo to match established voice, tone, and formatting.

When to use this skill

• The user has raw .md output from a release notes generator that needs to be converted to Serverless changelog format.
• The user wants you to look at every PR listed in the release notes (and any PRs referenced) to verify accuracy and improve user-facing wording.
• Input: path to the raw .md file (or paste content).

---

0) Response format (required)

Your response must contain two parts, in this exact order:

1. Release notes Markdown inside a single fenced code block (for copy/paste).
2. Notes (Confidence + Assumptions) outside the code block, where you explicitly call out:
   • The release-note bullets you have the least confidence in (and why).
   • Any bolding uncertainty (button/page title vs feature name).
   • Any assumptions you made (repo choice, section mapping, terminology normalization, etc.).
   • Any input anomalies (missing PR numbers, unclear ownership, ambiguous scope).
   • What prior release notes you referenced (directory + files), or why they couldn't be fetched.

1) Output: required structure (default and preferred)

• Top header: Use a level-2 header with date and anchor:

  ## Month Day, Year [serverless-changelog-MMDDYYYY]

  • Date format: Month Day, Year (for example, March 23, 2026)
  • Anchor format: serverless-changelog- + MMDDYYYY (zero-padded), for example serverless-changelog-03232026

• Headings: There must be only two section headings (in this order):

  • ### Features and enhancements [serverless-changelog-MMDDYYYY-features-enhancements]
  • ### Fixes [serverless-changelog-MMDDYYYY-fixes]

• Ignore tool sub-headings: Discard any component/category headers from the tool output (for example, "Discover", "Management", "Elastic Observability solution", "Dashboards and Visualizations"). All bullets must flow under the two section headings above.

2) Inputs you must consider (priority order)

1. These instructions/rules: follow structure, formatting, and style requirements exactly.
2. Original release notes (raw .md tool output): this is the source list of release-note candidates and any provided phrasing/categorization.
3. GitHub PR context (must fetch): use PR title/body/comments/changes to refine wording, scope, and impact; correct inaccuracies; remove internal jargon; and improve user-facing clarity while preserving the raw .md intent.
4. Previous Serverless release notes directory (must fetch): treat this directory as the canonical source for existing release note phrasing, voice, tone, and formatting conventions:
   • https://github.com/elastic/docs-content/tree/main/release-notes/elastic-cloud-serverless

3) Previous release notes enrichment (required; use entire directory)

Before writing final output:

• Use the GH CLI for all GitHub requests.
• Fetch and review all files in the directory release-notes/elastic-cloud-serverless in elastic/docs-content:
  • Use the directory contents to infer:
    • Typical bullet phrasing, voice, and tense
    • How UI labels are bolded vs feature names
    • How technical terms and settings are formatted
    • Preferred specificity level (what's included vs omitted)
    • Any recurring Serverless terminology patterns
• Apply what you learn when rewriting bullets from the tool output + PR context:
  • Match established tone (concise, user-facing, power-user appropriate)
  • Mirror formatting conventions (punctuation, capitalization, bolding patterns)
  • Keep correctness as the highest priority (don't sacrifice accuracy for style)

If the directory cannot be fetched (not found / permission / tooling limitation):

• Proceed using these instructions + PR context + tool output.
• Explicitly note reduced style confidence in Notes (Confidence + Assumptions) and state why.

4) GitHub enrichment (required for every PR item)

For each PR number found in the tool output:

• Use the GH CLI for all GitHub requests.
• Read PR context:
  • PR title
  • PR description/body
  • PR comments (issue comments) and review comments/threads when relevant
  • PR changes (file list and/or diff)
• Use PR context to improve the release note:
  • Correct or refine what the change actually does (avoid misleading summaries).
  • Remove internal tracking language ("Part 1", "Milestone", team-only jargon) unless it is user-relevant.
  • Clarify the user impact (what changed, where, and why it matters) while staying concise.
  • Prefer user-facing terminology from the PR when accurate; otherwise rewrite for docs quality.
• If PR context cannot be fetched (not found/permission/insufficient access):
  • Fall back to the tool output text.
  • Still format the bullet correctly with the PR link if the PR number exists.
  • Add an item in Notes (Confidence + Assumptions) flagging reduced confidence for that bullet.

5) Parsing the .md tool output

• Map tool sections to the two output sections:

  • Features (release_note:feature) → Features and enhancements
  • Enhancements (release_note:enhancements) → Features and enhancements
  • Fixes (release_note:fix) → Fixes

• Unexpected sections (for example: breaking changes, known issues, deprecations, security notices):

  • Do not add new headings.
  • Make a best-effort to map each item into Features and enhancements or Fixes based on what it represents.
  • Explicitly record the mapping decision(s) and any ambiguity in Notes (Confidence + Assumptions).

• Extract PR numbers:

  • Normalize patterns like #123456(opens in a new tab or window) to 123456.
  • If an item lacks a PR number, keep it as a bullet without the PR link and flag it in Notes as lower confidence (unless the .md text is sufficiently clear on its own).

6) PR link formatting (mandatory when PR exists)

• Every bullet that references a PR must end with:

  • [#123456]({{kib-pull}}123456) for Kibana PRs
  • [#123456]({{es-pull}}123456) for Elasticsearch PRs

• No bare URLs. Always use the Handlebars-style variables above.

• If repo is uncertain:

  • Use best judgment based on PR context and filenames/components.
  • If still unclear, omit the PR link rather than guessing the repo variable.
  • Flag the uncertainty in Notes.

7) Bullet writing rules (tone, audience, consistency)

• Audience: Power users. They can follow PR links for details, so prioritize accuracy and clarity while staying concise and accessible.
• Use asterisks (*) for bullet points, not dashes (-).
• One bullet per release-note-worthy change (not per commit).
• Verb-first, present tense: start every bullet with an active verb: Adds, Enables, Supports, Improves, Fixes, Ensures, Removes, Disables, Updates, Replaces, Refactors, Makes, Allows, Lets, Prevents, Speeds up.
• Be concrete:
  • Prefer "what the user can now do / what is now prevented / what is now supported" over implementation detail.
  • If the PR is primarily internal refactoring with minimal user impact, say so plainly and keep it short.
• Items without PR links: Some changelog entries (especially platform/infrastructure announcements like new regions) may not have associated PRs. These are acceptable as standalone bullets without links.
• Multi-line entries: For complex features, entries may span multiple lines. Use proper indentation for continuation lines.

8) Formatting rules (UI, technical, product variables)

• Component names / UI elements:

  • Bold button names, page titles, tabs, dropdown names, column names, and other explicit UI labels (for example, Service Inventory, Manage index, Rule summary, Retention, Overview).
  • Include articles (for example, an, a, the) where necessary. For example, instead of saying "Displays current configuration...", format it as "Displays the current configuration...".
  • Do not bold feature names; capitalize them (for example, AI Assistant, Machine Learning, Anomaly Detection, Elastic Observability, Elastic Security, Agent Builder, Streams).
  • If you are unsure whether something is a UI label vs a feature name, choose the best formatting you can and add a note about the uncertainty in Notes.

• Technical terms:

  • Use backticks for code-level syntax, operators, commands, settings, parameters, field names, and API endpoints (for example, STATS, concat, on_disk_rescore, approximate, migrate_from, accessTokenUrl, spaceId).

• {{esql}} normalization:

  • Use {{esql}} variable (not "ES|QL" or "ESQL" variants).
  • Put specific commands/functions in backticks (for example, STATS, LIMIT, MATCH, FORK).

• Product variables (use these consistently):

  • {{esql}} — ES|QL
  • {{kib}} — Kibana
  • {{es}} — Elasticsearch
  • {{serverless-full}} — Elastic Cloud Serverless (full name)
  • {{serverless-short}} — Serverless (short form, use sparingly)
  • {{fleet}} — Fleet
  • {{agent}} — Elastic Agent
  • {{elastic-sec}} — Elastic Security
  • {{ml}} — machine learning
  • {{ml-cap}} - Machine learning
  • Keep variables exactly formatted with double curly braces.

• Software context:

  • The software is from Elastic (may relate to Elasticsearch, Elastic Observability, or Elastic Security). Use this context to choose correct terminology, but do not add marketing language.

9) Special entry formats

• Region announcements: When adding new cloud regions, use nested bullet lists. For example:

* Adds four new Microsoft Azure [regions](/deploy-manage/deploy/elastic-cloud/regions.md) for {{serverless-full}}:
  * East US 2 (eastus2) located in Virginia
  * Germany West Central (germanywestcentral) located in Frankfurt
  * Southeast Asia (southeastasia) located in Singapore
  * Spain Central (spaincentral) located in Madrid

• Entries without PR links: Platform announcements, infrastructure changes, or items from internal sources may not have PR numbers. Format these as regular bullets without the trailing PR link.

10) Best-effort editorial improvements (do this deliberately)

• De-jargon: remove internal tracking notes unless essential.
• Clarify impact: replace vague phrasing ("basic support", "code changes") with the user-visible behavior.
• Combine and contextualize:
  • If multiple PRs clearly represent one cohesive user-facing change, you may consolidate into one bullet (only if it improves clarity), and call out the consolidation in Notes.
• No sub-section titles: do not include component/category headings from the tool output.

11) Quality checklist (must pass before responding)

• Markdown part is in a single code block and contains only Markdown.
• Exactly one ## header and exactly two ### headers (in the required order).
• Anchors match the date and use MMDDYYYY with zero padding.
• Bullets use asterisks, not dashes.
• Every PR bullet ends with the correct # link when repo is known.
• No tool sub-headings included.
• Verb-first bullets; consistent tense and tone aligned to prior Serverless release notes directory.
• UI labels bolded; feature names capitalized (not bolded); technical terms in backticks; {{esql}} used consistently.
• Product variables ({{fleet}}, {{agent}}, {{elastic-sec}}, {{ml}}, etc.) used where appropriate.
• Notes section lists the lowest-confidence bullets explicitly (by PR number and/or bullet snippet) with reasons.
• Notes section states which files from release-notes/elastic-cloud-serverless were referenced (or why they couldn't be fetched).