@ericrisco/rsc 3.6.0 → 3.7.1

package/skills/sales-funnel/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: sales-funnel
+description: "Use when planning the steps from an offer to purchase or booking: pages, transitions, recovery paths and measurement handoffs. NOT writing one page (that is `landing-copy`), running deals (that is `sales-pipeline`) or implementing payment (that is `stripe`)."
+tags: [sales-funnel, vsl, buyer-journey, conversion, checkout, campaign]
+recommends: [customer-research, offer-design, vsl-script, landing-copy, marketing, analytics, stripe]
+origin: risco
+---
+
+# Sales funnel — connect the buying decisions
+
+Turn an offer into the smallest coherent route a buyer can complete. Deliver a build brief:
+which steps exist, why each exists, how people leave or recover, and what proves a step completed.
+Do not turn a request for one page into a multi-page campaign.
+
+## Establish the campaign record
+
+Read the existing campaign and brand material before asking for missing facts. By default use
+`02-DOCS/wiki/marketing/<campaign>/research.md` and `offer.md`; honor an established location instead.
+Record the offer ID and revision in `funnel.md`, link its source and retain the same evidence IDs.
+Index new campaign artifacts in `02-DOCS/wiki/index.md`. For an explanation-only request, respond
+without saving files. Writing a brief authorizes that brief, not messages, purchases or deployment.
+
+An existing offer can be enough; the user need not run another skill just to satisfy a sequence.
+If offer documents conflict, identify the authoritative revision before treating disputed terms as
+publishable. Continue with the undisputed route and visibly unresolved terms. Price, included work,
+conditions and primary action must agree across all downstream handoffs.
+
+Establish traffic source, buyer readiness, intended action, delivery method and existing pages.
+Ask only for missing facts that change the route. Distinguish observations from assumptions;
+use `customer-research` for missing buyer evidence and `offer-design` for an unsettled offer.
+
+## Choose the fewest useful steps
+
+Each added step needs a buyer reason. Price alone does not decide whether someone needs a call,
+email sequence or checkout. Use the actual buying uncertainty, qualification needs and delivery
+constraints. A free or open-source product can end in a trial, installation or download.
+
+| Buyer needs before acting | Route choice |
+| --- | --- |
+| Understand a demonstrated offer and buy | Sales page or VSL → checkout → confirmation/delivery |
+| Assess suitability with a person | Explanation → necessary qualification → booking → confirmation |
+| Learn before deciding, and wants follow-up | Optional resource/capture → delivery → permissioned follow-up → offer |
+| Already understands the offer | Preserve the existing short route; remove repeated explanations |
+
+Choose one route and explain the trade-off. Add a complementary offer only when it exists and the
+user's scope includes it; declining must lead onward. A VSL does not require hiding the purchase
+action until a timer expires. Give people who cannot watch a readable way to understand the offer.
+
+## Specify transitions, not just page names
+
+For each step write: **entry context; buyer question; information/proof needed; one primary action;
+success condition; next destination; decline/exit; failure/recovery; data collected; implementation owner**.
+Keep the brief about decisions and handoffs. `landing-copy` writes final page text, `vsl-script`
+writes the video, `marketing` writes follow-up, and the existing web stack builds the pages.
+
+Attach each consequential claim to its evidence ID and explain the scope of support. A screenshot
+of a feature proves its visible behavior, not the revenue it will generate. Carry missing evidence
+as a draft gap with an owner; never fill the page with fabricated social proof.
+
+Where money or access changes hands, map **checkout requested → pending → confirmed or failed**
+separately from the pages showing them. A return URL, button click or thank-you view is not payment
+confirmation. Specify the authoritative success signal as an integration requirement and have
+`stripe` or the chosen provider specialist verify it against current documentation.
+
+For pending payments, show status and a way to return or obtain help. For failure/cancellation,
+preserve context and provide a deliberate retry or exit. Refreshes and revisits must not by
+themselves create a new charge or repeat delivery. State the order/booking identity that persists
+across retries, and require deduplication at the operation that fulfills the order. Do not claim a
+hosted provider supports this until checked. Include confirmed-payment/delivery-failure recovery
+when delivery is separate; a buyer should not pay again to retrieve an already-paid purchase.
+
+## Make completion measurable
+
+Give `analytics` an event brief, not speculative tracking code. For each important transition name
+the event, its verified trigger, the entity counted, deduplication key, numerator and denominator.
+Separate visits, checkout attempts, confirmed orders and fulfilled orders. Purchase counts come
+from unique confirmed orders, not refreshes or callback deliveries. Report refund/cancellation
+outcomes separately; do not silently redefine initial conversion.
+
+State the observation window and attribution limits. If the account has no baseline, mark targets
+unmeasured and collect one before promising a rate or choosing a winner. Route experiment design
+to `ab-testing`; a sample of a few purchases does not establish a causal improvement. Collect only
+data required for the journey and ask the relevant privacy/analytics skills about consent wiring.
+
+## Deliver the brief and reconcile it
+
+Deliver the chosen route, per-step decisions, event brief, dependency order and unresolved questions
+with owners. Put payment/delivery uncertainty before cosmetic refinements in the build order.
+Include a continuity check: **offer revision, price, inclusions, conditions, evidence IDs and action**
+must match the page and video assignments. Name each stale artifact and the required correction.
+
+Review the journey as a buyer who succeeds, declines, fails, refreshes and comes back later. A
+complete planning brief can still be marked **implementation unverified**. Publication readiness
+requires observed implementation tests; planning alone proves neither charges nor delivery work.
+
+## Failure patterns
+
+| Pattern | Repair |
+| --- | --- |
+| More screens are assumed to mean more revenue | Remove steps with no distinct buyer question or existing offer. |
+| Email signup and purchase are mixed into one success rate | Define each conversion and its eligible denominator separately. |
+| A polished page hides an undefined handoff | Name the completion signal, receiving owner and failure path. |
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/sales-funnel/evals/README.md

