deprecate

/deprecate

You are executing the /deprecate skill. This skill prepares a published content artifact for deprecation by producing a deprecation-notice.md companion artifact and a proposed frontmatter transition on the source content. It does not flip the source content's status on its own — per P8/R25, only the user's explicit natural-language signal authorizes the transition.

All relative paths below are relative to the project root, normally the directory containing project-root MANIFEST.md.

Artifact contract (P4)

This skill reads:

• The target content artifact's frontmatter — at minimum: id, type, status, brand, produced_by, updated, optional published_at, published_to. The artifact MUST have status: published for deprecation to apply.

This skill produces:

• deprecation-notice.md — a sibling artifact next to the source content, declaring the deprecation reason, grace period, effective date, optional replacement, and migration notes. Carries its own frontmatter (type: content/deprecation-notice, status: draft, for: "[[<source-id>]]").

This skill prepares, then performs only after explicit user acceptance:

• Source content transition: status: published → deprecated, adds deprecated_at: <ISO date>, optional superseded_by: "[[<successor-id>]]". Per P8, this transition requires the user's explicit accept signal (e.g., "yes, deprecate it", "go ahead and mark it deprecated"). Until that signal arrives, the source remains status: published.

Transitions declared:

Artifact	Field	Transition	Authority
deprecation-notice.md	status	(create as draft) → greenlit	requires user accept (P8)
source content	status	published → deprecated	requires user accept (P8)
source content	deprecated_at	(none) → <ISO date>	written together with status
source content	superseded_by	(none) → "[[<successor>]]"	written if user provided one
notice manifest entry	status	draft → approved	translated from notice greenlit per R61 after user accept
source manifest entry	status	remains approved while public; later archival sweep may mark superseded	deprecation does not archive or relocate

Open question

Open question Q-deprecated-status remains doctrinal: whether deprecated is a sub-state of published or a fourth terminal state. The skill operates correctly under either reading because it does not archive or relocate the source during deprecation.

Context resolution

Parse input

Extract from natural-language input ($ARGUMENTS):

Parameter	Detection	Default
source_ref	A wikilink, project-relative path, or id: value naming the published artifact	REQUIRED — abort if missing
reason	Human-readable deprecation reason	REQUIRED — abort if missing
grace_days	--grace-days <N> or "with N days notice" / "30 day grace"	30
superseded_by	--superseded-by <ref> or "replaced by " / "successor: "	(none)
contact	--contact <addr> or "questions to "	(none)

Resolve the source artifact

1. Read project-root MANIFEST.md first. If no manifest exists, stop with a defensive-incomplete response and ask the orchestrator to run the project-local bootstrap routine or provide a contract-valid project root.
2. If source_ref looks like a wikilink [[<id>]], resolve it from the manifest entries: block by matching entry id/key/path/frontmatter reference. Do not glob the filesystem for routing.
3. If source_ref is a path, use it only after confirming the same artifact is indexed in MANIFEST.md; do not route from direct paths alone.
4. If neither matches, ask the user to disambiguate and stop.

Read the resolved artifact's frontmatter. Required fields: id, type, status. Recommended: brand, produced_by, updated, published_at, published_to.

Step 1: Validate eligibility

The source content's status must be published. Apply the matrix:

Current status	Action
published	Proceed
deprecated	Already deprecated — report no-op; if superseded_by was supplied and the source has no successor recorded, offer to amend the existing notice (a separate accept gate).
archived	Report no-op (the artifact is already past the public surface; _archive/ is where it lives).
draft | review | greenlit	Refuse: deprecation applies to published content. Suggest archival via the standard P10 archive pattern (move to project-root _archive/ with status: archived).
(missing)	Refuse — content needs a status frontmatter field to be eligible.

If the matrix produces a refusal or no-op, report the reason and stop without writing anything.

Step 2: Compute effective date

Compute effective_date = today + grace_days in ISO 8601 format. Use Python for cross-platform reliability (avoids GNU vs BSD date differences):

python3 -c "from datetime import date, timedelta; print((date.today() + timedelta(days=${GRACE_DAYS})).isoformat())"

If grace_days is 0, the deprecation is immediate — say so in the notice ("effective immediately" rather than a future date).

Step 3: Write deprecation-notice.md

Write the notice next to the source artifact (same directory) using your Write tool. Name it deprecation-notice.md (or <source-id>-deprecation-notice.md if multiple coexist in one directory). Per R28 + R34, this skill does not ship a helper script — Claude's Write tool handles YAML emission safely (no shell-quoting injection surface for title, contact, brand, etc.), which is exactly why this step is inline rather than scripted.

Frontmatter template:

---
id: <source-id>-deprecation-notice
title: "Deprecation notice — <source title>"
type: content/deprecation-notice
status: draft
for: "[[<source-id>]]"
brand: <source brand>
reason: |
  <human-readable reason from $ARGUMENTS>
