@ericrisco/rsc 0.1.43 → 0.1.45

package/skills/calendar-scheduling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: calendar-scheduling
-description: "Use when adding booking/scheduling to a product — a 'pick a slot' page, an embedded Cal.com/Calendly widget, or a flow that shows real availability and writes the confirmed meeting to Google/Outlook/Apple — and when fixing the three classic bugs: double-booking, wrong-time-after-DST, and orphaned events on reschedule. Triggers: 'add a book-a-call page', 'embed Cal.com and white-label it', 'show my real availability and create the calendar event', 'we keep getting double-booked when two people pick the same slot', 'bookings show the wrong time after the clocks changed', 'fire a webhook on each booking', 'añade reservas de citas a la web y evita solapamientos con mi calendario de Outlook', 'evita que se reserve dos veces el mismo hueco'. NOT raw calendar CRUD, free/busy plumbing, or watch channels for an internal app with no booking surface (that is google-workspace), NOT a generic non-booking inbound event receiver (that is webhooks), NOT charging for a paid appointment (that is stripe)."
+description: "Use when a product needs a booking surface — a pick-a-slot page, a Cal.com/Calendly embed, or real availability plus the confirmed meeting written to Google/Outlook — or when fixing double-booking, DST drift, or orphaned reschedule events. NOT calendar CRUD with no booking surface (that is `google-workspace`), NOT the payment (that is `stripe`)."
 tags: [scheduling, booking, calendar, calcom, calendly, google-calendar, availability, webhooks]
 recommends: [google-workspace, webhooks, automation-flows, email-connector, stripe, sales-pipeline]
 profiles: []
@@ -12,17 +12,9 @@ origin: risco
 Scheduling is always two halves bolted together: a **booking surface** (an
 external person reserves a slot — embed, atom, or API call) and **calendar
 sync** (you read free/busy to compute availability and write the confirmed
-event back). Ship one without the other and you get the three bugs this skill
-exists to prevent:
-
-- **Double-booking** — two people grab the same slot because availability was
-  computed in the browser or written before a re-check.
-- **Timezone drift** — a meeting shows the wrong hour after a DST change because
-  a wall-clock time was stored instead of an instant + IANA zone.
-- **Orphaned events** — a reschedule creates a *second* calendar event instead
-  of moving the first, so the calendar fills with phantoms.
-
-Everything below is in service of not shipping those.
+event back). Ship one without the other and you get the three bugs the rest of
+this skill exists to prevent: **double-booking**, **timezone drift** after a DST
+change, and **orphaned events** on reschedule.
 
 ## Decide the altitude first
 
@@ -38,7 +30,9 @@ Pick the lowest-code option that still owns the data model you actually need.
 Why per row: the embed is zero-maintenance but a black box; the atom/API buys
 your own UI without owning sync; raw provider is full control and full
 liability; a unified API trades a vendor for not maintaining three calendar
-integrations. Full comparison in `references/provider-matrix.md`.
+integrations. Hosting, auth/scopes, webhook events, cross-domain support and
+when each wins, per provider:
+[`references/provider-matrix.md`](references/provider-matrix.md).
 
 - **Cal.com** is open-source and self-hostable. Self-hosted instances get
   **unlimited API access** (no cloud rate limit) and full white-label by
@@ -78,9 +72,6 @@ Scope ladder, narrowest first:
 - `calendar` / `calendar.events` — restricted; request only if you genuinely
   manage arbitrary events the app didn't create.
 
-**Calendly:** OAuth 2.1 or a personal access token. **Cal.com self-host:** no
-rate-limit anxiety, so no token-bucket gymnastics needed in your client.
-
 ## Availability without double-booking — the core flow
 
 Both classic races (computing slots in the browser, and writing the event
@@ -107,8 +98,10 @@ Decision — do you need a hold step?
 | Multi-step booking form, payment, or high contention | Yes — a TTL lock so the slot survives the form and releases if abandoned |
 
 Google's availability primitive is `freebusy.query` (POST, returns busy blocks
-per calendar); the write is `events.insert`. Payloads in
-`references/google-calendar-sync.md`.
+per calendar); the write is `events.insert`. Both payloads (with
+`conferenceData` for Meet), `watch` channels + sync tokens, recurring-event edge
+cases and refresh-token handling:
+[`references/google-calendar-sync.md`](references/google-calendar-sync.md).
 
 ## Timezone correctness
 
@@ -180,15 +173,6 @@ that orchestration is **automation-flows**, not here.
 | Poll the calendar for changes | Slow, rate-limited, misses edits | `watch` push channels + incremental sync tokens |
 | Write new code against Calendly v1 | v1 API + webhooks dead since May 2025 | Calendly v2 (OAuth 2.1 / PAT) |
 
-## References
-
-- `references/provider-matrix.md` — Cal.com vs Calendly vs Google direct vs
-  Nylas v3 vs Cronofy: hosting, auth/scopes, webhook events, cross-domain,
-  when each wins.
-- `references/google-calendar-sync.md` — `freebusy.query` and `events.insert`
-  (with `conferenceData` for Meet) payloads, `watch` channels + sync tokens,
-  recurring-event edge cases, refresh-token handling.
-
 Adjacent skills: raw calendar CRUD / watch channels with no booking →
 [`../google-workspace/SKILL.md`](../google-workspace/SKILL.md); charging for a
 paid appointment → [`../stripe/SKILL.md`](../stripe/SKILL.md); booking funnel as

package/skills/case-studies/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: case-studies
-description: "Use when turning a real customer win into a case study or testimonial — a metrics-anchored success story or an attributed quote a prospect can act on, including when a great result reads like a brochure and needs to convert. Triggers: 'turn this customer win into a case study', 'we cut their churn 40% — write it up', 'draft a testimonial quote from this customer-interview transcript', 'we have a 40% drop but the write-up sounds like marketing fluff — make it convert', 'build a reusable customer-story template plus an intake/consent form', 'escríbeme un caso de éxito de este cliente con métricas y una cita', 'redacta un cas d'èxit amb mètriques'. NOT the deck that pitches the vision to a room (that is pitch-deck), NOT a long thought-leadership article with no single named customer (that is article-writing)."
+description: "Use when turning one named customer's measured win into a case study, or the attributed testimonial quote that travels with it — consent-cleared, metrics-anchored proof for the next skeptical buyer. NOT the deck that sells the vision to a room (that is `pitch-deck`), NOT thought-leadership with no single named customer (that is `article-writing`)."
 tags: [case-study, testimonial, social-proof, customer-story, conversion]
 recommends: [pitch-deck, article-writing, retention, review-management, brand-voice, landing-copy]
 origin: risco