@@ -0,0 +1,28 @@
+# Sales funnel evaluation
+
+Run routing in fresh sessions using only the skill description. Repeat each positive and negative
+prompt three times; require at least 90% correct majority decisions across the cases. Check that
+each negative case's owner exists in the catalog. Structural eval-lint does not measure routing.
+
+For capability, give the complete scenario to independent agents with and without the skill.
+Both arms receive the same source facts and have separate temporary output directories. The
+baseline must not read any skill or this rubric. Randomize output labels and have an independent
+grader score every rubric item with quoted evidence and quality on completeness, actionability,
+correctness and grounding. Use the catalog behavioral scorer; require absolute >= 8.5 and lift >= 1.0.
+Repeat three times for a stable estimate and retain all outputs, scores and failed runs.
+
+These are model/human judgments, not deterministic CI. Record run count and uncertainty. No
+behavioral result is claimed by these case definitions. Re-run after description or method changes.
+No shell checker is provided: planning truth and payment-path adequacy need the supplied scenario
+and semantic review, not a grep for headings.
+
+## Initial evaluation — 2026-10-31
+
+One capability scenario, one fresh execution per arm, independently blind-graded:
+with skill **9.8/10**, without **9.8/10**, difference **+0.0**.
+The catalog scorer requires absolute >=8.5 and improvement >=1.0. This run
+passed absolute quality but did not meet the improvement threshold.
+This is a single-trial result, not the repeated-trial protocol above or evidence of conversion gains.
+Arms used separate contexts and files; the scorer reported transcript integrity **not checked**.
+The owner authorized release 3.7.0 with the pack’s incomplete behavioral evidence documented.
+The thresholds remain unchanged; release authorization is not an evaluation pass.

