Skip to content

Dependency-Gated Helper Documentation

Problem

A discoverability guide exists to point people at the right helper (agent or skill) at the right moment. Some helpers carry a hard dependency — an external system without which the helper cannot run at all. When the guide's recommendation is written more broadly than the helper's runnable conditions, the guide contradicts itself: it tells the reader to reach for a tool in a situation where that tool will fail its own first step.

SPEC-134 documented and chained the ~6 un-chained helpers between /vt-c-pd-3-prototype and /vt-c-pd-4-validate. One of them, design-implementation-reviewer, is Figma-MCP-hard-dependent (its agent description and Workflow Step 2 both require a Figma source). The first draft broadened its documented trigger to "any design reference" in four places, and the worked example dispatched it against a prototype the preceding step had explicitly established has no Figma source. A reader following that example would invoke an agent guaranteed to fail its own Step 2 — an internal self-contradiction (Pass-1 review, HIGH / DOC-1).

The failure is quiet because per-item trigger text reads fine in isolation. "Use the design-implementation-reviewer after prototype creation" is only wrong in combination with the scenario the guide itself set up two steps earlier.

Solution: narrow every trigger to its dependency precondition, in every spot

  1. Enumerate each helper's hard dependencies. For every helper the guide chains, name the external system it cannot run without (Figma MCP, a live server, a specific file the prior step may or may not produce).

  2. Gate the documented trigger on that precondition — everywhere. The trigger text is usually duplicated across surfaces (the loop diagram, the per-helper detail block, the orchestrator's Sub-Agents table, the owning SKILL). Narrow all of them together, or they drift:

design-implementation-reviewer — dispatch only when a Figma source exists.

In SPEC-134 the fix landed in five spots; the fifth (the orchestrator Sub-Agents table row) still carried the old "After prototype creation" wording after the first four were corrected — proof that "fix the obvious ones" leaves a live contradiction behind.

  1. Make the worked example a documented skip when the precondition is absent. The end-to-end walkthrough is the tripwire. Rather than delete the step, model the skip the same way an adjacent optional step is skipped:

Step 6 — skipped in this scenario: no Figma source exists (see Step 5), so design-implementation-reviewer does not apply here.

This teaches the conditional instead of hiding it, and keeps the example internally consistent.

Why the worked example is the load-bearing check

Per-item trigger text is reviewed one line at a time, so a too-broad trigger passes. The contradiction only becomes visible when you trace a concrete run through the whole guide and reach a helper whose precondition the earlier steps already denied. An end-to-end worked example is therefore not decoration — it is the internal consistency test for the recommendations. If the guide ships a worked example, run it mentally (or in review) as an assertion: every helper it dispatches must have its hard dependency satisfied by that point in the example.

Decision heuristic

When documenting any conditional or dependency-gated helper, ask:

"Is there a scenario the guide itself describes in which this helper is recommended but its hard dependency is absent?"

If yes, the trigger is too broad. Narrow it to the precondition in every surface, and make the worked example skip the helper (with a stated reason) wherever the precondition does not hold.

Anti-pattern

  • Broadening a helper's trigger to the most inclusive phrasing ("any design reference", "after prototype creation") because it reads well in a table, without checking the helper can actually run under that phrasing.
  • Fixing the trigger in the diagram and detail block but leaving the orchestrator table or SKILL copy untouched — a duplicated claim is only as accurate as its stalest copy.
  • Treating the worked example as narrative flavor rather than an executable consistency check.

Relationship to sibling patterns

This is the accuracy companion to distribution-as-completion-precondition (SPEC-149): both belong to the discoverability family, but that pattern governs whether a discoverability feature is finished (humans told), while this one governs whether its recommendations are correct (helpers only recommended where they can run). Related to count-reconciliation-single-source in spirit — a claim duplicated across surfaces is only as trustworthy as its least-updated instance.

Source: SPEC-134 (PD-Prototype Refinement-Loop), Pass-1 review finding DOC-1 (HIGH).