@@ -29,7 +29,7 @@ If the request is not a single customer's measured outcome, hand it off before y
 | Drop the proven quote into a converting page | `../landing-copy/SKILL.md` |
 | Price the offer this win justifies | `pricing` |
 
-The one-sentence call: it is a case study if a real, named customer already got a measured result and consented to be quoted. Vision-to-a-room is `pitch-deck`; no-single-customer is `article-writing`.
+The one-sentence call: it is a case study if a real, named customer already got a measured result and consented to be quoted.
 
 ## The intake gate — STOP if any of these is missing
 
@@ -61,7 +61,7 @@ quote_source: "interview-2026-05-20.txt"
 ---
 ```
 
-`consent: pending` means draft-only. `consent: anonymized` means no name/logo/identifying detail ships. Only `consent: signed` may publish a named, quoted, imaged customer. Full intake form, approval-email wording, and substantiation notes live in `references/consent-and-substantiation.md`.
+`consent: pending` means draft-only. `consent: anonymized` means no name/logo/identifying detail ships. Only `consent: signed` may publish a named, quoted, imaged customer. Full intake form, consent/release checklist, approval-email wording, substantiation and insider-disclosure notes, and the anonymization fallback rules live in `references/consent-and-substantiation.md`.
 
 ## Case-study anatomy
 
@@ -140,8 +140,3 @@ Write the prose so these fall out cleanly; do not produce a separate brochure fo
 `scripts/verify.sh <case-study.md>` is a read-only structural and legal lint. It checks for a quantified hero metric, the required Challenge/Solution/Result sections and snapshot box, an attributed quote, a before→after signal, a CTA, and the `consent:` / `approved:` marker — and it warns on the superlative banlist. It **fails hard** when the hero has no metric, a core section is missing, or consent is unmarked, because shipping an un-consented named quote is the legal risk. It is structural lint only; persuasion quality is the capability eval's job and yours.
 
 Hand off when the piece is done: the proven quote → `../landing-copy/SKILL.md`, the broader narrative → `../article-writing/SKILL.md`, the slide version → `../pitch-deck/SKILL.md`, the public-review angle → `../review-management/SKILL.md`.
-
-## References
-
-- `references/case-study-skeleton.md` — the full ordered template (results headline, snapshot box, C-S-R sections with Context-Achievement-Relevance metric lines, attributed quote block, CTA) plus a filled mini-example with consent front-matter.
-- `references/consent-and-substantiation.md` — intake-form fields, consent/release checklist, exact-quote-approval email wording, FTC substantiation and insider-disclosure notes, anonymization fallback rules.

package/skills/chatbot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chatbot
-description: "Use when putting a support or sales bot on a live website and it must behave — writing or hardening its persona/system prompt, designing the bot→human handoff, stopping it inventing prices/policies/refunds, defending against jailbreaks and prompt injection, qualifying leads, or setting launch metrics and a kill switch. Triggers: 'put a chatbot on our site that answers from our docs', 'add a chat widget', 'our bot promised a refund we don't offer — lock it down', 'stop people jailbreaking our website assistant', 'design the handoff to a human agent', 'qualify leads and book demos', 'necesito un chatbot de ventas para la web que califique leads i reservi demos'. NOT building the agent loop/RAG index/eval harness under it (that is building-agents), and NOT a human answering one live ticket (that is customer-support)."
+description: "Use when a support or sales bot on a live website must behave: persona/system prompt, grounding so it cannot invent prices or policy, jailbreak and injection defense, the human handoff, launch metrics and kill switch. NOT the agent loop or RAG index under it (that is `building-agents`), NOT a human answering one ticket (that is `customer-support`)."
 tags: [chatbot, support-bot, sales-bot, handoff, guardrails, grounding, conversational-ai]
 recommends: [building-agents, rag, customer-support, agent-safety, prompt-engineering, brand-voice]
 origin: risco
@@ -10,26 +10,14 @@ origin: risco
 
 This skill owns the bot that sits on a public site 24/7, answers support or sales questions, deflects what it safely can, and hands off cleanly what it can't. Four parts and nothing else: its **persona** (system prompt), its **grounding** (what it's allowed to know), its **guardrails** (what it must never say or do), and its **handoff** (when and how it gives up to a human). The retrieval engine under it is [`../building-agents/SKILL.md`](../building-agents/SKILL.md); the human who picks up the escalation is [`../customer-support/SKILL.md`](../customer-support/SKILL.md). You are productizing a bot, not engineering an agent and not working a ticket.
 
+Not here: the agent loop, tool schemas and eval harness → [`../building-agents/SKILL.md`](../building-agents/SKILL.md) (and `rag` for the index half: chunking, embeddings, rerank); one live ticket answered by a human — triage, SLA, macros → [`../customer-support/SKILL.md`](../customer-support/SKILL.md); prompt *wording* in the abstract → `prompt-engineering`; general LLM abuse taxonomy beyond the public-bot case → `agent-safety`; the golden-set eval as an engineering artifact → `agent-eval`; win-back/renewal → [`../retention/SKILL.md`](../retention/SKILL.md); new-customer welcome → [`../client-onboarding/SKILL.md`](../client-onboarding/SKILL.md); generic automation wiring → [`../automation-flows/SKILL.md`](../automation-flows/SKILL.md); WhatsApp/Telegram channel plumbing → [`../whatsapp-telegram/SKILL.md`](../whatsapp-telegram/SKILL.md).
+
 ## The one rule
 
 > The bot may state only what it can **cite** (from approved KB) or **confirm** (a fact it was given). Everything else is "Let me connect you to a human." Grounded-or-handoff. It never improvises a price, a policy, a refund, or a promise.
 
 Why: a hallucinated answer is a binding answer. Air Canada's bot invented a bereavement-refund policy; a tribunal held the airline liable for what the bot said (multiple 2025 retrospectives, accessed 2026-06-02). The bot speaks for the company in court, so cap what it's allowed to invent at zero.
 
-## When to use / When NOT to use
-
-**Use when:** standing up a support/sales chat widget on a website; writing or hardening the bot's system prompt (scope, refusals, tone); designing escalation to a human and what context travels; stopping the bot inventing policy/price (incident hardening); defending against jailbreaks / prompt injection on a public bot; building a sales bot that qualifies a lead and books a demo; defining launch metrics (deflection/containment/handoff) and the threshold that pulls it back.
-
-**Do NOT use when:**
-
-- Building the agent loop, tool schemas, RAG pipeline, or eval harness under the bot → [`../building-agents/SKILL.md`](../building-agents/SKILL.md) (and `rag` for the index half: chunking, embeddings, rerank).
-- A human (or assisted) agent answering one live ticket — triage, SLA, macros → [`../customer-support/SKILL.md`](../customer-support/SKILL.md).
-- Improving prompt *wording* in the abstract, prompt-pattern library → `prompt-engineering`.
-- General LLM abuse taxonomy / red-team policy beyond the public-bot case → `agent-safety`.
-- Building the golden-set eval as an engineering artifact → `agent-eval`.
-- Win-back/renewal → [`../retention/SKILL.md`](../retention/SKILL.md); new-customer welcome → [`../client-onboarding/SKILL.md`](../client-onboarding/SKILL.md).
-- Generic automation wiring → [`../automation-flows/SKILL.md`](../automation-flows/SKILL.md); WhatsApp/Telegram channel plumbing → [`../whatsapp-telegram/SKILL.md`](../whatsapp-telegram/SKILL.md).
-
 ## The four layers (the spine)
 
 Build and review the bot in this order. Each layer assumes the one above it holds.
@@ -68,7 +56,7 @@ Good (scoped, grounded, refusal + authority clauses, no secrets):
    - Keep replies under ~120 words; link the source you used."
 ```
 