package/skills/sales-funnel/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: sales-funnel
+
+should_trigger:
+  - prompt: "Plan the pages between my video ad and delivery of my paid workshop."
+    why: "Owns the multi-step purchase journey and its handoffs."
+  - prompt: "Tenemos una VSL y un checkout, pero no sabemos qué mostrar si falla el pago."
+    why: "An incomplete failure path is a journey-design problem."
+  - prompt: "People watch our pitch, then have nowhere clear to go. Map the next steps."
+    why: "A symptom of disconnected steps, without naming a funnel."
+  - prompt: "Decide whether this offer needs email capture before the sales page."
+    why: "Chooses the minimum useful route based on buyer readiness."
+  - prompt: "Make a build brief connecting our landing, booking form and confirmation."
+    why: "Specifies transitions and responsibilities across pages."
+
+should_not_trigger:
+  - prompt: "Rewrite the headline and FAQ of this single landing page."
+    route_to: landing-copy
+    why: "The route already exists; this is page wording."
+  - prompt: "Configure Stripe webhook signature verification."
+    route_to: stripe
+    why: "Payment integration implementation belongs to the provider skill."
+  - prompt: "Set up purchase events in PostHog."
+    route_to: analytics
+    why: "Instrumentation implementation is not journey planning."
+  - prompt: "Write the three emails after our launch announcement."
+    route_to: marketing
+    why: "Campaign copy is downstream of the route."
+
+capability:
+  - scenario: >-
+      Create a concrete funnel brief, not implementation code, for a live online workshop.
+      Offer W1 revision 4 is authoritative: EUR 180 total, one workshop plus recording,
+      access after confirmed payment, refund requests accepted until 48 hours before the event.
+      The existing landing draft uses revision 3 and says EUR 150 and lifetime coaching.
+      Warm subscribers arrive from our newsletter; the approved VSL already presents W1 revision 4.
+      Evidence E1 is a permitted screenshot of the actual workshop agenda; no outcome testimonials exist.
+      Checkout is hosted, can redirect back before payment is confirmed, and customers can refresh or return later.
+      We have no additional product and want the shortest path, with no new email capture.
+      The developer needs page purposes, transitions including failed or pending payment,
+      delivery handoff, required events and how to measure purchases without counting retries twice.
+      There is no conversion baseline. Draft the brief with explicit unresolved integration questions.
+    must_include:
+      - "Uses W1 revision 4 throughout and explicitly removes the EUR 150/lifetime-coaching claims from the landing handoff."
+      - "Keeps a direct route without new capture or an invented upsell, using existing warm audience context."
+      - "Separates checkout return, payment pending, confirmed payment and failed/cancelled payment; pending return does not unlock workshop access."
+      - "Specifies a safe refresh/return or retry path that preserves order identity and avoids triggering delivery or a new charge solely from a page load."
+      - "Links E1 to an agenda/process claim, does not imply it proves buyer outcomes, and states unavailable outcome proof as a gap."
+      - "Defines completed-purchase measurement using a confirmed order identity and an explicit denominator; retries and page refreshes are not additional purchases."
+      - "Assigns payment/delivery integration and instrumentation questions to implementation handoffs without claiming provider capabilities were verified."
+      - "Labels conversion targets as unmeasured and proposes baseline collection rather than an invented expected conversion rate."

