rsc-universal 0.1.1

package/skills/rust/references/axum-service.md

@@ -0,0 +1,132 @@
+# axum 0.8 service skeleton
+
+The full HTTP surface behind SKILL.md's essentials. axum 0.8, tokio 1.x, tower middleware.
+
+## Shared state
+
+`AppState` holds the dependencies (DB pool, config, clients). Wrap in `Arc`, inject via `State`:
+
+```rust
+use std::sync::Arc;
+use sqlx::PgPool;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: PgPool,            // PgPool is itself an Arc internally; clone is cheap
+}
+
+pub type Shared = Arc<AppState>;
+```
+
+## Error enum -> IntoResponse
+
+One enum, one mapping. Pattern-match the variant; log only the unexpected; never leak internals.
+
+```rust
+use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
+use serde_json::json;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum ApiError {
+    #[error("not found")]
+    NotFound,
+    #[error("invalid input: {0}")]
+    BadRequest(String),
+    #[error(transparent)]
+    Db(#[from] sqlx::Error),     // `?` on a query lifts sqlx::Error into ApiError
+}
+
+impl IntoResponse for ApiError {
+    fn into_response(self) -> Response {
+        let (status, msg) = match &self {
+            ApiError::NotFound => (StatusCode::NOT_FOUND, "not found".to_string()),
+            ApiError::BadRequest(m) => (StatusCode::BAD_REQUEST, m.clone()),
+            ApiError::Db(e) => {
+                tracing::error!(error = %e, "db error"); // log server-side only
+                (StatusCode::INTERNAL_SERVER_ERROR, "internal error".to_string())
+            }
+        };
+        (status, Json(json!({ "error": msg }))).into_response()
+    }
+}
+```
+
+## Handlers and router
+
+```rust
+use axum::{extract::{Path, State}, routing::get, Json, Router};
+
+async fn get_user(
+    State(state): State<Shared>,
+    Path(id): Path<i64>,                          // {id} parsed to i64; bad input -> 400 automatically
+) -> Result<Json<User>, ApiError> {
+    let user = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)
+        .fetch_optional(&state.pool)
+        .await?                                   // sqlx::Error -> ApiError::Db
+        .ok_or(ApiError::NotFound)?;              // None -> 404
+    Ok(Json(user))
+}
+
+async fn healthz() -> StatusCode { StatusCode::OK }
+
+async fn readyz(State(state): State<Shared>) -> StatusCode {
+    match sqlx::query("SELECT 1").execute(&state.pool).await {
+        Ok(_) => StatusCode::OK,
+        Err(_) => StatusCode::SERVICE_UNAVAILABLE, // 503 when the DB is unreachable
+    }
+}
+
+pub fn build_router(state: Shared) -> Router {
+    Router::new()
+        .route("/users/{id}", get(get_user))      // axum 0.8: {id}, not :id
+        .route("/healthz", get(healthz))
+        .route("/readyz", get(readyz))
+        .with_state(state)
+}
+```
+
+## Tower middleware
+
+Compose cross-cutting concerns as layers (outermost runs first on the request):
+
+```rust
+use std::time::Duration;
+use tower_http::{trace::TraceLayer, timeout::TimeoutLayer, request_id::PropagateRequestIdLayer};
+
+let app = build_router(state)
+    .layer(TraceLayer::new_for_http())            // span + structured access logs via tracing
+    .layer(TimeoutLayer::new(Duration::from_secs(10)))
+    .layer(PropagateRequestIdLayer::x_request_id());
+```
+
+## main + graceful shutdown
+
+```rust
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    tracing_subscriber::fmt().json().init();
+
+    let pool = PgPool::connect(&std::env::var("DATABASE_URL")?).await?;
+    let state = Arc::new(AppState { pool });
+    let app = build_router(state);
+
+    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
+    axum::serve(listener, app)
+        .with_graceful_shutdown(shutdown_signal())  // drain in-flight requests on SIGTERM/Ctrl-C
+        .await?;
+    Ok(())
+}
+
+async fn shutdown_signal() {
+    let ctrl_c = async { tokio::signal::ctrl_c().await.expect("install Ctrl-C handler"); };
+    #[cfg(unix)]
+    let term = async {
+        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
+            .expect("install SIGTERM handler").recv().await;
+    };
+    #[cfg(not(unix))]
+    let term = std::future::pending::<()>();
+    tokio::select! { _ = ctrl_c => {}, _ = term => {} }
+}
+```

package/skills/rust/references/ownership.md

@@ -0,0 +1,86 @@
+# Ownership, borrowing, lifetimes
+
+Deep dive on the model SKILL.md front-loads. Read this when the borrow checker is in your way.
+
+## Move vs borrow vs clone
+
+Every value has exactly one owner. Three things can happen when you pass it:
+
+- **Move** — ownership transfers; the source binding is dead afterward. Default for non-`Copy` types
+  (`String`, `Vec<T>`, structs holding them).
+- **Borrow** — `&T` (shared, many at once, read-only) or `&mut T` (exclusive, exactly one, read-write).
+  No transfer; the owner keeps the value.
+- **Clone** — `.clone()` makes an independent copy. Real cost (allocation for heap types). Legitimate
+  when you genuinely need two independent owners; a smell when used only to dodge a borrow error.
+
+`Copy` types (`i32`, `bool`, `f64`, `char`, small tuples of `Copy`) are bitwise-copied on assignment, so
+they are never "moved away" — no E0382 for them.
+
+Rule of thumb for APIs: **borrow on the way in, own on the way out.** Take `&str`/`&[T]`, return
+`String`/`Vec<T>`. Take `impl AsRef<str>` when you want to accept both `&str` and `String` ergonomically.
+
+## The borrow-checker error catalog
+
+| Error | Meaning | Typical fix |
+| --- | --- | --- |
+| E0382 "value moved here" / "borrow of moved value" | Used a value after moving it | Borrow instead of move; clone only if two owners are truly needed |
+| E0499 "cannot borrow as mutable more than once" | Two `&mut` overlap | Scope the first borrow so it ends before the second |
+| E0502 "already borrowed as immutable" | `&mut` while a `&` is live | Don't mutate through one path while reading through another; collect first, mutate after |
+| E0505 "cannot move out … borrowed" | Moved a value that is still borrowed | End the borrow (drop/scope) before moving |
+| E0597 "does not live long enough" | A reference outlives its referent | Return an owned value, or make the owner outlive the borrow |
+| E0515 "returns a reference to data owned by the current function" | Returning a borrow of a local | Return the owned value, or take the buffer as a `&mut` param |
+
+Non-lexical lifetimes mean a borrow ends at its last *use*, not at the end of the block — so often just
+reordering statements (move the read before the write) resolves E0502 with no restructuring.
+
+## Lifetimes & `'static`
+
+A lifetime annotation (`'a`) names how long a reference is valid; the compiler infers most of them
+(elision). You only annotate when a function returns a reference whose lifetime ties to an input:
+
+```rust
+// The returned &str lives as long as the input slice.
+fn first_word<'a>(s: &'a str) -> &'a str {
+    s.split_whitespace().next().unwrap_or("")
+}
+```
+
+`'static` means "valid for the whole program" — string literals are `&'static str`. `T: 'static` as a
+bound (common in `tokio::spawn`) means "contains no non-`'static` references", i.e. it owns its data; it
+does **not** mean the value lives forever. Prefer owned data over lifetime-threaded structs when the
+lifetimes get noisy — a `String` field is simpler than a `&'a str` field that infects every caller.
+
+## `Cow` — clone on write
+
+`Cow<'_, str>` lets a function return a borrow when it can and an owned value only when it must:
+
+```rust
+use std::borrow::Cow;
+fn normalize(input: &str) -> Cow<'_, str> {
+    if input.contains(' ') { Cow::Owned(input.replace(' ', "_")) } // allocate only when changed
+    else { Cow::Borrowed(input) }                                  // zero-copy fast path
+}
+```
+
+## Smart pointers — the full tree
+
+```text
+Need a value on the heap / a trait object / recursion?  -> Box<T>
+Shared ownership, single-threaded?                       -> Rc<T>
+Shared ownership, across threads or .await?              -> Arc<T>
+Mutate through a shared ref, single-threaded?            -> RefCell<T>   (runtime borrow check)
+Mutate through a shared ref, single-threaded + Rc?       -> Rc<RefCell<T>>
+Mutate shared state across threads (sync)?               -> Arc<Mutex<T>> / Arc<RwLock<T>>
+Mutate shared state across .await?                       -> Arc<tokio::sync::Mutex<T>> (or a channel)
+```
+
+`Rc`/`RefCell` are **not** thread-safe and will not compile across threads — the compiler enforces it via
+`Send`/`Sync`. Reach for `Arc` the moment a value crosses a thread or an `.await` point.
+
+## Interior mutability
+
+`RefCell<T>` moves the borrow check to runtime: `.borrow()` / `.borrow_mut()` panic on a violation
+(two mutable borrows). Use it only when the compile-time check is genuinely too strict (e.g. a graph,
+an observer registry). For atomics and counters prefer `std::sync::atomic` types or `Mutex`; for
+shared async state prefer a channel (message passing) over `Arc<Mutex<T>>` (shared memory) whenever the
+data really flows in one direction.

