Skip to content

Add a deprecation and migration procedure to the built-in method #3798

Closed

Description

@malibio

Overview

The built-in method has a procedure for splitting a wide refactor (expand, migrate, contract) but none for retiring code, an API or a data shape in a codebase that has users. The method ships to people working on their own projects, where deprecation and migration are ordinary work. Addy Osmani's deprecation-and-migration (MIT) covers it.

Problem Statement

  • NodeSpace's own repository is pre-release, so its rule is "delete and reset" and it carries no migration logic. That is a standard of this project that ends at release; it is not the general method, and a user's project usually has to keep what it ships working.
  • Splitting a Plan into Tasks gives the expand, migrate, contract shape for a refactor but not the decisions around it: whether to deprecate at all, how long old and new run side by side, how callers are found and moved, how a removal is rolled back, and how zombie code is recognised.

Proposed Solution

A Deprecating and Migrating procedure that:

  • starts by asking whether the thing has users (a decision recorded with Recording a Decision, using Asking the User for what only the user knows), because the answer decides everything after it;
  • states the usage that must be found before anything is removed, and the evidence that it is gone;
  • sequences the work as expand, migrate, contract, handing the slices to Splitting a Plan into Tasks;
  • states what rollback means for each step and who is told;
  • names the final removal as its own, evidenced task.

It states that a project with no users, or one that has declared itself pre-release, may skip the parallel-running steps, and says the project's standards decide.

Documentation

  • ADR-092 planning and delivery procedure tables - add a row with the source, licence, copyright and what changed
  • ADR-094 "The shipped workflow" - standards are skills attached to a project; the pre-release exception belongs there
  • seeded-nodes.md "Procedure skills" - the count and list change
  • Updates: the ADR-092 table and the seeded-nodes.md procedure list

Architecture Impact

Extends ADR-092's procedures; no new type, field or relationship. Companion nodespace-docs edit required; no new ADR. The post-release upgrade method for NodeSpace's own data is a separate decision (the "no migration ladder" stance in the SQL schema bootstrap ends at release) and is not made here.

Acceptance Criteria

  • A seeded Deprecating and Migrating skill exists with a description that says when it applies
  • It requires the "does this have users?" decision to be recorded before any removal is planned
  • It names how usage is found and what evidence shows it is gone
  • It sequences expand, migrate, contract and defers slicing to Splitting a Plan into Tasks, without restating it
  • It states rollback for each step
  • It says a pre-release project may skip the parallel-running steps when its standards say so, and does not name this repository
  • The attribution line carries the source, licence and copyright
  • Skill-retrieval confusion matrix includes it and shows no regression
  • ADR-092 and seeded-nodes.md are updated in the same change
  • Code passes bun run quality:fix

Technical Specifications

Reference Files

  • packages/agent/src/seeds/skills/splitting-into-issues.md - the "wide refactor is the exception" paragraph this builds on
  • packages/agent/src/seeds/skills/recording-a-decision.md, asking-the-user.md
  • packages/agent/src/skill_pipeline.rs - add a seed row with its links

Implementation Details

Related Issues

Non-Goals

  • NodeSpace's own post-release data upgrade method
  • Changing this repository's no-backward-compatibility rule

Activity

  1. added a commit that references this issue on Oct 14, 2026
    9711839
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions