System Sunset & Legacy Decommission Plan

Template Overview

Building new software features is exciting; retiring obsolete legacy systems is often neglected. As organizations mature, unmaintained legacy services, deprecated API endpoints, and abandoned database clusters accumulate like digital ghosts, consuming infrastructure budget and creating severe security vulnerabilities.

A graceful System Sunset and Decommission Plan ensures that obsolete software is retired safely: communicating proactively with users, providing automated data export pathways, severing dependencies methodically, and confirming final server teardowns.

This template provides an engineering-grade Decommissioning blueprint: system deprecation justification, communication timeline horizons, customer data migration guides, infrastructure teardown checklists, and final verification certificates.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "Sunset Plan: [Legacy System / Subsystem Name]"
date: [YYYY-MM-DD]
system_to_decommission: "Legacy Flat-File Search Indexer & Ingestion Daemon"
replacement_system: "Embedded SQLite FTS5 Engine ([[ADR-0038]])"
decommission_lead: "[[Staff Systems Engineer]]"
executive_sponsor: "[[VP Engineering Elena Rostova]]"
target_shutdown_date: 2026-11-30
tags: [sunset, decommission, deprecation, infrastructure, technical-debt]
---

# Sunset Plan: [Legacy System / Subsystem Name] — [YYYY-MM-DD]

## 1. System Context & Decommission Justification
- **Legacy System Description:** Custom flat-file search indexer implemented in early beta builds (circa 2024).
- **Why Decommission:** High memory consumption (consumed up to 250MB RSS), slow search latency (>400ms on large vaults), and lack of transaction safety compared to modern SQLite WAL architecture.
- **Replacement:** The SQLite FTS5 embedded search engine is fully deployed and verified to be 10x faster with 70% lower memory footprint.

## 2. Customer & User Migration Strategy
- **Customer Impact:** 100% transparent. Application build 1.4.0 automatically migrates old flat-file index caches into the new SQLite database upon first launch.
- **Data Safety Guarantee:** Zero raw Markdown note files are modified or deleted. Only temporary index metadata is migrated.
- **User Action Required:** None.

## 3. Communication Timeline & Phased Deprecation Horizons
| Timeline Horizon | Milestone / Event | Action Taken | Status |
| :--- | :--- | :--- | :--- |
| **Day -60 (2026-09-30)** | Internal Deprecation Notice | Announced deprecation to engineering; feature flag enabled | 🟢 Completed |
| **Day -30 (2026-10-30)** | Code Deprecation Warning | Marked legacy indexer methods with `@available(*, deprecated)` | 🟢 Completed |
| **Day 0 (2026-11-30)** | Complete Code Removal | Remove legacy flat-file scanner source files from codebase | 🟡 Scheduled |
| **Day +15 (2026-12-15)** | Final Verification Audit | Confirm zero runtime dependencies and purge legacy build flags | Scheduled |

## 4. Technical Teardown & Code Deletion Checklist
- [ ] Remove legacy indexer source files (`src/core/search/legacy_flat_indexer.swift`).
- [ ] Remove legacy unit tests and obsolete mock fixtures.
- [ ] Delete temporary flat-file cache migration scripts from staging builds.
- [ ] Remove obsolete POSIX file lock entitlements from App Sandbox configuration.

## 5. Post-Decommission Verification & Cost Savings
> [!IMPORTANT] Decommission Certification
> Following final code removal, binary size was reduced by 1.8MB and cold-start application initialization time dropped by 85ms.

- [ ] [[Decommission Lead]] Merge final code deletion pull request to main branch.
- [ ] [[VP Engineering]] Archive legacy system documentation into the repository history vault.

Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

---
title: "Sunset: Flat-File Indexer"
date: 2026-10-06
system_to_decommission: "Flat-File Indexer"
replacement_system: "SQLite FTS5"
target_shutdown_date: 2026-11-30
tags: [sunset, decommission]
---

# Sunset: Flat-File Indexer — October 6, 2026

## 1. Summary
Retiring legacy flat-file indexer in favor of SQLite FTS5 engine.

## 2. Benefit
Reduces app binary size by 1.8MB and eliminates 250MB memory footprint.

When to Use and When to Avoid

When to Use

• Use when retiring legacy software applications, deprecated API endpoints, or obsolete databases.
• Use to establish a phased communication timeline and safe customer data migration pathway.
• Use to track technical code deletion and confirm infrastructure resource teardown.

When to Avoid

• Avoid using for active systems undergoing normal routine maintenance.
• Avoid using for initial software project kickoffs (use [[project-charter-and-scope]]).

On-Device AI Integration

Capture system sunset and decommission plans with Oyma on macOS:

Analyze the system sunset planning meeting transcript:
1. Synthesize the legacy system to decommission, replacement architecture, and target shutdown date.
2. Outline customer migration workflows and confirm data safety guarantees.
3. Build the phased communication timeline table tracking milestones from deprecation notice to code removal.
4. Detail the technical teardown checklist, code deletion PRs, binary savings, and post-shutdown verifications.
Output in structured, engineering-grade CommonMark.

Your internal infrastructure decommission plans and technical retirement strategies remain safe on your Mac.