Wave-Independent Shipping with Upgrade-Aware Boundary Features¶
Problem¶
A spec contains multiple user stories. Strategic review or product judgment wants to defer the later story (often a "detail" or "drill-down" view) — but the earlier story has rendered an anchor that expects the later story to exist (e.g., a footer link to the detail page, a button that opens the secondary view).
If you ship Wave 1 with a dangling link to a not-yet-built target, the surface is half-broken. If you defer Wave 1 to ship together with Wave 2, you delay validated user value over speculative n=1 design.
Solution: design the boundary feature in two compatible states¶
The feature at the wave boundary must be valid in both states — Wave 1 alone, and Wave 1 + Wave 2. Wave 2 upgrades the same surface in-place; it does not replace it.
Concretely:
- Wave 1 ships a neutral, self-contained version of the boundary feature. It runs, reads, and tests without Wave 2 existing.
- Wave 2 ships an upgrade path that enhances the same surface when its prerequisite (e.g., a generated file, a new skill) is present. When absent, the upgrade gracefully falls back to the Wave 1 behavior.
- Tests gate on the Wave 1 contract first, then add Wave 2 tests for the upgrade path. The Wave 1 tests do not need to be rewritten when Wave 2 lands.
Concrete example — SPEC-122 dashboard footer¶
SPEC-122 had three user stories:
- US-1 PM priority override
- US-2 Bugs section in Domain-Dashboard
- US-3 Detail skill /vt-c-pm-bugs (separate file with full bug bodies)
Product-challenge-reviewer flagged US-3 as speculative (n=1 bug = thin evidence base). During /vt-c-3-build, the team wanted to ship US-1 + US-2 for the next PM-Weekly without waiting on US-3 — but the US-2 dashboard's Bugs section had a footer that was designed to link to the US-3 detail file.
The wave boundary lives at that footer line. Two-state design:
| State | Wave 1 (T6) renders | Wave 2 (T14) renders |
|---|---|---|
| Detail file exists | (N/A — Wave 1 has no detail file) | Markdown link to Bugs-{Domain}-{date}.md |
| Detail file missing | Neutral hint: "Run /vt-c-pm-bugs {Domain} for details" |
Same neutral hint (graceful fallback) |
Wave 1 ships with the neutral hint always rendered. The string is self-contained, tells the PM exactly what to do, and assumes nothing about Wave 2 existing. Wave 2 adds a file-existence check and upgrades the line to a real link when possible — without breaking the Wave 1 contract.
Captured in SPEC-122 tasks.md line 8:
"Wave 1 is independently shippable. T6 renders a neutral run-command hint as the footer; T14 (Wave 2) upgrades it to a markdown link when the bug-detail file exists. If Wave 2 ships later or never, T6's footer remains valid and self-contained."
After Wave 1 shipped at core-standards 3.39.0, Wave 2 was deferred to SPEC-142 (P2). The dashboard is fully usable today; the upgrade can wait for PM feedback.
When to use this pattern¶
- Multi-story spec where shipping Wave 1 standalone is valuable, but Wave 2 expects a hook in Wave 1's output.
- A strategic reviewer's "defer" recommendation conflicts with a UX continuity concern.
- Wave 2 is speculative (n=1 evidence) but the framework Wave 1 builds is concretely needed now.
When NOT to use this pattern¶
- Wave 1 has no meaningful standalone value (then defer the whole spec or rethink scope).
- The boundary feature cannot be expressed in a graceful-fallback form without making Wave 1 awkward.
- The two waves are deeply coupled in data (same migration, same schema change) — split the spec by user story instead, not by wave.
Test discipline¶
- Wave 1 tests assert the neutral/standalone behavior of the boundary feature. They must not assume Wave 2 artifacts exist.
- Wave 2 tests add the upgrade-path assertions: when the prerequisite is present, the surface renders the enhanced form; when absent, it falls back to Wave 1 behavior.
- A regression test in Wave 2 explicitly verifies the Wave 1 fallback path still works after the upgrade lands. This is the contract that protects future maintenance.
Decision heuristic¶
For every wave-split proposal, ask:
"If Wave 2 never ships, does Wave 1 still read as a complete user surface?"
If no, the wave boundary is wrong — redesign the boundary feature in the standalone state before splitting.
Anti-pattern¶
Splitting at a boundary where Wave 1's output contains "Coming soon: …" placeholders, dead links, or instructions to "wait for the next release." That isn't an independent wave — that's a half-shipped feature. The user-facing surface must read as deliberate, not deferred.
Related patterns¶
- Heuristic Calibration Gate — pairs with this pattern: each wave has its own calibration gate (SPEC-122 had T12 for Wave 1, T15 reserved for Wave 2).
- Three-Pass Spec Validation — strategic-review pass is the most likely source of "defer Wave 2" recommendations that surface this pattern.
- Dogfooding Meta-Acceptance — when Wave 1 changes the printed output of a workflow command, the command's own next run is a self-verifying acceptance test for the wave-boundary feature.