Avoid deferring small or trivial work items
State: open/draft
Summary
Section titled “Summary”-
Self-referencing improvements ship with their migrations: when a new standard, principle, format, or convention is defined, the corpus is brought into compliance in the same parent unit of work.
-
The default is “apply now”. Deferral is the exception and names its target milestone and reason.
-
Trivial migrations (rename, sweep, reformat) are applied immediately; non-trivial ones (large scope, real risk, upstream dependency) may stage to a scoped milestone.
-
Corollary of P-0006-self-hosting-development: self-hosting means the project improves itself first; deferring the application is half-hosting.
Statement
Section titled “Statement”This project is built in an evolutionary, self-referencing way: new or enhanced principles, standards, formats, and refactorings land often as the system improves itself. When we define an improvement to the system, we apply it to the system at the same time. The migration to a new definition is part of the same parent unit of work as the definition, not deferred to a later milestone unless the migration is large or risky enough to warrant its own scoped pass.
Deferral creates a dual state
Section titled “Deferral creates a dual state”The system says X (the new standard, format, or convention) but acts as not-X (the corpus, validators, and tooling still follow the old shape). Readers and automation now live in two simultaneous truths, the most expensive inconsistency to carry.
Migration debt compounds
Section titled “Migration debt compounds”Each milestone that passes with the deferral in place adds more instances of the old shape, more tooling hardened against it, and more cross-references to sweep later. A ten-minute rename today becomes a three-hour audit and sweep next quarter.
Self-referencing improvements are cheap to migrate now
Section titled “Self-referencing improvements are cheap to migrate now”The corpus is the migration target. There is no external user to coordinate with, no production data at risk, no breaking-change schedule. The product-engineering instinct to defer breaking changes to a release cycle does not apply to self-improving substrate work.
How it applies
Section titled “How it applies”When a definition-changing artifact lands, its migration lands with it in the same parent unit of work:
- New Standard: existing in-scope files are brought into compliance in the same PR or task.
- New Decision: downstream artifacts that reference the affected thing (link forms, frontmatter shapes, conventions) are updated immediately.
- Code refactoring: caller sites are updated, not flagged with a “migrate later” comment.
- Frontmatter schema change: existing instances are migrated; the schema does not ship in a state where existing data fails to validate.
- New convention or naming rule: applied to all new and substantially touched documents in the same PR.
The working test before deferring: is the migration large or risky enough to warrant its own scoped milestone? If yes, defer with an explicit target and reason. If no, apply now.
Examples
Section titled “Examples”- Per-type identifier shape (D-0002-entity-identifier-shape): rather than declaring the rule and deferring all migration to M-ML68, the catalogued-entity rename was pulled into M-0001-initial-entity-shape-and-roster so the corpus reflected the rule at once. The task rename followed the same logic, applied to every new or touched task in the same PRs.
- Contradiction-review fix pass: when a review surfaced eight inconsistencies, they were fixed in the next commit, not filed as follow-up tasks for a future milestone.
- Legitimate exception: reshaping the legacy entity tree was deferred to M-ML68 because the new entity shape had to stabilize first. The scope was large and the dependency real, and the deferral named its milestone and its reason.
Implications
Section titled “Implications”- Milestones are slightly larger but complete. A milestone that ships a Standard and the corpus-conforming pass is a unit you can review, accept, and verify against the substrate it describes.
- Less migration debt accumulates. The project does not carry a “to migrate” backlog that grows faster than it shrinks.
- The corpus stays in sync with its own definitions. The project always reflects what it currently believes about itself (P-0006-self-hosting-development).
- Reviewers verify definition and migration in one pass. A migration reviewed weeks later costs the reviewer the context again.
- Deferral needs justification. “Defer to a later milestone” is no longer the path of least resistance.
- Pragmatic boundary (P-0003-pragmatic-architecture): when a migration does not fit (large scope, real risk, blocked by an upstream dependency), staging is acceptable. The deferral documents an explicit milestone target and scope reason.
- API changes that require staging are another boundary: a published contract (CLI surface, importable entry point, on-disk schema a downstream consumer parses) cannot break in lockstep with its callers. Stage the migration across a deprecation window even when the change is small. Document the window, the cut-over milestone, and the bridge shim where one is needed.
- Trivial versus non-trivial:
- Trivial: rename a slug, update inbound wikilinks, reformat frontmatter, add a placeholder section. Tooling does most of it and one commit suffices. Apply now.
- Non-trivial: reshape a legacy entity tree, change a semantic boundary downstream consumers depend on, touch more than about fifty files with non-mechanical edits. Deferral may be right; scope it as its own milestone.
- This principle does not say “ship every improvement immediately even when half-baked”. It says: once you have decided to ship the improvement, ship its migration too, in the same parent unit of work.