docs(compound-engineering): capture review promotion contract

Author: tmchow

docs/solutions/skill-design/beta-skills-framework.md

@@ -13,6 +13,7 @@ severity: medium
 description: "Pattern for trialing new skill versions alongside stable ones using a -beta suffix. Covers naming, plan file naming, internal references, and promotion path."
 related:
   - docs/solutions/skill-design/compound-refresh-skill-improvements.md
+  - docs/solutions/skill-design/review-skill-promotion-orchestration-contract.md
 ---
 
 ## Problem
@@ -79,6 +80,8 @@ When the beta version is validated:
 8. Verify `lfg`/`slfg` work with the promoted skill
 9. Verify `ce:work` consumes plans from the promoted skill
 
+If the beta skill changed its invocation contract, promotion must also update all orchestration callers in the same PR instead of relying on the stable default behavior. See [review-skill-promotion-orchestration-contract.md](./review-skill-promotion-orchestration-contract.md) for the concrete review-skill example.
+
 ## Validation
 
 After creating a beta skill, search its SKILL.md for references to the stable skill name it replaces. Any occurrence of the stable name without `-beta` is a missed rename — it would cause output collisions or route to the wrong skill.

docs/solutions/skill-design/review-skill-promotion-orchestration-contract.md

@@ -0,0 +1,80 @@
+---
+title: "Promoting review-beta to stable must update orchestration callers in the same change"
+category: skill-design
+date: 2026-03-23
+module: plugins/compound-engineering/skills
+component: SKILL.md
+tags:
+  - skill-design
+  - beta-testing
+  - rollout-safety
+  - orchestration
+  - review-workflow
+severity: medium
+description: "When ce:review-beta is promoted to stable, update lfg/slfg in the same PR so they pass the correct mode instead of inheriting the interactive default."
+related:
+  - docs/solutions/skill-design/beta-skills-framework.md
+  - docs/plans/2026-03-23-001-feat-ce-review-beta-pipeline-mode-beta-plan.md
+---
+
+## Problem
+
+`ce:review-beta` introduces an explicit mode contract:
+
+- default `interactive`
+- `mode:autonomous`
+- `mode:report-only`
+
+That is correct for direct user invocation, but it creates a promotion hazard. If the beta skill is later promoted over stable `ce:review` without updating its orchestration callers, the surrounding workflows will silently inherit the interactive default.
+
+For the current review workflow family, that would be wrong:
+
+- `lfg` should run review in `mode:autonomous`
+- `slfg` should run review in `mode:report-only` during its parallel review/browser phase
+
+Without those caller changes, promotion would keep the skill name stable while changing its contract, which is exactly the kind of boundary drift that tends to escape manual review.
+
+## Solution
+
+Treat promotion as an orchestration contract change, not a file rename.
+
+When promoting `ce:review-beta` to stable:
+
+1. Replace stable `ce:review` with the promoted content
+2. Update every workflow that invokes `ce:review` in the same PR
+3. Hardcode the intended mode at each callsite instead of relying on the default
+4. Add or update contract tests so the orchestration assumptions are executable
+
+For the review workflow family, the expected caller contract is:
+
+- `lfg` -> `ce:review mode:autonomous`
+- `slfg` parallel phase -> `ce:review mode:report-only`
+- any mutating review step in `slfg` must happen later, sequentially, or in an isolated checkout/worktree
+
+## Why This Lives Here
+
+This is not a good `AGENTS.md` note:
+
+- it is specific to one beta-to-stable promotion
+- it is easy for a temporary repo-global reminder to become stale
+- future planning and review work is more likely to search `docs/solutions/skill-design/` than to rediscover an old ad hoc note in `AGENTS.md`
+
+The durable memory should live with the other skill-design rollout patterns.
+
+## Prevention
+
+- When a beta skill changes invocation semantics, its promotion plan must include caller updates as a first-class implementation unit
+- Promotion PRs should be atomic: promote the skill and update orchestrators in the same branch
+- Add contract coverage for the promoted callsites so future refactors cannot silently drop required mode flags
+- Do not rely on “remembering later” for orchestration mode changes; encode them in docs, plans, and tests
+
+## Lifecycle Note
+
+This note is intentionally tied to the `ce:review-beta` -> `ce:review` promotion window.
+
+Once that promotion is complete and the stable orchestrators/tests already encode the contract:
+
+- update or archive this doc if it no longer adds distinct value
+- do not leave it behind as a stale reminder for a promotion that already happened
+
+If the final stable design differs from the current expectation, revise this doc during the promotion PR so the historical note matches what actually shipped.