TRN authoring skills + format reference (AI-parsable breaking changes & deprecations)

.claude/skills/write-trn-breaking-change/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: write-trn-breaking-change
+description: Write a Breaking Change entry for a Livingdocs Technical Release Note (TRN) and insert it into the correct release file. Use this skill whenever a developer wants to document a breaking change, mentions "write breaking change", "add breaking change to release notes", or provides PR URLs and asks to document a breaking change for a specific release (e.g. "write the breaking change for release-2026-05"). This skill handles the full workflow: gathering PR details, writing the entry with Detect/Fix sub-sections, and inserting it into the release file.
+---
+
+# Write TRN Breaking Change Entry
+
+Breaking changes are the most upgrade-critical section of the TRN. Each entry must be detectable and fixable from its own text — an AI agent or operator should be able to walk through Breaking Changes and apply each fix without consulting other documentation.
+
+This skill is the **workflow**. The entry's shape, tone, and rules live in `.claude/trn-format-reference.md`, which is the source of truth — read it before drafting and follow it rather than relying on memory.
+
+## Step 1: Gather inputs
+
+Ask **one question at a time** — wait for each answer before asking the next:
+
+1. **Release** — identifier in `release-YYYY-MM` format. Accept plain year/month and normalise it yourself.
+2. **GitHub PR URLs** — ask whether they'd like to add all URLs at once or one at a time. If one at a time: ask for the first URL, then ask "Any more PRs? (say 'done' to continue)" and keep collecting until done. If all at once: accept a list of URLs in a single message.
+3. **Notification code(s)** — the `LivingdocsBreakingChange` code(s) this change emits (e.g. `LIBREAKING000`). Collect all of them if there are several (e.g. one per affected property, like `LIBREAKING000-propertyOne`, `LIBREAKING000-propertyTwo`). Say "none" if the change emits no runtime warning (e.g. a static-only concern such as direct `lib/` imports).
+4. **Notion requirement URL** — original requirement page (if available). Say "none" to skip.
+5. **Additional context** — free-form notes from the developer about the breaking change. Optional.
+
+## Step 2: Read the sources
+
+- Fetch each GitHub PR: title, description, linked issues, code diff. Pay attention to:
+  - Which config properties, API endpoints, or source-level imports are affected.
+  - The old shape vs. the new shape (verbatim — Detect and Fix lines must use the exact property names from the code).
+  - Whether the change is mechanical (e.g. property rename, key move) or judgment-based (e.g. semantic conflict where the user must choose).
+- If a Notion URL was provided, fetch it to understand the original motivation.
+- **Check earlier releases for a matching deprecation.** Most breaking changes that remove a property, API, or behaviour were first announced as a deprecation in an earlier release — typically around three releases earlier, though this is not guaranteed. Look under `## Deprecations :warning:` in the earlier `content/operations/releases/release-YYYY-MM.md` files. If you find one, its prose, Detect, and Fix are a strong starting point — adapt them rather than writing from scratch. Still review it end to end: details may have changed between the deprecation announcement and the actual removal, and the deprecation entry may have surfaced edge cases worth carrying over.
+- Read the existing `## Breaking Changes :fire:` section in `content/operations/releases/<release-identifier>.md` to calibrate tone and to confirm the change isn't already documented.
+
+## Step 3: Write the breaking change entry
+
+Write the entry following the **Breaking Change entry shape** and its **Rules** in `.claude/trn-format-reference.md` — the source of truth for the title, the `**Code:**` line, the exhaustive prose intro with before/after, the greppable `Detect`, and the `Fix`. Read it now rather than restating it here.
+
+Skill-specific note: if you adapted an earlier deprecation entry (Step 2), carry over its still-accurate detail and update whatever changed between the deprecation and the removal.
+
+## Step 4: Ask for feedback
+
+Show the draft to the developer:
+
+> _"Here's the draft. Does it look right? Anything to adjust — wording, missing edge cases, or the Detect/Fix specificity?"_
+
+Apply any requested changes. If the developer flags the entry as a deprecation rather than a breaking change, switch to the `write-trn-deprecation` skill instead.
+
+## Step 5: Insert into the release notes file
+
+1. Open `content/operations/releases/<release-identifier>.md`.
+2. Locate `## Breaking Changes :fire:`.
+3. Append the entry at the end of that section, before the next `##` heading.
+4. Save and confirm to the developer.
+
+## Step 6: Sanity-check after insertion
+
+Verify the finished entry against the **Rules** in `.claude/trn-format-reference.md` (icon-free `###` heading, `**Code:**` line with codes verbatim from the source, greppable Detect, both Detect and Fix present, no extra `####` sub-headings). Then confirm the insertion itself: the entry sits inside `## Breaking Changes :fire:`, before the next `##` heading.
+
+If any check fails, surface it to the developer and propose a fix before closing.