package/skills/rust/references/testing.md

@@ -0,0 +1,108 @@
+# Testing Rust services
+
+Behind SKILL.md's testing essentials. Unit, integration, doctests, async, fakes.
+
+## Unit tests
+
+Co-locate in a `#[cfg(test)] mod tests` block; they can reach private items in the same module.
+
+```rust
+fn slugify(s: &str) -> String { s.trim().to_lowercase().replace(' ', "-") }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn slugify_lowercases_and_dashes() {
+        assert_eq!(slugify("  Hello World "), "hello-world");
+    }
+}
+```
+
+A data-driven shape (Rust's "table test"): iterate over a slice of cases.
+
+```rust
+#[test]
+fn parse_cases() {
+    let cases = [("42", Some(42)), ("x", None)];
+    for (input, want) in cases {
+        assert_eq!(parse(input), want, "input = {input}");
+    }
+}
+```
+
+## Async tests
+
+```rust
+#[tokio::test]
+async fn fetch_returns_record() {
+    let repo = FakeRepo::with(vec![Record::new(1)]);
+    let got = service::fetch(&repo, 1).await.unwrap();
+    assert_eq!(got.id, 1);
+}
+```
+
+## Integration tests against the Router
+
+Files in `tests/` are separate crates that link the **public** API (so logic must live in `lib.rs`, not
+`main.rs`). Drive the real `Router` with `tower::ServiceExt::oneshot` — no network, no port:
+
+```rust
+// tests/users_api.rs
+use axum::{body::Body, http::{Request, StatusCode}};
+use tower::ServiceExt;
+use my_service::{build_router, test_state};
+
+#[tokio::test]
+async fn get_user_404_when_missing() {
+    let app = build_router(test_state());
+    let res = app
+        .oneshot(Request::get("/users/999").body(Body::empty()).unwrap())
+        .await
+        .unwrap();
+    assert_eq!(res.status(), StatusCode::NOT_FOUND);
+}
+```
+
+## Fakes via traits
+
+Depend on a trait, not a concrete DB type, so unit tests inject a fake without a database:
+
+```rust
+#[async_trait::async_trait]      // still needed for `dyn` trait objects in some versions; native async fn covers static dispatch
+pub trait UserRepo: Send + Sync {
+    async fn find(&self, id: i64) -> Result<Option<User>, ApiError>;
+}
+
+struct FakeRepo(Vec<User>);
+#[async_trait::async_trait]
+impl UserRepo for FakeRepo {
+    async fn find(&self, id: i64) -> Result<Option<User>, ApiError> {
+        Ok(self.0.iter().find(|u| u.id == id).cloned())
+    }
+}
+```
+
+For sqlx integration tests against a real DB, `#[sqlx::test]` provisions an isolated test database per
+test and rolls it back.
+
+## Doctests
+
+Examples in `///` docs are compiled and run by `cargo test --doc` — they cannot rot silently:
+
+```rust
+/// Slugifies a title.
+///
+/// ```
+/// assert_eq!(my_service::slugify("Hello World"), "hello-world");
+/// ```
+pub fn slugify(s: &str) -> String { /* ... */ }
+```
+
+## Tooling
+
+- `cargo nextest run` — faster, isolated, clearer parallel test output than `cargo test` (it does not
+  run doctests; keep `cargo test --doc` in the gate).
+- `insta` — snapshot testing for JSON/response bodies; `cargo insta review` to accept diffs.
+- Run the whole gate via `scripts/verify.sh` (fmt + clippy + test + audit).

package/skills/rust/scripts/verify.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a Rust crate/workspace (superset of CI).
+#
+# Usage:
+#   cd <your-crate-root>      # the directory containing Cargo.toml
+#   ./verify.sh
+#
+# Runs: cargo fmt --check, cargo clippy -D warnings, cargo test, and cargo audit (if installed).
+# Read-only: it never mutates your source.
+# Degrades gracefully: if there is no Cargo.toml or no `cargo` on PATH, it prints a skip
+# note and exits 0 (a clean/empty target is not a failure). Tools that are not installed
+# are skipped with a warning, not a failure. Real problems exit non-zero.
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+set -euo pipefail
+
+# Colors only when stdout is a TTY (keeps logs/CI output clean).
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have()  { command -v "$1" >/dev/null 2>&1; }
+warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info()  { printf -- '----- %s\n' "$*"; }
+
+# No manifest? Nothing to verify - skip cleanly (do not fail an empty target).
+if [ ! -f Cargo.toml ]; then
+  warn "no Cargo.toml in $(pwd) - nothing to verify (cd into your crate root to run the gate)."
+  exit 0
+fi
+
+# No toolchain? Skip cleanly.
+if ! have cargo; then
+  warn "cargo not found - install the Rust toolchain (https://rustup.rs) to run the gate."
+  exit 0
+fi
+
+# 1. cargo fmt --check - formatting is non-negotiable; --check never rewrites files.
+info "cargo fmt --check"
+if cargo fmt --all -- --check; then
+  ok "formatting clean"
+else
+  fail "unformatted code (run: cargo fmt --all)"
+fi
+
+# 2. cargo clippy -D warnings - lints are correctness gates here, not style suggestions.
+info "cargo clippy -- -D warnings"
+if have cargo-clippy || cargo clippy --version >/dev/null 2>&1; then
+  if cargo clippy --all-targets --all-features -- -D warnings; then
+    ok "clippy clean"
+  else
+    fail "clippy reported warnings/errors"
+  fi
+else
+  warn "clippy not found (rustup component add clippy)"
+fi
+
+# 3. cargo test - unit + integration; add --doc separately for doctests if desired.
+info "cargo test"
+if cargo test --all-targets; then
+  ok "tests pass"
+else
+  fail "tests failed"
+fi
+
+# 4. cargo audit - optional; RustSec advisory findings are a real failure.
+info "cargo audit"
+if have cargo-audit || cargo audit --version >/dev/null 2>&1; then
+  if cargo audit; then
+    ok "no known vulnerabilities"
+  else
+    fail "cargo audit found advisories"
+  fi
+else
+  warn "cargo audit not found (cargo install cargo-audit)"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/sales-pipeline/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: sales-pipeline
+description: "Use when an operator runs deals out of a spreadsheet, Notion, or Airtable and wants real stages, win-probabilities, deal hygiene, a weekly follow-up sweep, or a defensible roll-up forecast off the list — and when the pipeline looks full but nothing closes. Triggers: 'set up stages and a weighted forecast for my deal sheet', 'which deals are stale and what do I follow up on this week', 'my forecast keeps slipping every quarter', 'what's my pipeline coverage vs a 250k quota', 'build me a lightweight CRM without Salesforce', 'munta'm un CRM lleuger amb etapes i previsió', 'quins deals estan encallats', 'previsió de vendes del pipeline'. NOT statistical / scenario forecast modeling, time-series or cohort projections (that is forecasting), NOT sourcing new prospects (that is lead-gen), NOT writing the outbound emails (that is cold-outreach), NOT writing the proposal/quote (that is proposals), NOT the post-close kickoff (that is client-onboarding)."
+tags: [sales, crm, pipeline, forecasting, deal-hygiene, business-ops]
+recommends: [forecasting, lead-gen, cold-outreach, proposals, client-onboarding, spreadsheet-ops]
+origin: risco
+---
+
+# Sales Pipeline — A Disciplined CRM Out of a Flat File
+
+*You run a small team's pipeline from a CSV, a markdown table, or a Notion DB — no Salesforce, no RevOps. Your one rule: the forecast is what the gated stages and current win rates say, not what the rep hopes. Happy-ears deals do not inflate the number on your watch.*
+
+This skill does four jobs and refuses to drift into the siblings that own the rest: (1) define a **small set of gated stages** with objective exit criteria, (2) keep every open deal **hygienic** (next step + close date + last-touch, flag the stale), (3) run a **weekly follow-up sweep**, and (4) roll a **defensible weighted forecast** with a coverage ratio. The heavy statistical modeling, the lead sourcing, the outbound copy, the proposal, the post-close handoff — each belongs to a sibling. Route, do not improvise their job.
+
+## When to use / when NOT
+
+Use when the operator already has a list of deals and wants stages, probabilities, hygiene, a weekly sweep, coverage vs quota, or pipeline velocity — or when they describe the symptom "pipeline looks full but nothing closes."
+
+Do NOT use when the ask is one of these — route to the owner:
+
+| The ask | Owner | Why it is not here |
+|---|---|---|
+| 3-scenario revenue model, seasonality, cohort/time-series projection | `forecasting` | That is the statistical/scenario layer. This skill only does the simple stage-weighted roll-up that falls out of the pipeline. |
+| Find / scrape / qualify NEW prospect companies to add | `lead-gen` | This skill operates on deals that already exist in the list. |
+| Write the cold email or follow-up sequence to contact a prospect | `cold-outreach` | This skill schedules the next step; it does not write the words. |
+| Write the proposal / quote / SOW for a qualified deal | `proposals` | A stage transition is not a document. |
+| Post-close kickoff, account setup, onboarding | `client-onboarding` | The moment a deal is Closed-Won it leaves this skill. |
+| Generic dashboard / charting of arbitrary metrics, KPI tree design | `dashboard` / `kpi-framework` | This skill emits pipeline numbers, not a charting layer. |
+
+The boundary worth memorizing: **`forecasting` owns the math models; sales-pipeline owns the operational CRM.** When the request needs Monte Carlo, regression, or scenario trees, hand it over.
+
+## The artifact first — the deal-record schema
+
+Everything below lints against one table. Define it before anything else, because hygiene, the sweep, and the forecast are all just operations on these columns. One deal = one row. Required columns:
+
+| column | meaning | rule |
+|---|---|---|
+| `id` | stable deal id | unique, never reused |
+| `company` | the account | — |
+| `value` | deal value (one currency, document which) | number, no symbols |
+| `stage` | current stage | from the allowed set (next section) |
+| `win_prob` | stage win-probability as a decimal | 0–1, **owned by the stage, not the rep** |
+| `weighted_value` | `value × win_prob` | must equal the product (lint enforces it) |
+| `close_date` | expected close (ISO `YYYY-MM-DD`) | required on every open deal |
+| `next_step` | the next concrete action + its date | required on every open deal |
+| `last_touch` | date of last real activity (ISO) | required on every open deal |
+| `owner` | who owns the deal | — |
+| `forecast_category` | Pipeline / Best Case / Commit / Closed / Omitted | a category, **not** a stage |
+
+One good open row (CSV):
+
+```csv
+id,company,value,stage,win_prob,weighted_value,close_date,next_step,last_touch,owner,forecast_category
+D-104,Acme,40000,Discovery,0.30,12000,2026-07-15,"2026-06-09 demo with VP Eng",2026-05-30,Dana,Best Case
+```
+
+Hard rule, no exceptions: **no open deal may be missing `next_step`, `close_date`, or `last_touch`.** A deal with no next step is not a deal, it is a wish. The sweep and the forecast both treat a missing field as a defect, not a blank.
+
+## The stage model — small, gated, stage-owned probability
+
+Default to **six stages**. Five stages with clear exit criteria beat nine stages with none. Each stage advances only on an objective, verifiable **buyer action** — never on rep optimism.
+
+| stage | default `win_prob` | exit criterion (the verifiable buyer action that advances it) |
+|---|---|---|
+| Prospecting | 0.05 | Buyer agreed to a first real conversation (meeting on the calendar). |
+| Qualification | 0.10 | BANT/MEDDIC documented "yes" — budget, authority, need, timeline confirmed. |
+| Discovery | 0.30 | Buyer confirmed the problem + success criteria; you have the buying process and review layers. |
+| Proposal/Demo | 0.40 | Proposal or demo delivered and acknowledged; buyer engaged on it. |
+| Negotiation | 0.65 | Terms/price under active discussion; verbal intent + a mutual close plan. |
+| Closed | 1.0 / 0.0 | Signed (Won) or formally lost (Lost). |
+
+Rules that make the table hold:
+
+- **Probability belongs to the stage, not the deal.** A rep who hand-sets one deal to 90% in Discovery is sandbagging or happy-ears; both poison the forecast. The stage carries the number, uniformly. *(Why: it removes the single biggest source of forecast inflation in small teams.)*
+- **No stage advances without its exit criterion met AND a calendared next step.** "If you don't know the criteria, timeline, review layers and legal steps, the close date is a guess."
+- **Negotiation 50–80% is a band, not a default 80.** Pick within the band on real signal (legal in motion → higher); never max it out reflexively.
+
+Qualification gate: run **BANT as a ~60-second screen** for small deals; switch to **MEDDIC/SPICED above ~$25K ACV**. The full six-stage playbook — every exit criterion, required fields per stage, the BANT-vs-MEDDIC pillars, and the forecast-category mapping — lives in `references/stage-playbook.md`.
+
+## Deal hygiene — the required-field gate and the stale rules
+
+Roughly **40–60% of B2B CRM pipeline is stale** (no progression in 30+ days). A forecast built on a stale list is fiction. Apply an activity-decay model on every open deal:
+
+| condition | action |
+|---|---|
+| Missing `next_step` / `close_date` / `last_touch` | **Defect** — flag, do not forecast until fixed. |
+| No touch for **14+ days** | **Halve** the deal's effective weight in the forecast. |
+| No touch for **30+ days** | **Exclude** from coverage entirely (treat as stale, not pipeline). |
+| Sitting **> 1.5× the average time-in-stage** | Flag for review — it is stuck. |
+| `close_date` already in the past, deal still open | Flag — the date is a lie; re-set or disqualify. |
+
+Bad → Good on a single row:
+
+```text
+BAD  (open, but a wish dressed as a deal — fails the gate):
+  D-220,Globex,60000,Proposal,0.80,48000,,,,Sam,Commit
+  ^ win_prob hand-set to 0.80 in Proposal, no close_date, no next_step,
+    no last_touch, Commit category on zero evidence.
+
+GOOD (gated, hygienic, stage-owned probability):
+  D-220,Globex,60000,Proposal,0.40,24000,2026-08-01,"2026-06-12 send revised SOW",2026-06-02,Sam,Best Case
+  ^ win_prob = stage default, weighted_value recomputed, dated next step,
+    fresh last_touch, category demoted to match the evidence.
+```
+
+## The weekly follow-up sweep
+
+Build hygiene into a **~45-minute WEEKLY pipeline review**, not a quarterly cleanup — stale deals compound fast and a quarterly purge always finds the rot too late. The sweep is a fixed checklist; run it and emit a prioritized follow-up list:
+
+- [ ] Every open deal has `next_step` + `close_date` + `last_touch` — list the defects first.
+- [ ] Stale: no touch 14+ days (halve) and 30+ days (drop) — surface both buckets.
+- [ ] `close_date` in the past on an open deal — re-set or disqualify.
+- [ ] Slipped: `close_date` pushed two weeks in a row — flag; two slips is a pattern, not noise.
+- [ ] Stuck: time-in-stage > 1.5× the average for that stage.
+- [ ] Output: a ranked follow-up list (highest `weighted_value` × most stale first), each with the one concrete next action and its date.
+
+Track coverage as a **4-week rolling trend**, not a single snapshot. **Two consecutive weeks of declining coverage with no closes is a red flag** — escalate, do not wait for quarter-end.
+
+## The forecast roll-up
+
+Three numbers fall out of a clean pipeline. Compute them; do not model beyond them (that is `forecasting`).
+
+**Weighted forecast** = Σ over open deals of `value × stage win_prob`. Apply the stale decay first (halve at 14d, drop at 30d) so the number reflects live pipeline, not the wish list.
+
+**Pipeline coverage ratio** = Total Qualified Pipeline Value ÷ Revenue Target. Read it against the segment, because win rates differ:
+
+| segment | ACV / win rate | coverage min | coverage target |
+|---|---|---|---|
+| Enterprise | $100K+ / 15–20% win | 5× | 6–7× |
+| Commercial | $25–100K / 20–30% | 3.5× | 4–5× |
+| SMB | <$25K / 30–40% | 2.5× | 3–4× |
+
+**Pipeline velocity** = `(Open opps × Avg deal size × Win rate) ÷ Sales-cycle length (days)` → dollars/day. Cycle length has the most leverage: a ~20% cut in cycle length lifts velocity ~25%.
+
+Forecast categories are **not** stages — map them separately: Pipeline / Best Case / Commit / Closed / Omitted. As a sanity expectation, roughly **~25% of "Pipeline", a third-to-half of "Best Case", and near-all of "Commit"** typically lands in-quarter.
+
+**The current-win-rate caveat — non-negotiable.** 2025 benchmarks moved against sellers: B2B win rates fell ~21% → ~18% and cycles lengthened ~12% YoY. **Forecast with the current ~18% win rate and your real cycle length, never last year's optimistic numbers.** A 24-month-old win rate is the quietest way to over-forecast.
+
+Worked examples — weighted forecast on a 5-deal list, coverage by segment, velocity, and the exact column contract `verify.sh` enforces — are in `references/forecasting-math.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Rep hand-sets `win_prob` per deal | Happy-ears/sandbagging inflate the forecast; the number stops being comparable | Probability is owned by the stage, applied uniformly |
+| Stages with no exit criteria | "Discovery" becomes a place deals go to die; no one can verify progression | Every stage gates on an objective buyer action |
+| Counting stale deals (30+ days no touch) in coverage | 40–60% of pipeline is stale; coverage looks healthy while nothing moves | Drop 30d+ from coverage, halve 14d+, flag stuck deals |
+| Forecasting off list price, not weighted value | Treats a Qualification deal like a signed one; massive over-forecast | `value × stage win_prob`, decayed for staleness |
+| Quarterly cleanup instead of weekly | Rot is found three months too late; the quarter is already lost | 45-min weekly sweep; 4-week rolling coverage trend |
+| Using a 24-month-old win rate | 2025 win rates fell to ~18%, cycles +12%; old numbers over-forecast | Use the current win rate and your real cycle length |
+| `forecast_category` set to "Commit" on a Discovery deal | Category drifts from evidence; the commit number becomes a fantasy | Category must match documented evidence, not hope |
+| Nine micro-stages "for granularity" | More stages, less discipline; reps can't tell them apart | Six gated stages beat nine ungated ones |
+| Open deal with no `next_step` | It is a wish, not a deal; it silently ages into staleness | No next step → it is a defect, surface it in the sweep |
+
+## References and siblings
+
+- `references/stage-playbook.md` — the six stages in full, exit criteria, required fields per stage, BANT-vs-MEDDIC, forecast-category mapping.
+- `references/forecasting-math.md` — worked weighted-forecast / coverage / velocity examples and the verify column contract.
+
+Siblings that own the adjacent jobs — route to them by name: `../forecasting/SKILL.md` (the math models), `../lead-gen/SKILL.md` (sourcing), `../cold-outreach/SKILL.md` (the outbound copy), `../proposals/SKILL.md` (the quote/SOW), `../client-onboarding/SKILL.md` (post-close). For wiring the list to Sheets/Notion or bulk edits, `../spreadsheet-ops/SKILL.md`.
+
+To lint a pipeline file you produced — required columns, required fields on open deals, stage names in the allowed set, `win_prob` in range, `weighted_value == value × win_prob`, and a coverage line present — run `scripts/verify.sh path/to/pipeline.csv` (read-only; a clean or empty file exits 0).

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

@@ -0,0 +1,13 @@
+# Evals — sales-pipeline
+
+`cases.yaml` is run by the rsc eval harness. The `should_trigger` and
+`should_not_trigger` prompts test the description router: each should-trigger
+prompt must load this skill, and each should-not-trigger prompt must route to
+the named real sibling (`forecasting`, `lead-gen`, `cold-outreach`,
+`proposals`, `client-onboarding`) instead. The single `capability` case is
+graded by a judge against its `must_include` rubric — feed the scenario's 6-row
+deal CSV to the skill and check the output hits every rubric line (required-field
+gate, stage-owned probabilities, 14d/30d stale decay, weighted forecast,
+coverage-vs-quota verdict at the current ~18% win rate, and a lint-able artifact).
+No external API or network access is required; everything is local to the model
+and the harness.

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

@@ -0,0 +1,60 @@
+skill: sales-pipeline
+
+# Prompts that MUST load `sales-pipeline`. The skill runs a lightweight CRM out
+# of a flat file: gated stages, deal hygiene, a weekly follow-up sweep, and a
+# stage-weighted roll-up forecast with a coverage ratio. It does NOT do
+# statistical/scenario modeling (forecasting), source prospects (lead-gen),
+# write outbound copy (cold-outreach), write the proposal (proposals), or run
+# post-close onboarding (client-onboarding).
+should_trigger:
+  - prompt: "Set up stages and a weighted forecast for my deal spreadsheet."
+    why: "Core job — define gated stages with exit criteria and roll a stage-weighted forecast off an existing deal list."
+
+  - prompt: "Which of my deals are stale and what should I follow up on this week?"
+    why: "Deal hygiene + the weekly sweep — the 14d/30d activity-decay rules and the prioritized follow-up list answer this directly."
+
+  - prompt: "My forecast keeps slipping every quarter — the pipeline looks full but nothing closes."
+    why: "Non-obvious: the user names a symptom, not the skill. The diagnosis is stale-deal inflation + counting unweighted/uncommitted pipeline in coverage, which is exactly this skill's hygiene + coverage work."
+
+  - prompt: "Munta'm un CRM lleuger amb etapes i previsió de vendes sense pagar Salesforce."
+    why: "Catalan phrasing for a lightweight CRM with stages and a sales forecast — same skill regardless of language."
+
+  - prompt: "What's my pipeline coverage versus a 250k quarterly quota, and is it enough?"
+    why: "Non-obvious: coverage ratio = qualified pipeline / target, read against the segment benchmark (3.5x min / 4-5x target for Commercial). The 'is it enough' verdict is owned here."
+
+  - prompt: "Build me a stage model with exit criteria for a 3-person sales team with no RevOps."
+    why: "Stage-model design — the six gated stages with verifiable buyer-action exit criteria and stage-owned probability is the skill's first artifact."
+
+should_not_trigger:
+  - prompt: "Build a 3-scenario revenue forecast model with monthly seasonality and a cohort projection."
+    route_to: forecasting
+    why: "Statistical/scenario modeling and time-series/cohort projection is the forecasting layer; sales-pipeline only does the simple stage-weighted roll-up."
+
+  - prompt: "Find me 200 prospect companies in fintech with verified emails to add to my pipeline."
+    route_to: lead-gen
+    why: "Sourcing/qualifying NEW prospects is lead-gen; sales-pipeline operates on deals that already exist in the list."
+
+  - prompt: "Write the cold email sequence to contact these prospects and book meetings."
+    route_to: cold-outreach
+    why: "Writing the outbound copy and cadence is cold-outreach; sales-pipeline schedules the next step but does not write the words."
+
+  - prompt: "Draft the proposal and quote for the deal we just qualified."
+    route_to: proposals
+    why: "The proposal/quote/SOW document is owned by proposals; a stage transition is not a document."
+
+  - prompt: "We just closed the deal — set up the client kickoff and account onboarding."
+    route_to: client-onboarding
+    why: "Post-close handoff, kickoff, and account setup is client-onboarding; a Closed-Won deal leaves this skill."
+
+capability:
+  - scenario: "Given a 6-row deal CSV with mixed staleness, some hand-set win_probs, and missing next steps, produce a cleaned pipeline (stage-owned probabilities, recomputed weighted_value), a flagged-stale list, a weekly follow-up list, a weighted forecast, and coverage versus a stated quota."
+    must_include:
+      - "Applies the required-field gate: flags every open deal missing next_step, close_date, or last_touch as a defect."
+      - "Resets win_prob to the stage default (probability owned by the stage, not hand-set per deal) and recomputes weighted_value = value x win_prob."
+      - "Flags stale deals by the activity-decay rules: halve weight at 14+ days no touch, exclude from coverage at 30+ days."
+      - "Flags deals sitting > 1.5x the average time-in-stage, and any open deal with a past close_date."
+      - "Weighted forecast = sum(value x stage win_prob) after stale decay, not list-price sum."
+      - "Coverage = qualified (non-stale) pipeline / target, with a verdict against the segment benchmark (e.g. 3.5x min / 4-5x target for Commercial)."
+      - "Uses the current ~18% win rate / real cycle length, not an optimistic last-year number."
+      - "Emits an artifact (CSV or markdown table) with the required columns that scripts/verify.sh can lint, plus a coverage summary line."
+      - "Routes statistical/scenario modeling to forecasting rather than attempting it inline."