package/skills/tidy/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: tidy
+description: "Use when every repository in the workspace must end synced and clean: each one on its default branch, everything pushed, everything pulled, no leftover branches or worktrees. Covers the root repo and every nested repo (child projects). Fires on 'limpia el harness', 'actualiza todo', 'sincroniza todo', 'déjalo todo en main', 'sube y baja todo', 'tidy up the repos', 'sync everything'. NOT upgrading the rsc version (that is `npx @ericrisco/rsc upgrade`), NOT opening isolation for new work (that is `worktrees`), NOT landing one finished branch (that is `ship`)."
+tags: [git, sync, cleanup, branches, worktrees, limpieza, sincronizar, main]
+recommends: [worktrees, ship]
+profiles: [minimal, core, full]
+origin: risco
+---
+
+# tidy — every repo on main, pushed, pulled, nothing left over
+
+One request, every repository in the workspace. When it ends, each repo shows the same picture:
+
+- the main checkout is on the **default branch**, up to date with the remote;
+- **nothing local is missing from the remote** — no unpushed commit, on any branch;
+- **no worktree and no branch whose work has already landed**, locally or on the remote.
+
+The job is cleanup, and cleanup is where work gets lost. So the rule under every step: **delete only
+what is proven to be in the default branch already.** Anything else is pushed, kept and reported —
+never thrown away to make the picture look clean.
+
+## 1. Find the repositories
+
+The workspace root, plus every nested git repository below it (child projects keep their own git):
+
+```bash
+git rev-parse --show-toplevel                          # the root repo, if any
+find . -name .git -maxdepth 4 -not -path '*/node_modules/*' -not -path '*/.worktrees/*'
+```
+
+A `.git` that is a *file* is a linked worktree or a submodule, not a repo of its own: skip it here,
+it is handled from its parent in step 4. Name the list in one line before touching anything.
+
+**Never change the working directory into a child repo.** Use `git -C <repo>` and absolute paths.
+Session hooks take the cwd as the project, and a `cd` plants state inside the child.
+
+## 2. Read everything before changing anything
+
+Per repo, one pass, no writes except the fetch:
+
+```bash
+git -C <repo> fetch --all --prune --quiet
+git -C <repo> symbolic-ref --short refs/remotes/origin/HEAD     # the default branch (origin/main)
+git -C <repo> status --short --branch                           # current branch, ahead/behind, dirty
+git -C <repo> for-each-ref --format='%(refname:short) %(upstream:short) %(upstream:track)' refs/heads
+git -C <repo> worktree list --porcelain
+git -C <repo> stash list
+gh pr list --state open --json number,headRefName 2>/dev/null   # open PRs, when gh is there
+```
+
+No remote at all → the repo cannot be "pushed"; report it and only tidy what is local.
+
+## 3. Classify every item
+
+Each branch, worktree and remote branch lands in exactly one row. Decide by the commands, not by
+reading names.
+
+| Item | Proof | Action |
+| --- | --- | --- |
+| Worktree whose work landed | `npx @ericrisco/rsc worktrees` calls it safe | `npx @ericrisco/rsc worktrees reap` |
+| Worktree whose directory is gone | `prunable` in the porcelain list | `git -C <repo> worktree prune` |
+| Worktree with live or unsaved work | anything the reaper refuses | keep; report the reaper's reason |
+| Local branch merged into the default | `merge-base --is-ancestor <b> origin/<default>` | `git branch -d <b>` |
+| Local branch squash-merged | its content is in the default (below) | `git branch -D <b>`, tip SHA in the report |
+| Local branch with unlanded commits | neither of the two above | push it (`git push -u origin <b>`), keep it |
+| Remote branch whose content landed | same content check, against `origin/<b>` | delete it, after one confirmation (step 6) |
+| Remote branch with an open PR | `gh pr list` | keep; it is live |
+| Remote branch unlanded, no PR | not in the default, no PR | keep; report it as an open question |
+| Stash | any | keep; report it. Never `stash drop` without a yes |
+
+**The content check** (what makes a squash merge count as landed): merge the branch into the default
+in memory and see whether anything changes.
+
+```bash
+git -C <repo> merge-tree --write-tree origin/<default> <branch> | head -1   # resulting tree
+git -C <repo> rev-parse origin/<default>^{tree}                             # default's tree
+```
+
+Same tree → the branch adds nothing; it has landed. A conflict, a different tree, or a git older
+than 2.38 (no `--write-tree`) → **not proven**, so it is kept. A branch that never carried a commit
+of its own is a live workspace someone just opened, not leftovers: keep it.
+
+Never delete the default branch, the current branch of another checkout, or `rsc/knowledge`.
+
+## 4. Act, in this order
+
+1. **Uncommitted changes stop that repo.** Show the files and ask once: commit them, stash them, or
+   leave the repo as is. Never commit or discard someone's work in progress on your own. Another
+   session working in that checkout (the isolation notice says so) → do not touch its branch or its
+   files at all; report it.
+2. **Push what is only local.** Every branch with unlanded commits goes to the remote. The default
+   branch ahead of `origin`: push it if the default branch is open here; if it is protected
+   (branches and PRs), move those commits to a branch and open a PR — ask first.
+3. **Retire what landed.** `npx @ericrisco/rsc worktrees reap` for worktrees (it refuses anything
+   that would lose a file, and its refusal stands), `worktree prune`, then the branches from step 3.
+   Without rsc in that repo, follow the manual path in `../worktrees/SKILL.md`.
+4. **Back to the default and pull.** Clean checkout on another branch whose work is pushed →
+   `git -C <repo> switch <default>`. Then `git -C <repo> pull --ff-only`. A pull that cannot
+   fast-forward means the local default diverged: stop and report, never `reset --hard`.
+
+## 5. What is never done
+
+- `reset --hard`, `clean -fdx`, `push --force`, `worktree remove --force`, `stash drop` or `clear` —
+  not to make the picture tidy, not on a "probably fine".
+- Deleting a branch or worktree because its name looks old. Only the proofs in step 3 count.
+- Committing straight to a protected default branch.
+
+## 6. Remote branches: one confirmation, for all of them
+
+Deleting a remote branch reaches everyone who clones the repo. Collect every remote branch whose
+content landed, across all repos, and ask **once** with the full list:
+
+> Remote branches already in main, to delete: `rsc-harness: feat/x, fix/y` · `rsc-brain: feat/z`.
+> ¿Las borro? (sí/no)
+
+On yes: `git -C <repo> push origin --delete <b> ...`. On no: keep them and say so in the report.
+
+## 7. The report
+
+One table, one row per repo, then the open questions. Only facts you observed in this run.
+
+| Repo | Branch | ↑ / ↓ | Worktrees | Local branches | Remote branches | Pending |
+| --- | --- | --- | --- | --- | --- | --- |
+| rsc-harness | main | 0 / 0 | 0 | 0 | 2 deleted | — |
+| rsc-brain | main | 0 / 0 | 1 kept | 1 pushed | — | `feat/z`: live, no PR |
+
+Under it: every deleted squash-merged branch with its tip SHA (it can be brought back with
+`git branch <name> <sha>`), and every item kept with the one action that would close it. A repo that
+is not fully clean is reported as not clean, with the reason; a tidy-looking summary that hides one
+kept item is the failure this skill exists to prevent.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "It's an old branch, nobody uses it" | Age proves nothing. Ancestor or same tree, or it stays. |
+| "Squash-merged, so `-D` is fine without checking" | Check the tree first. A branch with one extra commit after the PR looks identical by name. |
+| "The tree is dirty, I'll stash it to switch to main" | That is someone's work. Ask first; a stash is easy to forget for ever. |
+| "Pull failed, I'll `reset --hard origin/main`" | That throws away local commits. Report the divergence instead. |
+| "I'll `cd` into each child to run git" | `git -C <repo>`. A `cd` plants session state inside the child. |
+| "I'll delete the remote branches as I go" | One list, one confirmation, at the end. |
+| "Report says clean; the kept worktree is a detail" | Say what was kept and why. The report is the deliverable. |
+
+**Next:** after a clean report there is nothing to hand over. Neighbours: `../worktrees/SKILL.md`
+opens isolation for new work; `../ship/SKILL.md` lands one finished branch; `npx @ericrisco/rsc
+upgrade` updates the harness itself, which is a different "actualiza".
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/tidy/evals/README.md

