| 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:
- Release — identifier in
release-YYYY-MM format where the deprecation is being introduced. Accept plain year/month and normalise it yourself.
- 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).
- 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.
- Notification code(s) — the
LivingdocsDeprecation code(s) this deprecation emits (e.g. LIDEP000). Collect all of them if there are several. Say "no" if it emits no runtime warning.
- Notion requirement URL — original requirement page (if available). Say "no" to skip.
- 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 concise 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
- Open
content/operations/releases/<release-identifier>.md.
- Locate
## Deprecations :warning:.
- Append the entry at the end of that section, before the next
## heading.
- 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.