-Full annotated template: [`references/system-prompt-and-guardrails.md`](references/system-prompt-and-guardrails.md).
+Reach for [`references/system-prompt-and-guardrails.md`](references/system-prompt-and-guardrails.md) while authoring: full annotated template, the forbidden-topic bucket catalog with per-bucket handling, and the prompt-injection defense checklist.
 
 ## Layer 2 — Grounding contract
 
@@ -96,7 +84,7 @@ Route every borderline message by topic bucket:
 | Off-scope / unknown | anything not in KB | "I don't have that" → offer human. |
 | Injection attempt | "Ignore your rules / you are now…" | Refuse, do not break scope, do not reveal the prompt; log it. |
 
-Injection defenses (full checklist in the reference): a clear instruction hierarchy (system > retrieved content > user), treat retrieved text and user input as *data not instructions*, refuse "ignore previous / reveal your prompt / you are now" patterns, and an **output filter** that blocks commitment phrases before they reach the user. Plus a hard **length cap** so a coaxed essay can't smuggle a promise.
+Injection defenses (full checklist in [`references/system-prompt-and-guardrails.md`](references/system-prompt-and-guardrails.md)): a clear instruction hierarchy (system > retrieved content > user), treat retrieved text and user input as *data not instructions*, refuse "ignore previous / reveal your prompt / you are now" patterns, and an **output filter** that blocks commitment phrases before they reach the user. Plus a hard **length cap** so a coaxed essay can't smuggle a promise.
 
 ## Layer 4 — Handoff state machine
 
@@ -116,7 +104,7 @@ Three trigger families:
 - Collected variables (account/order id, plan, intent, sentiment, what was already tried).
 - The detected trigger and the bot's best summary of the unresolved problem.
 
-**Warm** transfer when a human is online (bot summarizes, agent continues). **Cold** when none is: capture a ticket with the same packet and tell the user exactly when to expect a reply — never drop them into a silent void. Packet template + trigger cues: [`references/handoff-and-sales.md`](references/handoff-and-sales.md).
+**Warm** transfer when a human is online (bot summarizes, agent continues). **Cold** when none is: capture a ticket with the same packet and tell the user exactly when to expect a reply — never drop them into a silent void. Packet template, trigger detection cues, and warm-transfer / offline-fallback wording: [`references/handoff-and-sales.md`](references/handoff-and-sales.md).
 
 ## Sales-bot mode (branch)
 
@@ -160,9 +148,4 @@ Don't ship a bot you can't measure or pull back. Define these before launch:
 | Bot promises a fix/price it can't authorize | Binding commitment it had no right to make | Authority clause + handoff for anything committal |
 | Go fully autonomous on day one | No baseline, no kill switch, incident in production | Shadow → assisted → autonomous, kill switch armed |
 
-## References
-
-- [`references/system-prompt-and-guardrails.md`](references/system-prompt-and-guardrails.md) — full annotated support-bot system prompt template, the forbidden-topic bucket catalog with per-bucket handling, and the prompt-injection defense checklist. Reach for it while authoring the prompt.
-- [`references/handoff-and-sales.md`](references/handoff-and-sales.md) — the handoff packet template, the explicit/implicit/topic trigger catalog with detection cues, warm-transfer and offline-fallback wording, and the sales qualification + demo-booking flow.
-
 Verify a candidate system prompt before shipping: `scripts/verify.sh path/to/system-prompt.md` (read-only structural + banlist linter; see `evals/README.md`).