@@ -0,0 +1,23 @@
+# Evals — tidy
+
+The claim under test is the boundary with three neighbours that also say "update" or "clean":
+`rsc upgrade` (the harness version), `worktrees` (opening isolation) and `ship` (landing one
+branch). The negatives prove the split.
+
+## Triggering
+
+Load only `tidy` and run every prompt in 3–5 fresh sessions. A positive passes when `tidy` loads in
+a majority of trials; a negative passes when it stays quiet. Require at least 90% accuracy, and treat
+a trigger on "actualiza rsc a la última versión" as blocking: that one is the same verb, a
+different job.
+
+## Capability
+
+Fixture: a workspace with a root repo and two child repos holding, between them, a merge-landed
+branch, a squash-landed branch whose remote is gone, a branch with one unpushed commit, a landed
+worktree, a worktree with an untracked `.env`, and a child checkout left on a feature branch.
+
+Pass when, after the run: both landed branches are gone (the squash one with its SHA reported); the
+unpushed branch exists on the remote and locally; the landed worktree is gone; the `.env` worktree is
+still there and reported; every checkout is on `main`, 0 ahead and 0 behind; and no remote branch was
+deleted before the single confirmation. Any lost commit or file fails the run outright.

package/skills/tidy/evals/cases.yaml

@@ -0,0 +1,53 @@
+skill: tidy
+
+# `tidy` owns the end-of-day sweep across every repo in the workspace: each on its default
+# branch, pushed, pulled, no landed branch or worktree left. Upgrading rsc itself, opening
+# isolation for new work and landing one branch belong to neighbours.
+should_trigger:
+  - prompt: "Limpia el harness."
+    why: "The owner's own phrase for the whole sweep."
+
+  - prompt: "Actualiza todo a main en estos proyectos, que esté todo subido y sin ramas."
+    why: "Default branch, pushed, no branches: the contract in one sentence."
+
+  - prompt: "Sube y baja todo y quita los worktrees que sobren."
+    why: "Push, pull and retire leftovers across the workspace."
+
+  - prompt: "Tidy up the repos, I have branches and worktrees everywhere."
+    why: "Leftover branches and worktrees across repos, in English."
+
+  - prompt: "Déjalo todo en main y limpio antes de irme."
+    why: "End-of-session state for every repo."
+
+  - prompt: "Sync everything with GitHub and delete the merged branches."
+    why: "Push/pull plus landed-branch cleanup is this skill's whole job."
+
+should_not_trigger:
+  - prompt: "Actualiza rsc a la última versión."
+    route_to: "suggest"
+    why: "Upgrading the harness itself is `rsc upgrade`, not a git sweep."
+
+  - prompt: "Abre un worktree para empezar la feature de pagos."
+    route_to: "worktrees"
+    why: "Opening isolation for new work is the opposite move."
+
+  - prompt: "Esta rama ya pasó review, fusiónala."
+    route_to: "ship"
+    why: "Landing one verified branch is ship."
+
+  - prompt: "Borra los ficheros temporales y el node_modules del proyecto."
+    route_to: "bash-scripting"
+    why: "Disk cleanup inside a project is not branch and remote hygiene."
+
+capability:
+  - scenario: "User says: 'Limpia el harness.' The workspace has a root repo and two child repos. Between them: a branch merged into main, a squash-merged branch whose remote is gone, a branch with one unpushed commit, a worktree whose work landed, a worktree holding an untracked `.env`, and one child checkout left on a clean, pushed feature branch. Another child has an uncommitted edit to README.md."
+    must_include:
+      - "Lists the repos it found (root plus every nested repo) before changing anything, and runs git with `git -C <repo>` instead of changing directory into a child"
+      - "Fetches with prune and reads branches, worktrees, stashes and status for every repo before the first write"
+      - "Deletes the merged branch with `git branch -d`, and the squash-merged one only after the content check (merge-tree tree equals the default's tree), reporting its tip SHA"
+      - "Pushes the branch with the unpushed commit and keeps it, instead of deleting it"
+      - "Retires the landed worktree through `npx @ericrisco/rsc worktrees reap` and keeps the `.env` worktree, reporting the reaper's reason"
+      - "Stops on the uncommitted README.md edit and asks (commit, stash or leave) instead of stashing or discarding it on its own"
+      - "Switches the clean child checkout back to main and pulls with `--ff-only`"
+      - "Asks once, with the full list, before deleting any remote branch"
+      - "Ends with one table per repo plus the kept items and the action that would close each, and never uses reset --hard, push --force, clean -fdx or stash drop"

