/happier-release-notes

name: happier-release-notes
description: Author, update, validate, and publish-ready Happier release-note story decks. Use when creating curated release notes, analyzing commits/diffs/tags to discover user-facing changes, brainstorming detailed and short release notes, adding story-deck cards, adding release-note images/videos/posters, validating translation keys and asset references, preparing happier-assets upload inputs, or updating onboarding showcase story content.

Happier Release Notes

Mission

Create curated, explicit story-deck content for Happier releases with offline-safe lightweight visuals. Bundle image-card artwork and video posters in the app when practical; keep heavy video files and optional remote fallbacks in `happier-dev/happier-assets`.

Read First

1. Read `apps/ui/release-notes/README.md`. 2. Read `apps/ui/release-notes/releases/README.md`. 3. Inspect the current card contract in `apps/ui/sources/changelog/releaseNotes/types.ts` and schema limits in `storyDeckCardLimits.ts`. 4. If editing UI behavior, follow TDD and use the canonical UI testkit.

Author A Release

Use this path only after the user has approved the release-note content or has provided final content explicitly.

1. Determine the runtime release id. Current convention: `v<Constants.expoConfig.version>`, for example `v0.2.7`. 2. Create `apps/ui/release-notes/releases/<releaseId>.json`. 3. For image cards and video posters, prefer bundled assets: add the file under an app source asset folder and register it in `apps/ui/sources/components/ui/storyDeck/storyDeckBundledAssetRegistry.ts`. 4. For heavy videos and optional remote fallbacks, add media under `apps/ui/release-notes/assets/<releaseId>/`. 5. Add every translation key to all files in `apps/ui/sources/text/translations/`. 6. Run from `apps/ui`:

yarn tsx sources/scripts/parseReleaseNotes.ts

7. Confirm generated files changed only under `apps/ui/sources/changelog/releaseNotes/manifest.generated.json` and `asset-index.generated.json`.

Analyze A Release From Git

Use this path when the user asks to create/propose release notes from commits, tags, a branch diff, or a specific comparison range.

Determine The Range

Prefer an explicit user-provided range. If absent, infer the previous release tag conservatively and state the assumption before proposing content.

Useful commands:

git --no-pager tag --sort=-creatordate
git --no-pager log --oneline --decorate <from>..<to>
git --no-pager log --format='%H%x09%s' <from>..<to>
git --no-pager diff --stat <from>..<to>
git --no-pager diff --name-status <from>..<to>

For component tags, inspect the tag naming already present in the repo (`cli-v*`, `ui-v*`, `v*`, etc.) and match the component the user requested.

Inspect Commit Contents, Not Just Messages

Commit messages are only the index. For every candidate user-facing cluster, inspect the actual changes:

git --no-pager show --stat --name-status <commit>
git --no-pager show --format=fuller --find-renames <commit> -- <relevant-paths>
git --no-pager diff <from>..<to> -- <relevant-paths>

Prioritize reading:

• changed app screens/components under `apps/ui/sources/app/**` and `apps/ui/sources/components/**`
• protocol feature/catalog changes under `packages/protocol/**`
• CLI user-facing commands, installer, doctor, daemon, and provider flows under `apps/cli/**`
• server API, feature gates, sync, notifications, and storage changes under `apps/server/**`
• tests that describe user-visible behavior
• docs/changelog entries only as corroborating context

If a commit is ambiguous, inspect neighboring commits in the same cluster, touched tests, changed feature flags, and runtime wiring. Do not surface an item until you can explain what changed for a user/operator and why it matters.

Cluster And Filter

Cluster by user-facing outcome, not by commit count. Good clusters look like:

• a new product capability
• a visible UI/UX improvement
• a CLI command or workflow improvement
• a reliability fix that users would recognize
• a platform-specific support improvement
• a provider/model capability users can choose

Exclude or down-rank:

• pure refactors with no user-facing behavior
• internal test-only changes
• mechanical migrations
• dependency bumps unless they unlock visible capability or fix a user-visible bug
• duplicate commits that belong to a larger feature cluster

Proposal Output

Before writing release JSON, propose content for discussion:

1. Detailed release notes in markdown:

• `New Features`
• `Improvements`
• `Bug Fixes`
• platform/provider-specific sections when useful
• concise but concrete bullets based on inspected diffs

2. Short release-note StoryDeck proposal:

• 3-6 high-impact cards by default
• recommended card order
• proposed `list`, `image`, and `video` cards
• suggested row titles/body copy
• suggested screenshots, diagrams, or videos to capture
• any asset filenames to create under `apps/ui/release-notes/assets/<releaseId>/`

3. Confidence notes:

• assumptions about the git range/tag
• ambiguous items that need user confirmation
• items intentionally excluded from prominent cards

Ask the user to approve or revise the proposed detailed notes and StoryDeck before baking them into files. Do not create or overwrite authored release JSON from commit analysis without user approval, unless the user explicitly asked for direct implementation.

Brainstorm With User-Provided Content

When the user provides rough notes instead of asking for Git analysis:

1. Normalize the notes into user-facing outcomes. 2. Ask clarifying questions only when a missing decision materially changes the output. 3. Propose detailed markdown release notes and a short StoryDeck candidate. 4. Recommend which items deserve images/videos and which should stay in detailed notes only. 5. Bake the approved version into release-note files.

Detailed Markdown Styl