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/`](./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`](./references/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`](./references/02-research.md) | **Yes — drafts the body** | | `critique` | — | Content-quality **self-review** of draft vs dossier; severity-ranked findings. | [`03-critique.md`](./references/03-critique.md) | **No — reports only** | | `validate` | — | **Ralph loop** with `doc-pr-reviewer` until 100% factual; samples/links/assets. **No `pnpm build`.** | [`04-validate.md`](./references/04-validate.md) | Fixes only | | `polish` | — | Editorial pass + CI triage + diagnostics-author `@mentions` + **automated data ingestion**, then a **final `{validate}` pass**. | [`05-polish.md`](./references/05-polish.md) | **Yes** | | `review` | — | Undraft PR, description, reviewers + `doc-tester` **blind** run of every in-article scenario. | [`06-review.md`](./references/06-review.md) | No | ## Supporting references - [`whats-new-template.mdx`](./references/whats-new-template.mdx) — structure-only skeleton the `draft` phase copies (scaffold tokens, `publishDate` frontmatter, and the mandated section taxonomy). - [`writing-guidelines.md`](./references/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 `pnpm 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` (`pnpm 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).