package/skills/vsl-script/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: vsl-script
+description: "Use when writing or revising a spoken sales video with timed narration, visual cues, supported claims and one next action. NOT writing the surrounding page (that is `landing-copy`) or rendering the video (that is `remotion-video`)."
+tags: [vsl, sales-video, script, storyboard, narration, conversion]
+recommends: [customer-research, offer-design, sales-funnel, landing-copy, remotion-video]
+origin: risco
+---
+
+# VSL script — make the offer understandable on camera
+
+Write the words a person will say and the visible evidence that makes them credible. A VSL is a
+video sales letter: it helps a specific viewer understand an offer and take one next action.
+Its deliverable is a production-ready script, not rendered video or a conversion guarantee.
+
+## Load the offer and the viewing situation
+
+Read existing brand voice and campaign artifacts. Default to
+`02-DOCS/wiki/marketing/<campaign>/research.md`, `offer.md` and `funnel.md`; reuse an established
+location instead of duplicating them. Identify the authoritative offer ID/revision and retain its
+evidence IDs in the script. Ask only for missing facts that affect the argument: buyer, entry source,
+what they already know, desired action, duration and delivery constraints.
+
+The same offer governs price, inclusions, trial conditions, refund terms and CTA destination in the
+page and video. If these disagree, name the stale artifact and correct its handoff; do not choose
+whichever promise sounds stronger. If authority is unresolved, mark the disputed text as draft and
+continue with verified material. Missing testimonials need not block a useful demonstration.
+
+Choose the opening for the viewing situation. A viewer arriving from an explanatory email may
+need a concrete demonstration immediately. Someone who does not recognize the problem may need
+context first. Use research-supported objections rather than a compulsory sequence of emotions.
+One action can be buying, booking, trying or installing; a free product needs no invented price.
+
+## Build an argument that can be shown
+
+Write a short argument map before the full script: **viewer question → answer → visible support →
+next question**. Spend time on the decision that is hardest to believe. Offer an outline alone only
+when requested, or when a consequential unknown prevents the complete draft.
+
+For each claim, retain its source ID, what it actually supports and whether publication is permitted.
+Distinguish a demonstrated function from a measured customer outcome. Keep research-only quotes,
+unapproved names and unsupported numbers outside publishable narration. Rewrite around missing
+proof and list the gap separately; placeholders must not look like actual endorsements.
+
+Explain why the product works using its actual behavior or method. Route an unresolved offer or
+differentiation question to `offer-design`; coining a method name is not evidence. Use deadlines,
+capacity limits and guarantees only when they belong to the authoritative offer. A strong reason
+to act can be the demonstrated fit, without manufactured urgency.
+
+## Budget speech and screen time together
+
+Establish a planning speech rate from the presenter or an explicit assumption. It is a production
+estimate, not an audience benchmark. Reserve silent demonstrations, pauses and title/end cards
+before allocating speech. Overlapping narration and visuals share elapsed time; silent intervals
+cannot also be counted as narration time.
+
+`spoken-word budget = (total seconds − silent seconds) × words per minute / 60`
+
+Draft within that budget, then **count the actual spoken words**. Exclude headings, source notes,
+on-screen text and stage directions. Use one stated counting convention consistently (for example,
+whitespace-delimited words). Calculate the resulting speech duration and reconcile scene timings.
+If it overflows, cut repetition or propose more runtime; do not label an impossible script with
+optimistic timestamps. Leave headroom for breathing where the requested timing allows it.
+
+Give each scene a start/end time, narration, on-screen text or action, and evidence/asset notes.
+The timeline must cover the intended runtime without unexplained gaps or overlap. Write for a
+single listener, with pronounceable prices and ordinary spoken sentences. Place source IDs in a
+production column, not in the presenter's mouth. Use the same primary action when repeated.
+
+## Hand off a filmable draft
+
+Deliver the full script with a brief stating buyer, entry source, offer revision, action, runtime,
+spoken count and timing assumption. Include concrete demonstration/capture instructions, asset
+requirements and a separate list of unsupported claims removed or awaiting evidence/permission.
+For a scene-by-scene production handoff, read [references/storyboard-handoff.md](references/storyboard-handoff.md).
+
+Give `landing-copy` a continuity note containing the exact offer terms, action and evidence IDs;
+do not write the surrounding page unless requested. Give production to `remotion-video` or the
+user's chosen editor, with accessibility and playback needs noted. The script may be approved
+while footage, consent or rendering remains pending; report those states separately.
+
+When saving is requested or part of the campaign task, write `vsl.md` in the campaign folder and
+link it from `02-DOCS/wiki/index.md`. An explanation-only request writes nothing. After a real
+release, use observed viewing drop-offs and actions as revision evidence; separate hypotheses
+about why people left from the measurements themselves. Experiments belong to `ab-testing`.
+
+## Failure patterns
+
+| Pattern | Repair |
+| --- | --- |
+| Narration describes every pixel while the demo races ahead | Let the demonstration carry its evidence; reserve silent viewing time. |
+| A feature screenshot is cited for a savings promise | Narrow the promise to the behavior shown, or obtain outcome evidence. |
+| The spoken price differs from the page | Reconcile both against the identified offer revision before recording. |
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/vsl-script/evals/README.md

