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

[ajwild]

What & why

Introduces the authoring tooling for AI-parsable Technical Release Notes (TRN) — so Breaking Changes and Deprecations can be parsed by an AI agent (or read by an operator) to derive and apply the upgrade actions for a release.

This partially replaces #1156. That PR bundled the format change, the authoring skills, theme/rendering changes, and the full release-2026-05 content rewrite into one large change. This PR carves out just the authoring tooling; the release-2026-05 content rewrite and the theme work will follow as separate, smaller PRs.

Contents

• .claude/trn-format-reference.md (new) — the single source of truth for TRN entry shape, tone, and rules.
• .claude/skills/write-trn-breaking-change/ & write-trn-deprecation/ (new) — workflow skills that defer to the reference for format.
• .claude/skills/write-trn-feature-section/ — drop :gift: from feature entry titles, matching the icon-free entry convention.
• content/operations/releases/_release-template.md — add :warning: to the ## Deprecations heading; remove the icon legend.

Key design points

• Detect / Fix contract — each entry is self-contained enough to act on without consulting other docs.
• Greppable Detect lines — a literal token to search for (not an abstract dot-path like mediaTypes[].editor.dashboard), so an agent can actually find the affected config.
• **Code:** line — links each entry to its LivingdocsBreakingChange / LivingdocsDeprecation log code, so a log line maps straight to the entry and its fix.
• Exhaustive prose with before/after for these upgrade-critical sections.
• Skills = workflow, reference = format — no duplicated rules; one place to change the contract.
• Icons on section headings only — entry headings stay icon-free, giving clean anchor slugs.

Out of scope / follow-ups

• release-2026-05 Breaking Changes & Deprecations content rewrite (next PR).
• Full feature-format reformat (thin, Automatic/Configurable, link-out).
• Theme / rendering changes from AI Parsable Technical Release Notes #1156.

🤖 Generated with Claude Code

[dfreier]

At this point, the claude session context will already be filled quite a lot:

• Back and forth messages with the user in Step 1
• PR descriptions, code diffs, Notion pages, other release notes

I would recommend using subagents for reasearch tasks (e.g. 1 subagent per PR, Notion URL, previous releases explorer), where each subagent writes the full report in a file, containing pointers to commits, key files and lines, links to the PR for further info. The subagents only return a structured small summary report to the main session, including the pointer to the full report file.

Then in step 3, use the main session to spawn an opus subagent that builds a plan, based on the research results from the previous steps. The plan is written to the disk as well where it can be reviewed and edited by the developer.

If the plan looks good, spawn another subagent to implement the plan (writing to the trn doc file), give it the file pointers to the research results + the file path to the plan, report summary to the main session.

After all these steps, the main session has still a small context but knows all the summaries from the individual steps and knows the files where to look for additional details. And it has the local git diffs from the implementation step.
From here, use the main session for further iterations before clearing it and moving on to the next TRN entry.

[eileenoo]

What was the motivation to remove the emojis from feature / breaking changes / deprecation entries? Was this an outcome from the interviews (that I don't recall) or where does this come from?
I don't have a strong opinion about it - but as it's more of a style change, I would probably do it together with a refactoring of the UI.

[ajwild]

What was the motivation to remove the emojis from feature / breaking changes / deprecation entries? Was this an outcome from the interviews (that I don't recall) or where does this come from?

There are two reasons, firstly it adds a lot of visual noise to the page and especially the ToC (if #1165 is merged), and secondly it messes up the anchor links (something I find annoying and removing them was also reported as a positive change here).

However, if you would prefer it to stay then I could create a separate ToC partial (which I think I need to do anyway) and try to strip it there, and I could also try to modify how the anchor links are generated.

Having said that, after discussions today it sounds like no more effort should be put into this repo (besides improving Claude skills) and we could aim to delete it by the end of the year. That will depend on how priorities are set for the move to the knowledge base.