Tombstone Pattern

How to retire a doc, plan, ADR, screen, or package without losing the trail.

TL;DR (human)

Retired content keeps its file but gets a 🪦 status block prepended. Back-references are updated to mark it retired without removing the link. The historical record stays intact; the agent reading the file knows immediately it is no longer active.

For agents

Why not delete

Deletion loses three things:

1. The decision trail. Future agents need to know that something was the answer, why it was, and why it changed. The file is the evidence.
2. Back-references. Other docs / ADRs / commit messages link to it. Hard links break; agents follow broken links and waste a turn.
3. Audit history. Compliance / governance / security reviews need to see what existed and when.

Git history preserves some of this, but git history is hard to discover. The file at its path with a clear retirement marker is discoverable in one read.

Tombstone block format

Prepend to the top of the file, above the original title:

> 🪦 **TOMBSTONED YYYY-MM-DD** — <one-line reason: what replaced it, or why retired>.
> Kept for trail; do not treat as active.

# <original title kept>

<original body kept verbatim>

Required fields:

• 🪦 emoji — visual signal.
• TOMBSTONED — the keyword.
• YYYY-MM-DD — when it was retired. ISO date.
• Reason — one line.
• Pointer to the replacement (if any).

When to tombstone

When not to tombstone

Back-reference sweep

When you tombstone, sweep references:

1. grep -r "path/to/tombstoned.md" — every other doc that links here.
2. Update each linking doc to either:
   • Update the link target to the replacement, or
   • Leave the link but add a parenthetical "(🪦 retired)".
3. Update top-level indexes (README.md, docs/README.md, INDEX.md) — the file may still appear, but its row says "🪦 retired".

Goal: no surprise. A reader landing on a back-reference learns immediately that the target is retired.

Tombstones are immutable

Once a file is tombstoned, do not edit its body. The body is the historical record. The only allowed edit is to update the tombstone block itself (e.g. fix a typo, add a more current replacement link).

If the body needs to be updated to "be correct again", you do not want a tombstone — you want an edit.

Rolling up tombstones

After a long campaign of work, many tombstoned files accumulate. They are still discoverable and that is good. But indexes can get noisy.

Periodic clean-up:

1. Move tombstoned files into a sibling _archive/ directory.
2. Update back-references to the new path.
3. Index file lists archived items at the bottom in a collapsed section.

This is not deletion. It is demotion in discoverability, with the trail intact.

Common failure modes

• Tombstone without back-reference sweep. Other docs still treat the retired file as authoritative. → Always sweep. A check:back-refs gate helps.
• Tombstone followed by "actually let me edit this". Confuses readers — is it retired or not? → Decide first; if you edit, it's not a tombstone.
• Delete + new file with same name. Loses the trail entirely. → Tombstone the old, new file goes by a new name (or same name with a clear ### Replaces tombstoned \<old\> block at top).
• Tombstone with no reason. Reader has no idea why it was retired. → One-line reason is mandatory.

See also

• universal.md — Rule 4.
• ../architecture/adr-pattern.md — Status: Superseded is the ADR-specific tombstone.