@@ -0,0 +1,27 @@
+# VSL script evaluation
+
+Run routing in fresh sessions using only the skill description. Repeat each positive and negative
+prompt three times; require at least 90% correct majority decisions across the cases. Check actual
+near-miss ownership. Structural eval-lint proves only case shape and route existence.
+
+Run the self-contained capability task with and without the skill in independent sessions and
+separate temporary output directories. The baseline must not read skills or rubrics. Blind-grade
+randomized outputs against every must_include item, quoting evidence, plus completeness,
+actionability, correctness and grounding. Score with the catalog behavioral scorer and require
+absolute >= 8.5 and lift >= 1.0. Repeat three times, retain failures and report run count.
+
+Independently count spoken words in the final script. Timing feasibility is arithmetic; performance,
+natural delivery and persuasion remain judgments. Do not report a predicted conversion lift as
+evidence. These definitions claim no executed behavioral result. Re-run after method edits.
+There is no grep-based publication gate: source permissions and claim support need semantic review.
+
+## Initial evaluation — 2026-10-31
+
+One capability scenario, one fresh execution per arm, independently blind-graded:
+with skill **9.9/10**, without **9.9/10**, difference **+0.0**.
+The catalog scorer requires absolute >=8.5 and improvement >=1.0. This run
+passed absolute quality but did not meet the improvement threshold.
+This is a single-trial result, not the repeated-trial protocol above or evidence of conversion gains.
+Arms used separate contexts and files; the scorer reported transcript integrity **not checked**.
+The owner authorized release 3.7.0 with the pack’s incomplete behavioral evidence documented.
+The thresholds remain unchanged; release authorization is not an evaluation pass.

package/skills/vsl-script/evals/cases.yaml

