whatsnew

What's-new release-notes skill

Formalizes the previously ad-hoc process of writing an Aspire "What's new in Aspire N.N" page as a single, step-argument skill with a repeatable lifecycle. Invoke it as /whatsnew {modality} — the modality argument selects one phase:

{draft/scaffold} → {research} → {critique} → {validate} → {polish} → {review}
   init/structure   dossier+draft  self-review   fact-check   edits+data    sign-off

Each phase has a dedicated spec under references/. This skill orchestrates existing skills — it does not duplicate them. {research} is the phase that authors the article body from its dossier; {critique}/{validate} then review and fact-check that draft, and {polish} finalizes it. Because {polish} edits content after {validate}, it must end with a fresh {validate} pass so nothing ships unchecked (see below).

Dispatch on the modality argument

Read the argument, then follow the matching spec. draft, scaffold, and init are aliases for the same phase. If no argument is given, ask which phase to run (or infer from context — e.g. a fresh release with no page → draft).

Modality	Alias	Purpose	Spec	Edits content?
draft	scaffold, init	Stand up branch, draft PR, skeleton MDX, banner, sidebar, version constants. Structure only.	01-draft-scaffold.md	Skeleton only
research	—	Enumerate every change into an impact-focused dossier, then author the first-draft prose into the MDX from it.	02-research.md	Yes — drafts the body
critique	—	Content-quality self-review of draft vs dossier; severity-ranked findings.	03-critique.md	No — reports only
validate	—	Ralph loop with doc-pr-reviewer until 100% factual; samples/links/assets. No bun run build.	04-validate.md	Fixes only
polish	—	Editorial pass + CI triage + diagnostics-author @mentions + automated data ingestion, then a final {validate} pass.	05-polish.md	Yes
review	—	Undraft PR, description, reviewers + doc-tester blind run of every in-article scenario.	06-review.md	No

Supporting references

• whats-new-template.mdx — structure-only skeleton the draft phase copies (scaffold tokens, publishDate frontmatter, and the mandated section taxonomy).
• writing-guidelines.md — humanized voice + the maintainer content standards. Defers to doc-writer for canonical style.

Cross-cutting rules (apply to every phase)

Git / branching / PR

• Release work happens on a release/{N.N} branch in the repository.
• Cut release/{N.N} from the latest default branch (e.g. main) — fetch first so you branch from an up-to-date base and avoid merge conflicts.
• Iterate via a draft PR from release/{N.N} into the repository's default branch. Open it after the scaffold is committed (a branch with no commits ahead of the default branch has no diff, so the PR can't be created); {review} marks it ready for review.

Voice & quality (see writing-guidelines.md + doc-writer)

• Impact first, positives first, KISS. No walls of text, no marketing fluff.
• Judicious <Aside> — a spotlight, not a floodlight. Don't burn the reader's eyes.
• Content standards: Deployment and Integrations are separate sections; a distinct "New integrations" section for brand-new ones; a "Default container image updates" section for tag bumps. The release-date badge + GitHub release-notes link render automatically from publishDate + slug — never hand-place them.
• Resource artwork: Every new release page must set resourceImage to newly captured screenshots demonstrating a feature introduced in that release, with matching light/dark variants. Verify the running product version and capture its actual UI; do not substitute generic dashboard artwork, an older release's screenshots, or fabricated UI. Store the files in the release's assets folder before adding their paths, and show them beside the feature in the article. The resource directory discovers release pages and consumes this frontmatter automatically; do not add a duplicate catalog entry. Verify the card's image and release metadata in the resource-catalog tests and browser preview.

Safety / mechanics

• Never run bun run build locally — validate build-readiness by inspection.
• Each modality is idempotent — safe to re-run; critique/validate loop to convergence.
• Re-validate after polish. Any edit {polish} makes lands after the {validate} gate, so {polish} must finish with a fresh {validate} pass and {review} confirms it — the committed article never bypasses validation.
• Prefer built-in tools over shell; Windows-friendly paths.

Key repository paths

What	Path
What's-new pages	src/frontend/src/content/docs/whats-new/aspire-N-N.mdx (JA under .../ja/whats-new/)
Version constants	src/frontend/config/aspire-versions.mjs (currentAspireMajorMinorVersion, currentAspireVersion, currentAspireReleaseDate, currentAspirePreviewVersion)
Sidebar	src/frontend/config/sidebar/docs.topics.ts (What's-new items)
Announcement banner	banner: frontmatter on src/frontend/src/content/docs/index.mdx, src/frontend/src/content/docs/docs.mdx, src/frontend/src/content/docs/community/index.mdx, and each src/frontend/src/content/docs/{locale}/index.mdx (+ .../ja/docs.mdx); rendered by src/frontend/src/components/starlight/Banner.astro
Assets	src/frontend/src/assets/whats-new/aspire-<version>/
Container image data	src/frontend/src/data/container-images.json
Diagnostics articles	src/frontend/src/content/docs/diagnostics/aspire<area><NNN>.mdx → /diagnostics/aspire<NNN>/
Data ingestion	src/frontend/scripts/update-integration-data.ps1 (bun run update:all)

Orchestrated skills

doc-writer (voice/style) · doc-pr-reviewer (validate loop) · doc-tester (review blind run) · twoslash-validator (TS samples) · update-integrations / update-samples / container-images (polish data ingestion).