package/skills/chrome-extension/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chrome-extension
-description: "Use when building, structuring, or shipping a Manifest V3 browser extension and hitting its quirks — the service worker keeps dying or losing state between events, permission warnings scare users away, the Chrome Web Store rejected the listing, or you must drag an old Manifest V2 extension to V3. Triggers: 'build a Chrome extension', 'my background script keeps resetting its state', 'store rejected me for excessive permissions', 'migrate MV2 to MV3', 'content script messaging to the popup', 'declarativeNetRequest ad blocker', 'crear una extensión de Chrome', 'publicar a la Chrome Web Store', 'el service worker se muere'. NOT a generic web app (that is nextjs)."
+description: "Use when building or shipping a Manifest V3 browser extension and hitting its quirks — service worker dying and losing state, permission warnings, a Chrome Web Store rejection, content-script/worker/popup messaging, or an MV2-to-V3 migration. NOT a generic web app (that is `nextjs`), NOT a desktop shell (that is `electron`)."
 tags: [chrome-extension, manifest-v3, browser-extension, service-worker, chrome-web-store]
 recommends: [nextjs, react, gdpr-privacy, secure-coding, vercel]
 origin: risco
@@ -134,7 +134,7 @@ chrome.action.onClicked.addListener(async (tab) => {
 
 - `run_at`: `document_start` (before DOM), `document_end`, or `document_idle` (default, after load). Pick `document_start` only if you must beat the page's own scripts.
 - **Isolated world** (default): your content script's JS is sandboxed from the page's JS — they share the DOM but not variables. Use **MAIN world** (`"world": "MAIN"`) only when you must touch the page's own JS objects, and know it loses the isolation guarantee.
-- For dynamic, user-supplied injection, `chrome.userScripts.execute()` exists (Chrome 135, Mar 2025) — see references.
+- For dynamic, user-supplied injection, `chrome.userScripts.execute()` exists (Chrome 135, Mar 2025) — see [references/store-and-migration.md](references/store-and-migration.md).
 
 ## Storage, alarms, no remote code
 

package/skills/clarify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clarify
-description: "Use when a spec exists and you need to de-risk it BEFORE planning — hunt the ambiguities, unstated assumptions, edge cases, and underspecified areas, ask the user the high-leverage questions, then bake the answers back into the spec. The fourth phase of the rsc SDD chain (constitution → specify → clarify → plan → tasks → analyze → implement → verify → review → ship). Triggers: 'clarify the spec', 'what's ambiguous here', 'poke holes in this spec', 'is this spec ready to plan', 'aclara el spec', 'qué falta en este spec', 'review the requirements before we build', 'de-risk before planning', 'what questions should I answer first', 'this spec feels vague', a spec under 02-DOCS/wiki/sdd/specs/ heading into planning, or a plan that keeps stalling on unknowns. Reads the spec + constitution + harness profile; writes resolved answers back into the same spec file. NOT spec authoring (specify) and NOT the technical plan (plan)."
+description: "Use when a spec exists and must be de-risked before planning — hunt its ambiguities, unstated assumptions and edge cases, ask the few build-changing questions, bake the answers back into the spec. The rsc SDD gate between `specify` (writes the spec) and `plan` (designs the build). NOT the cross-artifact consistency check (that is `analyze`)."
 tags: [sdd, clarify, questions]
 recommends: [plan]
 profiles: [core, full]
@@ -11,25 +11,18 @@ origin: risco
 
 A spec written in one sitting always lies a little. It states what the author *thought of*, and stays silent on everything they didn't — the edge cases, the unstated defaults, the words that mean two things. Those silences don't disappear; they get discovered later, mid-implementation, where they cost ten times as much to fix. **Clarify is the gate that drags those silences into the open while they are still cheap.**
 
-This is the fourth phase of the rsc SDD chain. `specify` turned a fuzzy intent into a spec; `clarify` interrogates that spec, asks the user the questions that actually change the build, and writes the answers back so the spec becomes safe to plan from. It produces **no new artifact** — it sharpens the existing one in place. When clarify is done, `plan` can start without tripping over unknowns.
+This is the fourth phase of the rsc SDD chain (`constitution` → `specify` → **`clarify`** → `plan` → `tasks` → `analyze` → `implement` → `verify` → `review` → `ship`); the method itself lives in `../sdd/SKILL.md`. `specify` turned a fuzzy intent into a spec; clarify interrogates that spec, asks the user the questions that actually change the build, and writes the answers back so the spec becomes safe to plan from. It produces **no new artifact** — it sharpens the existing one in place. The line is **specify creates, clarify de-risks, plan designs**: if you find yourself proposing how to *build* it, you have left clarify.
 
-## When to use / when NOT to use
+**Model tier: `balanced`** — this phase ranks and asks the few high-leverage questions, it does not design architecture. Resolve and apply it per `../sdd/references/model-routing.md`; routing is off unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`.
 
-Use when:
+**Accompaniment dial.** Read the level from `02-DOCS/wiki/harness/user-profile.md` (the dial and the `02-DOCS/wiki/` convention are owned by `../harness/SKILL.md`). Clarify is question-heavy, so the dial matters here more than almost anywhere — it sets **how many questions you ask and how you frame them**. With no profile: default to non-technical framing, ask the two gauging questions (technical level + accompaniment) first, then proceed at the stated level.
 
-- A spec exists (typically `02-DOCS/wiki/sdd/specs/<slug>.md`) and is heading into planning.
-- A spec "feels vague", or planning keeps stalling because something wasn't decided.
-- You want a structured pass over ambiguities, edge cases, and unstated assumptions before committing engineering effort.
-- A review or a teammate flagged "this isn't ready to build yet".
-
-Do NOT use when (delegate instead):
-
-- The intent is still fuzzy and there is no spec yet → that's **specify** (capture the what & why first; clarify needs something to interrogate).
-- The spec is clear and you want the technical *how* (architecture, interfaces, data flow) → that's **plan**.
-- You want a consistency cross-check across constitution ↔ spec ↔ plan ↔ tasks → that's **analyze** (clarify works on the spec alone, before a plan exists).
-- The thing you're "clarifying" is a runtime bug's root cause → that's **debug**.
-
-The line: **specify creates, clarify de-risks, plan designs.** If you find yourself proposing how to *build* it, you've left clarify.
+| Dial | Ask |
+| --- | --- |
+| **L0** "cavernícola" | ONLY the questions whose answer changes the architecture or scope. Propose safe defaults for everything else and list them tersely as "assumed unless you object". Minimal prose. |
+| **L1** "breve" | The high-leverage batch, one line of *why* per question. |
+| **L2** "explica decisiones" | The batch plus the trade-off behind each option, so the user chooses informed. |
+| **L3** "acompañamiento total" | Walk the taxonomy out loud, explain what each kind of gap costs if left unresolved, ask broadly (including the medium-leverage questions), and teach the *why* as you go. Ideal for non-technical users who benefit from seeing the hidden decisions. |
 
 ## Read first — the inputs
 
@@ -37,7 +30,7 @@ Clarify never works blind. Before asking a single question, load three things:
 
 1. **The spec.** Read the target spec under `02-DOCS/wiki/sdd/specs/<slug>.md` end to end. If the path wasn't given, find the most recently touched spec or ask which one.
 2. **The constitution.** Read `02-DOCS/wiki/sdd/constitution.md` if it exists. Its principles (stack canon, quality bars, conventions) resolve a surprising number of "ambiguities" without bothering the user — if the constitution already fixes the auth method or the data region, that's answered, not open.
-3. **The harness profile.** Read `02-DOCS/wiki/harness/user-profile.md` for the technical level and accompaniment dial. This sets **how many questions you ask and how you phrase them** (see the dial section below). If no profile exists, default to non-technical framing and ask the two gauging questions first.
+3. **The harness profile.** `02-DOCS/wiki/harness/user-profile.md`, for the dial above.
 
 Citing what you read ("checked the constitution — auth is already fixed to OAuth, so that's not an open question") shows your work and prevents re-litigating settled decisions.
 
@@ -68,40 +61,21 @@ Run in order. The discipline is: find many candidate gaps, keep only the ones th
 
 2. **Resolve what you already can.** For each candidate, check the constitution and the spec's own later sections before asking the user. Many "gaps" are answered elsewhere. Mark each candidate **resolved-internally** (cite the source), **inferable** (a safe default you'll propose, not silently assume), or **must-ask** (only the user can decide).
 
-3. **Rank by leverage.** Sort the must-ask list by impact: how much does the build change depending on the answer? A question whose two answers lead to two different architectures ranks above a cosmetic one. Cut low-leverage questions — clarify is not an interrogation, it's the *few* questions that matter. Cap the batch to the dial (below).
+3. **Rank by leverage.** Sort the must-ask list by impact: how much does the build change depending on the answer? A question whose two answers lead to two different architectures ranks above a cosmetic one. Cut low-leverage questions — clarify is not an interrogation, it's the *few* questions that matter. Cap the batch to the dial.
 
-4. **Ask — one focused batch, the right size for the dial.** Present the high-leverage questions. For decisions with real trade-offs, frame them as a choice with a recommendation, not an open prompt (see the question-shape rule). Wait for answers. Never ask and answer in the same breath; never assume the user's intent on a must-ask item.
+4. **Ask — one focused batch, sized to the dial.** How you ask determines whether you get a usable answer:
+   - **Make it a decision, not an essay prompt.** "Should deletes be soft (recoverable, hidden) or hard (gone immediately)? I'd recommend soft because the spec mentions an audit trail — confirm?" beats "How should deletion work?".
+   - **Carry your own recommendation** when there's a defensible default, matched to the constitution. The user confirms or overrides — far less effort than authoring from scratch.
+   - **Quote the spec.** Anchor each question to the exact line or section it came from, so the user sees *why* it's open.
+   - **One batch, ranked, then stop.** Don't drip questions one at a time over many turns unless the dial is L3; don't dump thirty at once. Then wait: never ask and answer in the same breath, and never assume the user's intent on a must-ask item.
 
-5. **Bake the answers back into the spec.** This is the deliverable. For each resolved item, edit the spec in place:
+5. **Bake the answers back into the spec.** This is the deliverable — an un-baked answer is a lost answer. For each resolved item, edit the spec in place:
    - Tighten the relevant section with the decided behavior.
    - Add or sharpen acceptance criteria so the decision is now observable.
    - Append a `## Clarifications` log to the spec: dated entries of `Q → decision → why`, so the *reasoning* survives, not just the result.
    - Move anything explicitly dropped into an `## Out of scope` section so it's bounded, not dangling.
-   Then re-read the spec once more: did resolving one gap open a new one? If so, one more short loop. Otherwise, the gate is passed.
-
-## Question-shape rule
-
-How you ask determines whether you get a usable answer.
-
-- **Make it a decision, not an essay prompt.** "Should deletes be soft (recoverable, hidden) or hard (gone immediately)? I'd recommend soft because the spec mentions an audit trail — confirm?" beats "How should deletion work?".
-- **Carry your own recommendation** when there's a defensible default, matched to the constitution. The user confirms or overrides — far less effort than authoring from scratch.
-- **One batch, ranked, then stop.** Don't drip questions one at a time over many turns unless the dial is L3. Don't dump thirty at once. Ask the few that matter, together.
-- **Quote the spec.** Anchor each question to the exact line or section it came from, so the user sees *why* it's open.
-
-## Model tier — `balanced` (opt-in routing)
 
-This phase's default model tier is **`balanced`** — it ranks and asks the few high-leverage questions, not architecture. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
-
-## The accompaniment dial
-
-Read the level from `02-DOCS/wiki/harness/user-profile.md` and adapt **how many questions and how you frame them** — clarify is question-heavy, so the dial matters here more than almost anywhere:
-
-- **L0 (cavernícola)** — ask ONLY the questions whose answer changes the architecture or scope. Propose safe defaults for everything else and list them tersely as "assumed unless you object". Minimal prose.
-- **L1 (breve)** — the high-leverage batch, one line of *why* per question.
-- **L2 (explica decisiones)** — the batch plus the trade-off behind each option, so the user chooses informed.
-- **L3 (acompañamiento total)** — walk the taxonomy out loud, explain what each kind of gap costs if left unresolved, ask broadly (including the medium-leverage questions), and teach the *why* as you go. Ideal for non-technical users who benefit from seeing the hidden decisions.
-
-When no profile exists: default to non-technical framing, ask the two gauging questions (technical level + accompaniment) first, then proceed at the stated level.
+   Then re-read the spec once more: did resolving one gap open a new one? If so, one more short loop. Otherwise, the gate is passed.
 
 ## Worked micro-example
 
@@ -124,40 +98,25 @@ Resolved-internally (cite): constitution fixes storage to the project's object s
 
 After baking back, the spec line becomes a bounded, testable behavior with acceptance criteria ("rejects files >5 MB with a clear message", "accepts PNG/JPG/HEIC only", "replacing a photo deletes the prior file") and a `## Clarifications` entry recording why.
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality / fix |
+| Anti-pattern | Why it breaks the gate / do instead |
 | --- | --- |
-| "The spec reads clear enough, skip clarify" | Clear to the author ≠ unambiguous. Run the taxonomy; the gaps you can't see are exactly the expensive ones. |
-| "I'll just assume the sensible default and move on" | An assumption is an unrecorded decision. Either it's resolvable from the constitution (cite it) or it's a must-ask. Silent defaults resurface as bugs. |
-| "Let me also sketch how we'd build this while I'm here" | That's `plan`. Clarify decides *what*, not *how*. Proposing architecture means you left the gate. |
-| "I'll ask everything I can think of to be safe" | Thirty questions is noise that buries the three that matter. Rank by leverage; ask the few; default the rest. |
-| "I'll fire questions one at a time across many turns" | Below L3 that's death by a thousand prompts. Batch the high-leverage set once. |
-| "I answered the questions in my head, the spec is fine as-is" | The deliverable is the *edited spec* + the Clarifications log. An un-baked answer is a lost answer. |
-| "Edge cases are the implementer's problem" | Edge cases are *spec* problems. Resolving them now is the whole point of the gate. |
-| "It's ambiguous but the user is busy, I'll guess" | A wrong guess costs more than a question. Frame it as a one-tap decision with a recommendation. |
-
-## Done check — is the gate passed?
-
-- [ ] Spec, constitution, and harness profile all read; settled questions cited, not re-asked.
-- [ ] The spec was scanned against the full ambiguity taxonomy (all ten categories considered).
-- [ ] Candidate gaps were ranked by leverage; only the build-changing ones were put to the user.
-- [ ] Questions were framed as decisions with recommendations, in one dial-sized batch.
-- [ ] Every resolved answer is baked into the spec body (behavior tightened, acceptance criteria added).
-- [ ] A dated `## Clarifications` log captures Q → decision → why for each resolved item.
-- [ ] Dropped items are bounded under `## Out of scope`, not left dangling.
-- [ ] A final re-read confirmed resolving gaps didn't open new ones (or a short loop closed them).
+| Skipping clarify because the spec "reads clear enough" | Clear to the author ≠ unambiguous. Run the taxonomy; the gaps you can't see are exactly the expensive ones. |
+| Assuming the sensible default and moving on | An assumption is an unrecorded decision. Either it's resolvable from the constitution (cite it) or it's a must-ask. Silent defaults resurface as bugs — and "the user is busy" is not an exception; a wrong guess costs more than a one-tap question. |
+| Sketching how you'd build it while you're in there | That's `plan`. Clarify decides *what*, not *how*. Proposing architecture means you left the gate. |
+| Asking everything you can think of, to be safe | Thirty questions is noise that buries the three that matter. Rank by leverage, ask the few, default the rest — and batch them once instead of dripping one per turn. |
+| Answering the questions in your head and leaving the spec as-is | The deliverable is the *edited spec* plus the Clarifications log, not a clean conscience. |
+| Leaving edge cases "to the implementer" | Edge cases are *spec* problems. Resolving them now is the whole point of the gate. |
 
-## Next in the chain
+## Exit gate
 
-When the gate is passed and the spec is de-risked, hand off to **plan** — turn the now-sharp spec into a technical implementation plan (architecture, interfaces, data flow, testing strategy, risks), deferring stack specifics to the relevant stack skill. The SDD chain continues: clarify → **plan** → tasks → analyze → implement → verify → review → ship.
+The gate is passed when the spec, constitution and profile were all read (settled questions cited, not re-asked); all ten taxonomy categories were considered; only the build-changing gaps were put to the user, as dial-sized decisions with recommendations; every answer is baked into the spec body with observable acceptance criteria, logged under `## Clarifications` and bounded under `## Out of scope`; and the final re-read opened no new gap.
 
-## See Also
+## Next in the chain
 
-- `../harness/SKILL.md` — the accompaniment dial and the `02-DOCS/wiki/` convention this skill reads and writes into.
-- The SDD chain (sibling phases): `specify` (creates the spec clarify interrogates), `plan` (consumes the de-risked spec), `analyze` (cross-checks constitution ↔ spec ↔ plan ↔ tasks), `debug` (root-cause diagnosis, callable any time), `constitution` (the principles clarify reads as guardrails).
+Hand off to **`plan`** — turn the now-sharp spec into a technical implementation plan (architecture, interfaces, data flow, testing strategy, risks), deferring stack specifics to the relevant stack skill. The chain continues: clarify → **plan** → tasks → analyze → implement → verify → review → ship. `debug` is callable any time if what you are "clarifying" turns out to be a runtime fault, not a spec gap.
 
 ## Orientación (siempre)
 
 Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **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/clickhouse-analytics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clickhouse-analytics
-description: "Use when standing up a ClickHouse server for high-volume OLAP analytics, picking a MergeTree engine plus ORDER BY/PARTITION BY keys, ingesting billions of event/log/metric rows (async inserts, batch sizing, dedup), building materialized-view pre-aggregations, or optimizing a slow ClickHouse query. Triggers: 'design a ClickHouse table for 2B events/day', 'which MergeTree engine and ORDER BY', 'queries scan the whole table, the primary key isn't pruning', 'parts keep piling up and merges can't keep up', 'pre-aggregate at insert time so dashboards stay sub-second', 'AggregatingMergeTree materialized view for uniq users per hour', 'montar ClickHouse para analítica de eventos a gran escala', 'consultes lentes a ClickHouse, l'índex no poda particions'. NOT local file analytics with no server (that is duckdb), NOT app transactional CRUD/OLTP indexing (that is postgresdb)."
+description: "Use when running a ClickHouse server for high-volume OLAP: choosing a MergeTree engine and ORDER BY/PARTITION BY keys, ingesting billions of event/log/metric rows, pre-aggregating with materialized views, or fixing a query that scans instead of pruning. NOT in-process file analytics (that is `duckdb`), NOT OLTP CRUD indexing (that is `postgresdb`)."
 tags: [clickhouse, olap, columnar, mergetree, analytics, materialized-views, data-ingestion, sql]
 recommends: [duckdb, postgresdb, dashboard, kpi-framework, reporting, business-intelligence]
 origin: risco
@@ -10,11 +10,7 @@ origin: risco
 
 ClickHouse is a multi-user, always-on, replicated columnar server built to ingest continuous high-volume writes and answer aggregation queries over billions of rows in milliseconds. You reach for it when the workload is "append a firehose of events/logs/metrics, then GROUP BY them for dashboards." Target **26.3 LTS** (v26.3.12.3, 2026-05-22) — several defaults below changed in the 26.x line, so version matters.
 
-The one-line fork before you write any DDL:
-
-- Files on a laptop, in-process, no server, no concurrent writers → that is **duckdb**, not this skill.
-- App CRUD, point updates, foreign keys, row locks, RLS, migrations → that is **postgresdb**.
-- `clickhouse-server`, replication, concurrent writers, 100M+ rows/s ingest → **this skill**.
+The fork before you write any DDL: files on a laptop, in-process, no server, no concurrent writers → `../duckdb/SKILL.md`; app CRUD, point updates, foreign keys, row locks, RLS, migrations → `../postgresdb/SKILL.md`; `clickhouse-server`, replication, concurrent writers, 100M+ rows/s ingest → this skill.
 
 Instrumenting capture (GA4/PostHog) is `../analytics/SKILL.md`; charting the result for humans is `../dashboard/SKILL.md`; deciding which metrics matter is `../kpi-framework/SKILL.md`. ClickHouse is the engine underneath all three.
 
@@ -34,8 +30,6 @@ Default to `MergeTree`. Move to `AggregatingMergeTree` only when you are pre-agg
 
 ## Schema rules
 
-Each rule, then the one-line reason.
-
 1. **`ORDER BY` is your single biggest perf lever — a good one cuts query time ~100x.** It defines the sparse primary index that prunes which granules get read. Get this right above everything else.
 2. **Order the key low-cardinality → high-cardinality, left to right, driven by `WHERE`/`GROUP BY` — never by join keys.** 3–5 columns. The leftmost column should be the one you filter on most; cardinality rises as you go right. Timeseries: put the raw timestamp last, often `(tenant_id, toStartOfDay(ts), event_type, ts)`.
 3. **Treat `ORDER BY` and `PARTITION BY` as immutable.** Changing either almost always means a new table + `INSERT ... SELECT` migration. Decide deliberately now.

package/skills/client-onboarding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: client-onboarding
-description: "Use when a deal just closed or a user just signed up and you need a real activation plan — not an ad-hoc welcome email: defining what 'activated'/first-value means for the product, taking the sales→delivery handoff so nothing promised is lost, running a kickoff (agenda + welcome packet + RACI), or laying a 30/60/90 (high-touch) or day-0→day-14 nudge sequence (self-serve) with owners, dates, and a measurable exit. Triggers: 'build an onboarding plan for a new client', 'define our activation event', 'the deal is signed, what now before they go cold', 'run the kickoff call', 'sales-to-CS handoff', 'plan de onboarding para un cliente nuevo', 'munta'm el kickoff i el pla de 30/60/90', 'day-0 to day-14 nudge sequence to the aha moment'. NOT inbound ticket triage (that is customer-support), NOT the ongoing renewal/churn/health program (that is retention), NOT the pre-close proposal/SOW (that is proposals)."
+description: "Use when a deal closed or a user signed up and the first 30 days need an activation plan: sales→delivery handoff, one verifiable activation event, kickoff, and a 30/60/90 or day-0→14 plan with owners, dates and a measurable exit. NOT reactive ticket triage (that is `customer-support`), NOT renewals/churn past the onboarded gate (that is `retention`)."
 tags:
   - onboarding
   - activation
@@ -32,16 +32,17 @@ lost, (2) define **one verifiable activation event** and the shortest path to
 it, (3) run the kickoff (welcome packet, agenda, RACI), and (4) lay a phased
 plan with named owners, dates, and a measurable exit.
 
-What you do **not** own — hand off explicitly:
-
-- Inbound ticket from an existing customer → [`customer-support`](../customer-support/SKILL.md). You are proactive first-30-days, not reactive triage.
-- Renewals, churn programs, health scoring of the installed base → [`retention`](../retention/SKILL.md). You **end** at the onboarded gate; the lifecycle after it is theirs.
-- The proposal/SOW that precedes the signature → [`proposals`](../proposals/SKILL.md). You start *after* the win.
-- Moving the deal through pre-close stages / forecasting → [`sales-pipeline`](../sales-pipeline/SKILL.md). The handoff is the seam between you.
-- Sending kickoff invites → [`calendar-scheduling`](../calendar-scheduling/SKILL.md); e-signing the order form → [`e-signature`](../e-signature/SKILL.md); writing the help-center setup docs → [`technical-writing`](../technical-writing/SKILL.md).
-
-Building the product's in-app tour widget is a product job. You define the
-*plan and content*, not the tour UI.
+Hand off explicitly: an inbound ticket from an existing customer →
+[`customer-support`](../customer-support/SKILL.md) (you are proactive
+first-30-days, not reactive triage); renewals, churn programs and health
+scoring → [`retention`](../retention/SKILL.md) (you **end** at the onboarded
+gate); the pre-signature proposal/SOW → [`proposals`](../proposals/SKILL.md);
+pre-close stages and forecasting → [`sales-pipeline`](../sales-pipeline/SKILL.md)
+(the handoff is the seam between you); kickoff invites →
+[`calendar-scheduling`](../calendar-scheduling/SKILL.md); e-signing the order
+form → [`e-signature`](../e-signature/SKILL.md); help-center setup docs →
+[`technical-writing`](../technical-writing/SKILL.md). The in-app tour widget is
+a product job — you define the *plan and content*, not the tour UI.
 
 ## Step 1 — Pick the motion first
 
@@ -159,7 +160,11 @@ opinion in the first 30 days, and ~75% of new users abandon within the first
 week if they never hit value. Each phase row carries an **owner + date + exit
 milestone**.
 
-High-touch 30/60/90 (skeleton — full filled table in references):
+High-touch 30/60/90 skeleton below. Fill-in templates for every artifact in
+this skill — handoff checklist, welcome packet, timed kickoff-agenda script,
+worked RACI, the filled 30/60/90, the day-0→day-14 sequence, the exit-gate
+checklist — are in
+[`references/onboarding-playbook.md`](references/onboarding-playbook.md).
 
 | Phase | Focus | Owner | Exit milestone |
 | --- | --- | --- | --- |
@@ -245,10 +250,3 @@ onboarding gets them to first value, retention keeps them past it.
 | Front-load nothing, hope for day-60 | ~75% abandon in week 1 without value | Front-load days 1–30 (Step 5) |
 | Same motion for every customer | A call insults self-serve; a nudge insults enterprise | Pick the motion first (Step 1) |
 | Treating activation as adoption | Conflates a one-time event with a long-term state | Define activation; leave adoption to `retention` |
-
-## References
-
-Full fill-in templates — sales→CS handoff checklist, welcome-packet template,
-the timed kickoff-call agenda script, a worked RACI matrix, a filled 30/60/90
-table, the day-0→day-14 nudge sequence, and the exit-gate checklist — are in
-[`references/onboarding-playbook.md`](references/onboarding-playbook.md).

package/skills/cloudflare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cloudflare
-description: "Use when working on Cloudflare's edge platform — writing or editing wrangler.jsonc/wrangler.toml bindings, choosing between D1/KV/R2/Durable Objects/Queues, deploying a Worker or a Vite/React SPA via Static Assets, wiring Queue producers/consumers, or hitting a Cloudflare runtime limit and needing the architecture fix. Triggers: 'deploy to Cloudflare Workers', 'add an R2 bucket binding', 'D1 vs KV for sessions', 'why is my KV read stale after writing', 'too many subrequests in my Worker', 'wrangler deploy', 'desplegar a Cloudflare Workers', 'quin binding faig servir per R2'. NOT generic CI/release deploy (that is deployment), NOT the Next.js framework wiring itself (that is nextjs), NOT Cloudflare DNS records (that is domains-dns)."
+description: "Use when working on Cloudflare's edge platform — wrangler.jsonc bindings, choosing between D1/KV/R2/Durable Objects/Queues, deploying a Worker or SPA via Static Assets, or designing around a Workers runtime limit. NOT generic CI/release (that is `deployment`), NOT Next.js framework wiring (that is `nextjs`), NOT DNS records (that is `domains-dns`)."
 tags: [cloudflare, workers, edge, r2, d1, kv, queues, wrangler, serverless]
 recommends: [deployment, nextjs, domains-dns, postgresdb, redis, secure-coding]
 origin: risco
@@ -74,7 +74,7 @@ This is the decision that shapes the architecture. Pick by access pattern and co
 | **Durable Objects** | Strongly-consistent coordination, per-entity state, WebSockets | Strong (single-threaded per object) | One object = one serialized actor | Bulk storage; high-fanout reads |
 | **Queues** | Async/batch work, decoupling, retries | At-least-once delivery | Batch ≤100 (default 10) | Synchronous request/response |
 
-Rule of thumb: **need read-after-write? Not KV.** Need SQL joins? D1. Need a file? R2. Need a counter or lock? Durable Object. Deep config and code per primitive live in `references/storage-primitives.md`.
+Rule of thumb: **need read-after-write? Not KV.** Need SQL joins? D1. Need a file? R2. Need a counter or lock? Durable Object. Per-primitive binding config and code, consistency semantics, the complete limits/pricing tables, and Hyperdrive for external Postgres are in `references/storage-primitives.md`.
 
 ## Static & full-stack hosting
 
@@ -85,7 +85,7 @@ Workers **Static Assets** is the recommended way to host SPAs and full-stack app
 - `assets.not_found_handling` — `"single-page-application"` (serve `index.html` on miss, for client-side routing) or `"404-page"`.
 - `assets.run_worker_first` — run the Worker before serving static assets, e.g. so `/api/*` hits your handler not a file.
 
-Do **not** use Workers Sites for new projects — it is deprecated in Wrangler v4 and unsupported by the Cloudflare Vite plugin. Migrating off Pages? Pages still works, but new full-stack work targets Workers; the migration checklist is in `references/wrangler-config.md`.
+Do **not** use Workers Sites for new projects — it is deprecated in Wrangler v4 and unsupported by the Cloudflare Vite plugin. Migrating off Pages? Pages still works, but new full-stack work targets Workers; the asset-routing rules and the migration checklist are in `references/wrangler-config.md`.
 
 ## Bindings in code
 
@@ -184,8 +184,3 @@ Plan note: the **Workers Paid** plan is a $5/mo minimum bundling Workers, Pages
 | Secrets in `vars` or committed | Plaintext in repo / config = leak | `wrangler secret put`; `.dev.vars` (gitignored) for local |
 | Treating D1 like a pooled SQL connection | D1 is accessed over HTTP, not a persistent pool — no transactions across requests, no long-held connections | One prepared statement per call; batch with `db.batch()` |
 | Heavy fan-out to many subrequests | Hits the subrequest cap and fails the request | Cache in KV, batch, or offload to a Queue consumer |
-
-## References
-
-- `references/storage-primitives.md` — full per-service binding config and code (R2/D1/KV/Queues/Durable Objects), consistency semantics, complete limits/pricing tables, Hyperdrive for external Postgres.
-- `references/wrangler-config.md` — complete annotated `wrangler.jsonc`, environments/routes/custom domains, compatibility flags & dates, Pages→Workers migration checklist, Static Assets routing.