grace_period_days: <N>
effective_date: <ISO date>
superseded_by: "[[<successor-id>]]"     # omit if none
contact: <contact info>                  # omit if none
produced_by: deprecate
created: <YYYY-MM-DD>
created_at: <ISO8601 timestamp>
references:
  - "[[<source-id>]]"
---

Body template:

# Deprecation notice — <source title>

This notice accompanies `[[<source-id>]]` and announces its end-of-life as a
canonical reference.

## Why

<reason — expand from frontmatter; provide the editorial context>

## Timing

- **Grace period**: <N> days
- **Effective**: <effective_date>
- **Current status**: published (deprecation pending user accept)

## Replacement

<if superseded_by:>
The successor is [[<successor-id>]]. Readers should consult the successor for the
current treatment of the topic.
<else:>
No direct successor is identified at this time. The topic may be revisited later
or remain deprecated indefinitely.
</if>

## Migration notes

<optional: how to migrate links, outbound references, audience messaging>

## Contact

<contact info if provided; otherwise omit this section>

## What happens at accept

When the user accepts this deprecation (e.g., *"yes, deprecate this"* or *"go
ahead, mark it deprecated"*), this skill (or its successor invocation) will:

1. Flip this notice's `status` from `draft` to `greenlit`, set `accepted_by`,
   `accepted_at`.
2. Flip the source content's `status` from `published` to `deprecated`, set
   `deprecated_at: <today>`, and `superseded_by: "[[<successor>]]"` if
   provided.
3. Leave both artifacts in place at their canonical publication location. The
   notice rides alongside the source for the rest of the source's visible life.

After the grace period elapses (or whenever the project decides), a separate
sweep may move both artifacts to project-root `_archive/` with `status: archived`
per P10 §6.4 of ARCHITECTURE.

Write accepted_by and accepted_at only if the user's accept signal is already in this turn's conversation; otherwise leave them out and surface the proposal.

Step 4: Surface the proposal to the user

After writing deprecation-notice.md, report:

Deprecation notice drafted for: <source-id>

  Notice: <path>/deprecation-notice.md
  Status: draft (awaiting user accept per P8)

  Reason: <reason>
  Grace period: <N> days
  Effective: <effective_date>
  Successor: <[[id]] or "none">

  Proposed source transitions (NOT yet applied):
    status:         published → deprecated
    deprecated_at:  <today>
    superseded_by:  [[<successor>]]    (if provided)

  To accept: tell me "yes, deprecate it" (or any clear natural-language signal
  per P8). I will then flip the source frontmatter and greenlight the notice.
  To revise: tell me what to change in the reason, grace period, or successor.
  To cancel: tell me "drop this" or "never mind" and I'll delete the draft notice.

Step 5 (only on user accept signal)

When the user clearly accepts (P8 — explicit natural-language signal interpreted by the AI), perform the transitions:

1. Update source content frontmatter in place:
   • status: deprecated
   • deprecated_at: <today ISO date>
   • superseded_by: "[[<successor-id>]]" (only if provided)
   • updated: <today ISO date>
2. Update deprecation-notice.md frontmatter:
   • status: greenlit
   • accepted_by: <user>
   • accepted_at: <ISO timestamp>
   • updated: <today ISO date>
3. Optionally, if the successor exists and has frontmatter, add supersedes: "[[<source-id>]]" to the successor (mirror of superseded_by). Skip silently if the successor file is unresolvable.
4. Report:

   Deprecation accepted.
   
     Source: <source-id> → status: deprecated (deprecated_at: <today>)
     Notice: <path>/deprecation-notice.md → status: greenlit
     Successor: [[<successor>]] (if any) ← supersedes link added
   
   The artifacts stay at their current location. A future archival sweep (per
   P10 §6.4) can move both to project-root _archive/ when the project decides.
   

Critical: do not perform the transitions on a tentative signal ("looks good, but let me sleep on it"). Per P8, leave the notice in status: draft until the cue is unambiguous.

Idempotency

• The notice file is written deterministically; running /deprecate twice on the same source overwrites the previous draft notice (single canonical notice per source). The user is informed when an overwrite happens.
• If the source already has status: deprecated, the skill is a no-op (Step 1 refusal).
• Successor links are mirrored only if the successor exists; otherwise silent.

Error handling

Condition	Message	Action
source_ref not provided	"Error: provide the content artifact to deprecate (wikilink, id, or path)."	Abort
reason not provided	"Error: deprecation needs a human-readable reason."	Abort
Source not resolvable	"Error: cannot find a content artifact matching ''."	Abort, suggest narrowing
Source missing status frontmatter	"Error: source has no status field; cannot determine eligibility."	Abort
Source status != published	"Cannot deprecate — source is <state>. Deprecation applies to published content only."	Refuse with explanation
File write failure	"Error: failed to write deprecation-notice.md at <path>."	Abort with path

Storage tier compliance

• READ FROM: source content artifact (frontmatter + optional body for context).
• READ FROM: knowledge file knowledge/lifecycle_deprecation.md for the lifecycle vocabulary.
• WRITE TO: deprecation-notice.md next to the source artifact.
• WRITE TO: project-root MANIFEST.md entry for the notice when the project is contract-valid.
• WRITE TO (only on user accept): source content frontmatter (status, deprecated_at, superseded_by, updated), the notice's own frontmatter (status, accepted_by, accepted_at, updated), and the source/notice manifest-entry statuses translated per R61.
• NEVER writes to a pipeline.yaml, a phase state file, or any .ccf/ or .ccf-core/ directory (those concepts do not exist in this ecosystem; P1 + R19).
• NEVER moves the source content out of its published location on deprecation — relocation to _archive/ is a separate sweep at the project's discretion (P10 §6.4).

Natural-language examples

# Standard deprecation with successor
/deprecate [[iurfriend-q1-content-trennungsjahr-2024]] "Content outdated — 2025 legal reform; replaced by Q2 update" --superseded-by [[iurfriend-q2-content-trennungsjahr-2026]]

# Immediate deprecation, no successor
/deprecate content/trennungsjahr/published.mdx "Topic retired — no longer relevant to current audience journey" --grace-days 0

# Conversational form
/deprecate "Please deprecate the trennungsjahr article from Q1 2024. Reason: legal reform 2025. Successor: trennungsjahr 2026."

Related skills

• /content-writer — produces the successor content that supersedes the deprecated artifact.
• /editor — reviews the deprecation notice's reason and migration guidance against the brief.
• For surfacing all status: deprecated artifacts, resolve entries from project-root MANIFEST.md and then read the artifacts' own frontmatter. Do not use workspace walks for routing.
• The archival sweep described in PRINCIPLES.md P10 / ARCHITECTURE §6.4 handles eventual move of deprecated artifacts to project-root _archive/. That is not this skill.

References

• PRINCIPLES.md P1 (artifacts carry state), P4 (artifact contracts), P8 (user accept), P10 (terminal states + ephemera).
• ARCHITECTURE.md §6.4 (archival pattern), §4.4 (artifact lifecycle), §8 (touchpoints).
• DECISIONS.md R19 (single-layer plugin layout), R21 (P10 added), R25 (no universal commands).

End-of-run (R26 — conditional)

Standard runs (source resolved, notice drafted, proposal surfaced, user accepts or revises) end normally — no self-improvement prompt fires.

The prompt fires only on deviation. Triggers and prompt shapes:

• User waived eligibility (e.g., asked to deprecate a greenlit piece instead of routing to archival sweep) → "I deprecated a <state> piece this time, contrary to the eligibility matrix. Should we add <state> to the matrix as eligible, or is this a one-off?"
• User overrode the grace-period default → "You set grace-days to <N> — distinctly different from the 30-day default. Is <N> a better default for this brand/campaign, or genuinely case-by-case?"
• User added a --contact or --superseded-by value with surprising shape (multi-recipient contact, multiple successors) → "The deprecation accepted <unusual input shape>. Should the notice template support <feature> as a first-class field?"
• User tentatively signalled then revoked accept ("yes — actually wait") → "We rolled back the accept this time. Should the proposal surface (Step 4) include a clearer 'I'm not sure yet' branch?"
• The script-retirement R28 path produced friction (e.g., user expected a --force-overwrite flag) → "You expected <flag> from the retired helper; we used inline Write. Should the SKILL.md document the overwrite-safety semantics more explicitly?"

If the user confirms, update SKILL.md (and knowledge/lifecycle_deprecation.md if the change is architectural) inline before going idle. If the user declines or doesn't engage, do nothing.

Language Handling

• Detect the conversation language; respond in the user's language unless explicitly asked otherwise.
• Before applying conversation-language detection, check project-root MANIFEST.md for output_language:; honor that declaration if set. Per P12 + R35, the declared language takes precedence over inferred conversation language for the deprecation notice body.
• Translate internal checklist labels and headings naturally — do not force English headings into non-English output.
• Preserve legal, financial, and technical terms in their original language (Trennungsjahr, MwSt, BTW, Aufhebungsvertrag, etc.).
• Preserve Unicode characters natively (ü, ö, ä, ß, etc.); never substitute transliterations (ue, oe, ae, ss).
• Frontmatter field names and enum values stay English regardless of content language. Free-text frontmatter values may follow content language where natural.
• The deprecation notice's body (reason, migration guidance, contact instructions) follows the language of the source artifact being deprecated — a German getrennt-leben piece gets a German deprecation notice. The frontmatter (status, deprecated_at, superseded_by, reason) stays structured per the contract above; the prose explanation in the body is localized.

Input

Arguments: $ARGUMENTS