@@ -0,0 +1,51 @@
+skill: vsl-script
+
+should_trigger:
+  - prompt: "Write a spoken sales video for the top of my landing page."
+    why: "Creates the narration and visual plan for a VSL."
+  - prompt: "Quiero explicar mi oferta en vídeo y llevar al espectador a reservar una demo."
+    why: "Spanish sales-video request with a single action."
+  - prompt: "Our presenter cannot get through this pitch in the promised two minutes. Fix the script."
+    why: "Timing feasibility is a script problem even without the VSL label."
+  - prompt: "Turn these verified customer objections into a five-minute video sales argument."
+    why: "Uses evidence and objections to shape a spoken buying decision."
+  - prompt: "Prepare narration, on-screen text and demo cues for our sales video."
+    why: "Produces the production handoff rather than rendering footage."
+
+should_not_trigger:
+  - prompt: "Build the actual video in Remotion from this approved script."
+    route_to: remotion-video
+    why: "Rendering and code are downstream production work."
+  - prompt: "Write the sales page headline, price section and FAQ."
+    route_to: landing-copy
+    why: "Owns written web copy, not spoken narration."
+  - prompt: "Plan the registration and reminder sequence for a live webinar."
+    route_to: webinar
+    why: "The live event journey has its own owner."
+  - prompt: "Set bids and audiences for our Meta video campaign."
+    route_to: ads
+    why: "Paid acquisition management is not a VSL deliverable."
+
+capability:
+  - scenario: >-
+      Write a complete 60-second spoken VSL for a landing visited by warm email subscribers,
+      plus on-screen cues and a short production handoff. The only action is opening a free trial.
+      Offer Q2 revision 7: scheduling app, free trial for 14 days, no card needed, then EUR 12/month
+      if the customer chooses to subscribe. An older page draft says EUR 9/month and a 30-day trial.
+      E1 is a verified product demo showing a customer choosing an available slot and receiving a confirmation;
+      it proves those steps work, not time saved. E2 is a private customer interview saying
+      "I stopped chasing appointment confirmations", with no permission to quote it publicly.
+      No measured time-saving study, customer-count proof, deadline or guarantee exists.
+      The founder wants to say "save five hours every week" and to fit a 20-second silent demo inside
+      the same 60 seconds. Use a planning pace of 135 spoken words per minute. Produce a feasible draft
+      now, explain unsupported claim changes separately, preserve the silent demo, and keep price and trial
+      terms aligned with the authoritative offer. Do not write the surrounding landing page.
+    must_include:
+      - "Delivers actual spoken lines, on-screen cues and a single free-trial action rather than only an outline."
+      - "Preserves Q2 revision 7 terms: 14 days, no card, EUR 12/month only on subscription; explicitly flags the old page terms for correction."
+      - "Allocates 20 seconds with no narration to the demo and at most 40 seconds to speech, yielding a maximum 90 spoken words at 135 words/minute."
+      - "Counts the delivered spoken words, excludes on-screen notes from that count, and gives a timing plan that fits the complete 60 seconds."
+      - "Uses E1 only for observable scheduling/confirmation behavior; removes or qualifies the unsupported five-hours claim rather than presenting it as fact."
+      - "Does not publish or attribute E2's private quote without permission; records the permission gap separately from publishable narration."
+      - "Provides concrete demo capture/visual instructions and source references outside the spoken lines, without claiming a video was rendered."
+      - "Uses no invented testimonial, customer count, scarcity deadline or money-back promise."

package/skills/vsl-script/references/storyboard-handoff.md

@@ -0,0 +1,39 @@
+# Make the script filmable
+
+Use this reference when the script will go to an editor, presenter or animation tool. Keep a single
+script record; a storyboard is a view of the approved narration, not another independently edited offer.
+
+## Scene contract
+
+For each scene, give the editor:
+
+- **Time:** elapsed start/end and whether speech overlaps the visual.
+- **Narration:** exact spoken words, or an explicit silent interval.
+- **Screen:** the action to capture and the minimum readable text.
+- **Evidence:** source ID, permitted use and the particular claim supported.
+- **Asset:** existing file/link, capture needed, or unresolved permission.
+- **Transition:** the visual or verbal connection to the next scene.
+
+For example, a booking-app scene could show a real test account selecting an available slot and
+receiving confirmation. Its evidence is the recorded behavior. It does not establish an average
+time saving. Use test data and conceal personal customer information in the capture.
+
+## Production decisions
+
+Ask about aspect ratio, placement, presenter and visual style only when these are needed and not
+already supplied. A landing embed may need readable interface crops rather than a full desktop
+recording. If no assets exist, mark capture tasks; a proposed screenshot is not an available asset.
+
+Provide captions matching the spoken words and a transcript for the surrounding page. Important
+visual-only information needs a text or audio equivalent. Account for this in the timing instead of
+adding narration after the budget is closed. A silent demo can retain its silence with concise,
+readable captions and a descriptive transcript.
+
+List production dependencies in execution order: verify offer and permitted claims, collect assets,
+record or synthesize approved narration, assemble scenes, review readable text and captions, then
+test the actual playback and destination. Respect the user's chosen production tools and existing
+authorization; a script request does not authorize buying assets or publishing a video.
+
+Before handoff, compare the narration and end card against the linked offer revision. If the offer
+changes after recording, identify affected scenes and page text together. Record what is ready,
+what needs capture and what requires approval; never label the unrendered storyboard a finished film.