Skip to content

Capability-Promotion Review

Periodic review — instantiates Layer-Appropriate Capability Placement

A recurring review that spots the same capability being rebuilt locally across teams and decides whether it should be promoted into a supported host or shared layer — turning repeated duplication into an owned, escalated decision.

A Capability-Promotion Review is a recurring forum whose single question is: which capabilities are being reinvented locally often enough that they should be promoted into a supported host or shared layer? Its defining move is treating repeated duplication as a signal, not a nuisance — when three teams have each built their own rate limiter, that is evidence the capability is placed at the wrong layer, and the honest response is to change ownership rather than let a fourth team build a fourth copy. It is deliberately periodic and cross-cutting: no single team can see that everyone is solving the same problem, so promotion has to be decided from a vantage point above them, on a cadence, by someone with the authority to move a capability's ownership.

Example

A platform architecture group meets quarterly. This quarter, a shadow-platform audit and a scan of recent local builds surface a pattern: four separate services have each hand-rolled their own request rate limiter — subtly differently, each with its own bugs, none observable from a central place. The review reads this as a promotion trigger: rate limiting has crossed the threshold from "reasonable local convenience" to "capability the host should own." They weigh it against the placement criterion — is rate limiting genuinely a cross-cutting concern with stable semantics? (yes) — and decide to promote it: the host platform will provide a supported rate-limiting service, with an owner, an SLA, and a catalog entry, and the four local copies are slated for retirement behind compatibility shims.

Crucially, the review doesn't just bless the new host service; it records the decision, assigns the ownership, and schedules the next look to confirm the local copies actually get retired. The duplication that had been quietly multiplying is now an owned, escalated decision with a name attached — and the next team that needs rate limiting will find a supported host capability instead of a blank editor.

How it works

What distinguishes this review from a generic architecture meeting is that it is organized entirely around the promote/don't-promote decision:

  • Runs on a cadence. It recurs (quarterly, per release train) so duplication is caught while it is three copies, not thirty — the periodicity is the mechanism, not an afterthought.
  • Consumes duplication evidence. It takes in signals — shadow-platform audits, repeated local builds, extension requests — and reads them as the trigger to consider promotion.
  • Decides against a criterion. Each candidate is judged on whether it is genuinely cross-cutting with stable enough semantics to belong to the host, not merely common.
  • Assigns ownership and a retirement plan. A promotion isn't real until someone owns the new host capability and the displaced local copies have a path off — so the decision names both.

Tuning parameters

  • Cadence — how often the review runs. Frequent reviews catch duplication early but cost standing attention and can promote prematurely; infrequent ones let shadow platforms entrench before anyone looks.
  • Promotion threshold — how many independent local builds (or how much pain) trigger promotion. A low bar consolidates aggressively but risks hosting things that should have stayed local; a high bar avoids premature platform-building but lets duplication fester.
  • Authority of the forum — advisory recommendation versus binding ownership decisions. Real authority makes promotions stick but centralizes power; advisory-only reviews see the problem but can't move ownership, so nothing changes.
  • Reversibility — whether promotions are trials with a demotion path or one-way commitments. Trial promotions keep the host from accreting unremovable features; irreversible ones are simpler but let the platform bloat.

When it helps, and when it misleads

Its strength is that it fixes mis-placement systemically: it is the only vantage point from which "everyone is rebuilding the same thing" is even visible, and it converts that scattered waste into a single owned capability at the right layer. By recurring, it also stops the slow accretion of shadow platforms before they harden into things too entangled to retire.

Its failure modes cut both ways. Promote too eagerly and the host becomes a dumping ground — every locally-common utility hauled into the platform, which bloats into the very over-stuffed layer the archetype warns against, now with a central team as the bottleneck. Promote too timidly and duplication metastasizes unchecked. The subtler misuse is the review that decides but never confirms retirement, so a capability gets promoted, the host version ships, and the old local copies live on forever — promotion on paper, duplication in fact.[1] The discipline that keeps it honest is to promote against a real cross-cutting criterion rather than mere popularity, to make ownership and a retirement plan part of the decision, and to check at the next review that the displaced copies actually died.

How it implements the components

This review realizes the governance-and-escalation slice of the archetype — it is where a capability's ownership is deliberately moved to the right layer:

  • capability_promotion_trigger — it defines and evaluates the condition under which repeated local duplication should escalate into a host capability, turning a vague "lots of teams do this" into a fired decision.
  • architecture_review_cadence — it is the recurring forum: the periodic, cross-cutting vantage point without which duplication is never seen whole.

It decides ownership changes but does not publish the resulting directory — that is Capability Catalog — nor record the rationale of any single choice, which is Architecture Decision Record. The retirement it orders is carried out by Compatibility Bridge or Shim, and the duplication evidence it reads is gathered by Shadow-Platform Audit.

Notes

A promotion decision only becomes real through other mechanisms, which is why this review sits at the center of a small chain: Shadow-Platform Audit feeds it the evidence, the Capability Catalog publishes what it promotes, Architecture Decision Record records why, and Compatibility Bridge or Shim retires what it displaces. The review is the decision; those are the follow-through.

References

[1] The promote/keep-local judgment is a form of subsidiarity — the principle that a function should sit at the lowest layer that can handle it well, and rise only when that layer demonstrably cannot. Read that way, promotion is not centralization for its own sake but escalation on evidence, which is exactly why premature or unconfirmed promotion is a misuse of the mechanism. ↩