source-command-promote-experiment

Files (1)

• SKILL.md

SKILL.md (first lines)

# source-command-promote-experiment

Use this skill when the user asks to run the migrated source command `promote-experiment`.

## Command Template

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->

# /build-loop:promote-experiment <name>

Promote a proven experimental artifact into the build-loop plugin itself. This is the manual, user-approved counterpart to Phase 6 Learn's auto-promote — which stays local to the project. Cross-project promotion modifies the plugin repo and affects every user, so it is never automatic.

**Promotion is the choke point where a machine-drafted artifact becomes both tracked and loadable.** `.build-loop/skills/experimental/**` is gitignored and `.build-loop/skills/active/**` is not (`scripts/experimental_ignore.py`), so the move out of `experimental/` is the moment the artifact first appears in `git status`. The plugin-repo copy then makes it loadable in every project. Both effects are decided here, by this skill, and both must be stated to the user before the copy happens.

## Prerequisites

1. The artifact must exist at `.build-loop/skills/active/<name>/SKILL.md` (already auto-promoted within the project), OR at `.build-loop/skills/experimental/<name>/SKILL.md` (user is fast-tracking without waiting for A/B completion — require explicit confirmation).

2. The build-loop plugin repo must be writable. Check:
   ```bash
   BUILD_LOOP_REPO="${CLAUDE_PLUGIN_ROOT:?set CLAUDE_PLUGIN_ROOT or BUILD_LOOP_REPO to your build-loop install}"
   [ -d "$BUILD_LOOP_REPO/.git" ] && [ -w "$BUILD_LOOP_REPO/skills" ]
   ```
   If false, abort with "build-loop plugin repo not writable at $BUILD_LOOP_REPO".

3. The user must supply `<name>` as an argument. If missing, list current candidates:
   ```bash
   ls .build-loop/skills/active/ 2>/dev/null
   ls .build-loop/skills/experimental/ 2>/dev/null
   ```

## Steps

### 1. Read the evidence

Collect:
- The artifact's SKILL.md content
- Its experiments jsonl (`.build-loop/experiments/<name>.jsonl`)
- All `applied` entries across this project (and, if a global index exists at `~/.build-loop/experiments/<name>.jsonl`, append those too)
- Any `auto_promote` or `extend_sample` decisions from `.build-loop/experiments/decisions.jsonl`

Compute:
- Total applied runs (across projects)
- Aggregate win rate vs baseline
- Any regression signals (reversed auto-promotes, discard attempts)

### 2. Synthesize a promotion dossier

Build a markdown summary for the user:

```markdown
## Promotion dossier: <name>

**Type**: skill | agent
**Auto-promoted in this project**: <date>, after N runs
**Cross-project evidence**: P projects, Q applied runs, R wins, S regressions
**Aggregate metric delta**: +X% vs baseline (target was +Y%)
**SKILL.md length**: N lines
**Dependencies declared**: (none | list)
**Last modified**: <date>

**What the skill does** (from description frontmatter):
<one line>

**Recommended promotion target**:
- Name on promote: build-loop:<name>  (or rename to: build-loop:<suggested-name>)
- Target path: skills/<name>/SKILL.md in the plugin repo
- Triggers on: <extracted trigger phrases>
```

### 3. Ask the user

First read the artifact's `user-invocable:` field (and `public-justification:` if `true`), then put this block in the question body — verbatim, above the options. It is the canonical exposure block from `skills/self-improve/SKILL.md` §"Promotion exposure statement":

```
Exposure after promotion
  Destination:      <BUILD_LOOP_REPO>/skills/<final-name>/SKILL.md
  user-invocable:   <false | true>
  Directly invocable by you:
      <no — reached only through /build-loop:run routing>
      <YES, as /build-loop:<final-name> — because <the file's public-justification: line>>
  Loaded in:        every session, every project, once the PR merges and the plugin updates
  Git:              the artifact leaves the gitignored
                    `.build-loop/skills/experimental/**` tier and becomes a
                    tracked file in the plugin repo on branch
                    feat/promote-<name>-from-<project-slug>
```

Answer "YES, directly invocable" only when the file carries a `public-justification:` — the stamper in step 4 refuses the promotion otherwise. Default for a promoted build-loop skill is `user-invocable: false`: `/build-loop:run` is the only human-facing command, and every other capability is reached by intent.

Then use `AskUserQuestion`:

```
Question: "Promote '<name>' into the build-loop plugin repo?"
Header: "Promote"
Options:
  - "Promote as drafted" — copy SKILL.md verbatim, open PR
  - "Promote with rename" — user provides new name, then copy + PR
  - "Review first" — output the dossier but do not copy (user decides after reading)
  - Cancel (implicit via AskUserQuestion "Other")
```

### 4. Execute

If user approved promotion:

1. Determine target path: `$BUILD_LOOP_REPO/skills/<final-name>/SKILL.md` (plus any references/ subdirectory from source).
2. If target already exists:
   - Abort and ask user to choose a new name, OR confirm overwrite.
3. Create a feature branch on the plugin repo: `feat/promote-<name>-from-<project-slug>`.
4. Copy files. Edit frontmatter: remove `experimental: true`, `promoted_at`, `promoted_from_project`; add `promoted_at: <ISO>`, `promoted_from_project: <project-name>`, `original_baseline: <N>`, `aggregate_delta: <percent>`.
5. **Stamp the destination** — the copy is now a plugin-repo skill, and the harness computes `userInvocable ?? true`:
   ```bash
   python3 "$BUILD_LOOP_REPO/scripts/stamp_skill_frontmatter.py" --apply "$BUILD_LOOP_REPO/skills/<final-name>/SKILL.md"
   ```
   `compliant` or `stamped` → continue. `violation` (`user-invocable: true` with no `public-justification:`) or `malformed` → **abort the promotion**, delete the copied files, delete the feature branch, and report the stamper's reason. Do not commit a skill whose surface the stamper refused; the exposure you told the user in step 3 would be wrong.
6. Update the plugin's `skills/build-loop/SKILL.md` capability routing table to reference the new skill if it fits an existing row, OR add a new row (ask the user which).
7. Commit:
   ```

From tyroneross/build-loop, Apache-2.0.

More from tyroneross/build-loop