Repository navigation
Description
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 onpackages/agent/src/seeds/skills/recording-a-decision.md,asking-the-user.mdpackages/agent/src/skill_pipeline.rs- add a seed row with its links
Implementation Details
- Read Osmani's skill file before adapting; this issue was written from the repository summary.
- Do not put this repository's pre-release rule in the skill. It belongs in the project's standards (Move this project's standards and process into skills attached to the project #3730) with its expiry stated.
Related Issues
- Move this project's standards and process into skills attached to the project #3730 (this repository's standards: record the no-backward-compatibility rule as a standard that ends at release)
- Add a shared rationalizations, red flags and verification block to the delivery procedures #3796 (shared verification block)
Non-Goals
- NodeSpace's own post-release data upgrade method
- Changing this repository's no-backward-compatibility rule
Activity
Add procedures for diagnosing, prototyping, researching, deprecating,…