Avoid deferring small or trivial work items
Status: open/draft
Summary
Section titled “Summary”- Self-referencing improvements ship with their migrations: when we define a new standard / principle / format / convention, the corpus is brought into compliance in the same parent unit of work.
- The default is “apply now”; deferral is the exception that requires explicit milestone targeting and scope rationale.
- 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 P0006 — 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 fashion: new or enhanced principles, standards, formats, and code refactorings land frequently as the system improves on itself. When we define an improvement to the system, we apply that improvement 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 itself — not deferred to a future milestone unless the migration is genuinely 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, the new format, the new convention) but acts as not-X (the corpus, the validators, the tooling all still follow the old shape). Readers and automation are now in two simultaneous truths, which is the most expensive kind of inconsistency to live with.
Migration debt compounds
Section titled “Migration debt compounds”Each milestone that passes with the deferral in place accumulates more instances of the old shape, more tooling hardened against it, more cross-references that have to be swept later. What was a 10-minute rename today becomes a 3-hour audit + sweep next quarter.
Self-referencing improvements have low immediate-migration cost
Section titled “Self-referencing improvements have low immediate-migration cost”The corpus IS the migration target. There’s no external user to coordinate with, no production-data risk, no breaking-change schedule. The “defer to later” instinct from product-engineering (where breaking changes need release cycles) doesn’t translate to self-improving-substrate work; the cost of immediate migration here is unusually low.
The path of least immediate effort accumulates interest
Section titled “The path of least immediate effort accumulates interest”Saying “defer to MML68” feels like saving work; in practice it shifts the work + adds rebase / merge / re-context costs on top. Default to “do it now”; reach for deferral only when the migration size or risk genuinely justifies a separate pass.
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 brought into compliance in the same PR or task that ships the Standard.
- New Decision → downstream artifacts that reference the affected thing updated immediately (link forms, frontmatter shapes, conventions).
- Code refactoring → caller sites updated, not flagged
# TODO migrate after the refactor lands. - Frontmatter schema change → existing instances migrated; the schema doesn’t 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 genuinely large or risky enough to warrant its own scoped milestone? If yes, defer with explicit target and rationale. If no, apply now.
Examples
Section titled “Examples”- Per-type identifier shape (D-0002-entity-identifier-shape): rather than just declaring the per-type rule and deferring all migration to MML68, T-0002 (the catalogued-entity rename) was pulled into M0001 so the corpus immediately reflects the new rule. The Tasks rename followed the same logic — applied to every new/touched task in the same PRs.
- Markdown standard (T-0006 → T-0008): Task 3 explicitly includes the one-time corpus reformat pass as AC-5/AC-6, not deferred to a “format-cleanup” milestone.
- Decision Summary section requirement: when the Summary-at-top
convention was added to the Decision entity, the three existing
ADRs (
D0001,D0002,D0003) gained placeholders in the same commit. No “Summary will be added later” deferral. - Contradiction-review fix pass ([commit
49ec9ba]): when the contradiction-review subagent surfaced 8 inconsistencies, they were fixed in the next commit, not filed as follow-up tasks for a future milestone. - Legitimate exception — the legacy
plugin/entities/→plugin/lib/model/entities/migration is appropriately deferred to MML68 because the new entity shape needs to stabilize under M0001 before the legacy tree is reshaped against it. The scope is large and the dependency is real; the deferral is documented with explicit milestone targeting.
Implications
Section titled “Implications”- Milestones are slightly larger but coherently complete. A milestone that ships a new Standard and the corpus-conforming pass is a unit you can review, accept, and verify against the substrate it describes.
- Less migration TODO accumulates. The project doesn’t end up with a perpetual “to migrate” backlog that grows faster than it shrinks.
- The corpus stays in sync with its own definitions. Self-hosting (P-0006-self-hosting-development) is teeth-bearing: the project always reflects what it currently believes about itself.
- Reviewers can verify “definition + migration” in one pass. When the migration is in a separate PR weeks later, the reviewer re-acquires context to verify; the verification cost compounds.
- Default behavior shifts. “Defer to a later milestone” stops being the path of least resistance; it becomes the path requiring justification.
- Pragmatic boundary (P-0003-pragmatic-architecture): when migration genuinely doesn’t fit — large scope, real risk, blocked by an upstream dependency — staging is acceptable. The deferral document explicit milestone target + scope rationale. The exceptions are rare; the default is “apply now.”
- API changes that require staging are another boundary case: a published API contract (CLI surface, importable Python entry point, on-disk schema downstream consumers parse) cannot break in lockstep with its callers. Staging the migration across a deprecation window is the right call even though the underlying change is small. Document the deprecation window, the cut-over milestone, and the bridge shim where one is needed.
- Distinguishing trivial from non-trivial migration:
- Trivial: rename a slug; update inbound wikilinks; reformat file frontmatter; add a placeholder section. Tooling can do most of it; one commit suffices. → Apply now.
- Non-trivial: re-shape a legacy entity tree; change a
semantic boundary that downstream consumers depend on; touch
~50 files with non-mechanical edits. → Deferral may be the right call; scope it as its own milestone.
- This principle does NOT say “ship every improvement immediately even when half-baked.” It says: if you’ve decided to ship the improvement, ship its migration too, in the same parent unit of work.
- Corollary of P-0006-self-hosting-development: self-hosting means the project’s improvements apply to itself first; deferring the application is half-hosting.