.claude/skills/write-trn-deprecation/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: write-trn-deprecation
+description: Write a Deprecation entry for a Livingdocs Technical Release Note (TRN) and insert it into the correct release file. Use this skill whenever a developer wants to document a deprecation, mentions "write deprecation", "add deprecation to release notes", or provides PR URLs and asks to document a deprecation for a specific release (e.g. "write the deprecation for release-2026-05"). This skill handles the full workflow: gathering PR details, writing the entry with Detect/Fix sub-sections and a planned removal release, and inserting it into the release file.
+---
+
+# Write TRN Deprecation Entry
+
+Deprecations announce future removals. They share the structure of Breaking Changes (`Detect` / `Fix` sub-sections) and differ in one way: deprecations name a **planned removal release** so the reader can schedule the migration.
+
+This skill is the **workflow**. The entry's shape, tone, and rules — including the deprecation-specific and opt-in-default-behaviour cases — live in `.claude/trn-format-reference.md`, which is the source of truth. Read it before drafting and follow it rather than relying on memory.
+
+## Step 1: Gather inputs
+
+Ask **one question at a time** — wait for each answer before asking the next:
+
+1. **Release** — identifier in `release-YYYY-MM` format where the deprecation is being introduced. Accept plain year/month and normalise it yourself.
+2. **Planned removal release** — when will the deprecated property / API / behaviour be removed? Accept `release-YYYY-MM` format, or "no fixed removal release" if the deprecation is open-ended (e.g. an opt-in API default-behaviour change).
+3. **GitHub PR URLs** — ask whether they'd like to add all URLs at once or one at a time. If one at a time: ask for the first URL, then ask "Any more PRs? (say 'done' to continue)" and keep collecting until done. If all at once: accept a list of URLs in a single message.
+4. **Notification code(s)** — the `LivingdocsDeprecation` code(s) this deprecation emits (e.g. `LIDEP000`). Collect all of them if there are several. Say "none" if it emits no runtime warning.
+5. **Notion requirement URL** — original requirement page (if available). Say "none" to skip.
+6. **Additional context** — free-form notes from the developer. Optional.
+
+## Step 2: Read the sources
+
+- Fetch each GitHub PR: title, description, linked issues, code diff. Pay attention to:
+  - Which config property, API endpoint, or behaviour is being deprecated.
+  - What the replacement is (different shape, opt-in flag, alternative property, etc.).
+  - Whether the migration is mechanical (a property rename or move) or discretionary (the user chooses how to map the old usage to the new model).
+- If a Notion URL was provided, fetch it to understand the original motivation.
+- Read the existing `## Deprecations :warning:` section in `content/operations/releases/<release-identifier>.md` to calibrate tone and to confirm the deprecation isn't already documented.
+
+## Step 3: Write the deprecation entry
+
+Write the entry following the **Deprecation entry shape** and its **Rules** in `.claude/trn-format-reference.md` — the source of truth for the title, the `**Code:**` line, the exhaustive prose intro (which must name the planned removal release) with before/after, the greppable `Detect`, and the `Fix`. Read it now rather than restating it here.
+
+## Step 4: Ask for feedback
+
+Show the draft to the developer:
+
+> _"Here's the draft. Does it look right? Anything to adjust — wording, the planned removal release, or the Detect/Fix specificity?"_
+
+Apply any requested changes. If the developer flags the entry as a breaking change rather than a deprecation, switch to the `write-trn-breaking-change` skill instead.
+
+## Step 5: Insert into the release notes file
+
+1. Open `content/operations/releases/<release-identifier>.md`.
+2. Locate `## Deprecations :warning:`.
+3. Append the entry at the end of that section, before the next `##` heading.
+4. Save and confirm to the developer.
+
+## Step 6: Sanity-check after insertion
+
+Verify the finished entry against the **Rules** in `.claude/trn-format-reference.md` (icon-free `###` heading, `**Code:**` line with codes verbatim from the source, prose names a planned removal release or states none, greppable Detect, both Detect and Fix present, no extra `####` sub-headings). Then confirm the insertion itself: the entry sits inside `## Deprecations :warning:`, before the next `##` heading.
+
+If any check fails, surface it to the developer and propose a fix before closing.

.claude/skills/write-trn-feature-section/SKILL.md

@@ -28,7 +28,7 @@ Ask **one question at a time** — wait for each answer before asking the next:
 **Example 1 - Simple (auto-available, no config):**
 
 ```markdown
-### Optimized Media Library Modal :gift:
+### Optimized Media Library Modal
 
 We've optimized the image selection modal to display more images by increasing its width. The modal now shows up to 6 images per row (depending on screen size), compared to the previous layout. This makes better use of available screen space.
 
@@ -38,7 +38,7 @@ For more information, see the [Media Library]({{< ref "/reference/media-library"
 **Example 2 - Complex (sub-sections, config, before/after):**
 
 ```markdown
-### Distribution Dates UI Improvements :gift:
+### Distribution Dates UI Improvements
 
 Editors use the planning board to manage articles scheduled for publishing and distribution. Setting distribution dates quickly and accurately is essential for efficient workflow management.
 
@@ -78,7 +78,7 @@ For more information, see the [Distribution Dates]({{< ref "/reference/distribut
 Use this format:
 
 ```
-### FEATURE NAME :gift:
+### FEATURE NAME
 
 INTRO_PARAGRAPH
 
@@ -104,7 +104,7 @@ INTRO_PARAGRAPH
 - **Complex topics**: add _"Reach out to your customer solutions contact for help getting started."_ if setup is non-trivial.
 - **Sub-sections**: use `####` headings for multiple distinct sub-features or steps.
 - **Links**: `{{< ref "/path" >}}` for internal docs. `{{< release "release-YYYY-MM" >}}` for other releases.
-- **`:gift:` emoji**: always append to the `###` heading.
+- **No emoji on the entry heading**: the `:gift:` lives on the `## Features` section heading only (see `.claude/trn-format-reference.md`).
 
 #### Tone & style