Distribution as a Completion Precondition for Discoverability Features¶

Problem¶

A discoverability or onboarding feature — a new entry-point skill, a getting-started doc, a persona landing page — exists to change human behavior: people should find and use something they previously couldn't. When the code ships and the tests are green, the feature looks done. It is not.

SPEC-149 added /vt-c-dev-start to solve a confirmed adoption gap (123+ skills exceed human memorability; the only entry point was workflow-oriented, not persona-oriented). But a discovery skill that nobody is told about is untested, not disproven (R7). If the US-3 adoption metric (measured 2026-08-01) is read before the audience has been told the skill exists, a flat number means "we never ran the experiment" — not "the feature failed." Shipping without distribution silently converts a real experiment into an uninterpretable one.

Solution: model distribution as an explicit, owner-assigned workflow step¶

Make "announce/demo to the target audience" a first-class Definition-of-Done step with a named owner and a status — not an afterthought bolted on after merge.

Concretely, in SPEC-149's state.yaml:

steps:
  A: completed      # US-1 the skill itself
  B: completed      # US-2 the docs
  C: owner_pending  # distribution — Rolf to announce/demo to Dominik, Markus, Niclas
distribution:
  status: owner_pending
  action: "Announce/demo /vt-c-dev-start + docs/getting-started/by-role.md to the Dev audience"
  why: "Discovery skill nobody is told about is untested, not disproven (R7). Precondition for interpreting the US-3 adoption metric (2026-08-01)."

The distribution step gates interpretation of the metric, not the merge. The code (US-1, US-2) ships when its gates pass; the spec records that the human step is outstanding and owned, so the metric is never read out of context.

Why this is separate from "the feature works"¶

Traditional DoD asks "does the code do what the spec says?" For a discoverability feature that is necessary but not sufficient — the spec's actual claim is "people will find and use this." That claim can only be exercised after a human tells the audience. Treating the announcement as implicit is the same class of error as declaring a migration "done" before verifying the backfill actually ran.

Decision heuristic¶

For any feature whose success is defined by a change in human behavior, ask:

"Between merge and the metric's measurement date, is there a human action (announce, demo, train) without which the metric is uninterpretable?"

If yes, that action is a DoD step with an owner and a status — and the metric must not be read until it is completed.

Anti-pattern¶

Marking the spec fully completed at merge, letting the announcement happen "whenever," then reading the adoption metric on the scheduled date and concluding the feature failed. The experiment was never run.
Leaving distribution as a vague note in the PR description rather than an owned, status-tracked step — so no one is accountable and it silently never happens.

Interaction with spec completion¶

Distribution being owner_pending does not block /vt-c-complete: US-1/US-2 are done and all quality gates pass, so the spec is marked completed while the distribution step remains tracked (with its owner and rationale) toward the metric date. Completion closes the engineering loop; the tracked step keeps the adoption loop honest.

Re-Validate Deferral Criterion — the US-3 metric is a deferred evaluation; this pattern ensures the deferral's precondition (audience was told) is met before the criterion is judged.
Wave-Independent Shipping — Wave 1 shipped standalone; this pattern governs the human step that makes Wave 1's premise testable.
Dogfooding Meta-Acceptance — complementary: the skill verifies itself on next run, but self-verification of the code is not verification of adoption.