Sefaria Release Notes

Sefaria Release Notes Generator

Reads a shipped-stories JSON file (produced upstream by build/ci/shipped_stories.py, which deterministically walks the git tree between two prod tags and calls the Shortcut API) and writes two Slack-formatted files from it: release notes for engineers, and a release announcement for everyone else. This skill does not fetch anything from GitHub or Shortcut and does not mutate any Shortcut story — it only reads the JSON and writes prose. In a non-interactive run, never ask a clarifying question — proceed with the Edge Cases table's defaults.

Inputs

• Path to the shipped-stories JSON file — default filename shipped-stories.json
• Output directory — defaults to the project root

The JSON has this shape:

{
  "version": "6.111.0-prod.2",
  "chart_version": "0.87.5-prod.1",
  "release_date": "2026-08-31T07:17:36Z",
  "range": {"previous_tag": "...", "current_tag": "...", "spec": "PREV..CUR"},
  "commits": [{"subject": "...", "pr_number": "3644", "branch": "feature/sc-11111/x", "story_ids": ["11111"]}],
  "commits_without_story": ["subject", ...],
  "reverted_commits": [{"subject": "Revert \"...\"", "suppressed_story_ids": ["11111"]}],
  "story_ids": ["11111", ...],
  "stories": [{"id": 11111, "name": "...", "description": "...", "url": "...", "workflow_state_id": 500000045, "story_type": "feature"}],
  "hydrated": true,
  "unresolved_story_ids": []
}

• release_date — ISO 8601 creation timestamp of the resolved current tag, or null if it couldn't be resolved (e.g. an explicit --range against a non-tag ref). This is the header date's only legitimate source — see "Header date" below.
• reverted_commits — commits whose subject matched the Revert "..." / revert: / revert(...) convention, each with the story ids THAT REVERT COMMIT referenced. Never list a story appearing here as shipped, even if you spot it elsewhere while reading the JSON — shipped_stories.py has already excluded it (and, where the reverted original is also in this range, excluded that original's ids too) from story_ids / stories for exactly this reason, unless another independent, non-reverted commit also carries the same id.

Phase 1 — Read and summarise

Read the JSON file. Before generating any output, summarise what you found so the user (or the CI log) can catch issues early:

• Version: app X.X.X / chart X.X.X (from version and chart_version, stripping any -prod.N suffix)
• N commits, N with a resolved story, N in commits_without_story
• N stories in stories, N unresolved_story_ids (note these — they had a story ID but the Shortcut lookup failed; mention them in the tech file as unresolved rather than silently dropping them)

Categorise each story (and, for commits with no story, each commit) into one of four buckets:

1. User-facing — visible feature, UI change, or user-impacting bug fix
2. Backend / performance — API changes, query optimisation, data or matching fixes
3. Infrastructure / DevOps — Helm, CI/CD, Kubernetes, observability
4. AI / eval / platform — chatbot, eval pipeline, ML work shipping in this deploy

Items with no story and no clear user impact can be omitted or listed briefly under backend/infra.

Header date: this runs AFTER the rollout is already confirmed healthy, so both files' headers describe something that already happened, not something upcoming. Format release_date (ISO 8601, e.g. 2026-08-31T07:17:36Z) as a human-readable date (e.g. Aug 31, 2026) and use it in both files' headers — see references/slack-format.md. If release_date is null, omit the date line entirely rather than guessing or fabricating one. There is no sprint/date-range field in the JSON — do not invent one.

Phase 2 — Generate output files

Read references/slack-format.md before writing any output. It contains Slack mrkdwn rules, the exact section structures, and short examples of correct output.

Write two files to the output directory:

release-notes-tech-slack.txt

The release notes. Audience: engineers in a Slack channel. Include story links, PR refs, and technical detail.

• One bullet per item, using the section structure in references/slack-format.md
• 1–3 sentences per item: what changed, root cause for bugs, what it enables for features
• Every item with a story (from the JSON's stories list) MUST include its story link — cross-check each bullet against commits[].story_ids / stories before finalizing
• Flag high-risk items with :warning: (major framework upgrades, DB migrations, iOS SDK changes)

release-announcement-product-slack.txt

The release announcement. Audience: non-engineers. Plain language, no PR numbers, no stack names (Django → "our web framework", Postgres → "the database", etc.).

• Group by impact: what users see, bug fixes, partner/API changes, stability
• Each bullet: 1–2 sentences, named after the feature or fix, not the technical mechanism
• Translate every technical term — if you're unsure whether a term needs translation, translate it
• Ordering rule for :eye: *What users will see and feel*: content updates (new library texts, new books, new categories, newly linked sources) ALWAYS go first — before page retirements, UI fixes, or AI features. These are the most tangible user-facing changes and are what non-technical stakeholders care about most.

Edge Cases

Output Confirmation

After writing both files, report:

• File paths written
• Item counts by section (e.g. "7 user-facing, 5 backend, 4 infra")
• Any :warning: high-risk items by name so the user knows what to watch post-deploy
• Any unresolved story IDs or story-less commits that need human follow-up