@ericrisco/rsc 0.1.44 → 0.1.46

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.

package/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: "Use when you have a concrete diff, branch, or GitHub PR to judge on its own merits and there is no rsc-SDD spec/plan/constitution chain to key off — the standalone, spec-less giving pass behind the executable /code-review. Triggers: 'review this PR before I merge', 'revisa este diff', 'revísame el PR', 'què està malament en aquest canvi', 'tear apart the contractor's branch', 'is this PR safe to merge', 'is this dependency bump safe', '/code-review --comment 1432', 'high-signal review of this change'. Scales coverage by effort (low/medium = fewer high-confidence findings; high/max = broader, may surface uncertain ones labelled [question]); read-only by default, posts comments only with --comment and edits only with --fix. NOT the SDD review gate keyed to 02-DOCS/wiki/sdd/ that also processes incoming comments and pushes back (that is review)."
+description: "Use to judge a concrete diff, branch, or GitHub PR on its own merits with no rsc-SDD spec/plan chain to key off — the spec-less giving pass behind /code-review: only findings you can defend, one verdict, read-only unless --comment or --fix. NOT the SDD gate keyed to 02-DOCS/wiki/sdd/ that also processes incoming review comments (that is `review`)."
 tags: [code-review, pr-review, quality, correctness]
 recommends: [review, secure-coding, verify]
 origin: risco
@@ -8,9 +8,7 @@ origin: risco
 
 # Code review — standalone, spec-less diff judgment
 
-You are reviewing a concrete change — a `git diff`, a branch, a GitHub PR, a pasted patch — on its own merits. No rsc-SDD spec/plan/constitution chain is required and you should not pretend one exists. This is the doctrine behind the executable `/code-review` slash command: same evidence bar, written as a discipline you run by hand.
-
-> **The one-line disambiguator:** `review` needs `02-DOCS/wiki/sdd/` (spec + plan + constitution) and owns the *receiving* loop. `code-review` needs only the diff. If the user is mid-SDD and wants to process incoming comments, route to `../review/SKILL.md`. If they hand you a naked diff or an inbound third-party PR, this skill.
+You are reviewing a concrete change — a `git diff`, a branch, a GitHub PR, a pasted patch — on its own merits. No rsc-SDD spec/plan/constitution chain is required and you should not pretend one exists. This is the doctrine behind the executable `/code-review` slash command: same evidence bar, written as a discipline you run by hand. If the user is mid-SDD and wants to process *incoming* comments against `02-DOCS/wiki/sdd/`, that is `../review/SKILL.md`; a naked diff or an inbound third-party PR is this skill.
 
 **The north star is signal-to-noise.** Report only findings you would stake your name on. A clean diff is `APPROVE`, not a manufactured nit. High-false-positive review gets tuned out by humans in about two weeks; the bar to aim for is the logic-error review where under 1% of findings come back marked wrong. Padding does not make you look thorough — it trains the reader to ignore you.
 
@@ -30,7 +28,7 @@ git diff --stat main...HEAD   # see blast radius before reading
 # A pasted patch — read it as given
 ```
 
-A review with no notion of intent is a review of vibes. If no purpose is stated, **infer it from the diff and say what you assumed** ("Assuming this is meant to add idempotency to the webhook handler…") so the reader can correct a wrong premise. Then read the *whole* changed file, not just the green/red lines — the structural failure of standalone review is judging a hunk without its context and shipping generic pattern-matched suggestions.
+A review with no notion of intent is a review of vibes. If no purpose is stated, **infer it from the diff and say what you assumed** ("Assuming this is meant to add idempotency to the webhook handler…") so the reader can correct a wrong premise — a silent wrong premise produces a confidently wrong review. Then read the *whole* changed file, not just the green/red lines: the structural failure of standalone review is judging a hunk without its context and shipping generic pattern-matched suggestions.
 
 ## The pass order
 
@@ -47,6 +45,8 @@ Run these in order. Passes 1–5 are correctness/safety and are blocking-eligibl
 
 Pass 4 is a **boundary** pass — trace untrusted input to its sink and flag the reachable ones. For a real STRIDE/OWASP threat model with exploitability ranking and vulnerable→fixed diffs, hand off to `../secure-coding/SKILL.md`.
 
+Adjacent jobs, delegated by name: running the lint/type/test gates until they are green is `../verify/SKILL.md` (this skill judges whether green is *correct*); root-causing one confirmed failure is `../debug/SKILL.md`; cross-checking spec/plan/tasks *before* code exists is `../analyze/SKILL.md`.
+
 ## Confidence floor and the false-positive skip-list
 
 **The 80% rule:** if you are not at least ~80% sure a finding is real, you have two moves — trace the code until you *are* sure, or downgrade it to `[question]`. Never ship a guess dressed as a defect.
@@ -103,7 +103,7 @@ End every review with exactly one, plainly — no mushy middle:
 
 ## Effort dial
 
-Mirror the slash command's effort level: **low/medium** → fewer, high-confidence findings (raise the confidence floor, focus on passes 1–4). **high/max** → broader coverage; you may surface uncertain findings, but they must be labelled `[question]`, never inflated into blockers. This is *coverage vs precision* and is distinct from the harness L0..L3 accompaniment dial, which sets how much you narrate, not how rigorous you are.
+Mirror the slash command's effort level: **low/medium** → fewer, high-confidence findings (raise the confidence floor, focus on passes 1–4). **high/max** → broader coverage; uncertain findings are allowed but must be labelled `[question]`, never inflated into blockers. This is *coverage vs precision*, not the harness accompaniment dial — it changes what you look at, not how much you narrate.
 
 ## Emitting comments and applying fixes
 
@@ -120,24 +120,11 @@ gh pr review 1432 --approve -b "APPROVE — correctness and contracts clean."
 
 Inline line-anchored comments go through the GitHub REST API — see `references/pr-workflow.md` for the JSON shape, fork-PR handling, and large-diff strategy. If `--fix` puts you on the default branch, **branch first**; commit or push **only when the user asks**; git authorship is **Eric** (no Claude co-author or generated footer).
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality |
+| Failure mode | Reality |
 |---|---|
 | "It compiles and the tests pass, so it's correct." | Tests prove green, not correct. Pass 5 asks whether the tests actually exercise the new branch — green for the wrong reason is a finding. |
-| "I'll list everything I'd have done differently." | That is noise. Report defects and reuse wins you can defend; preference is not a finding. |
-| "This looks like a bug." | Looks-like is not a finding. Trace the value to a reachable sink, or file it `[question]`. |
-| "More findings = more thorough." | False positives get you tuned out in two weeks. Signal-to-noise is the metric; one real blocker beats ten nits. |
-| "No PR description, so I'll guess the intent silently." | State the intent you assumed. A wrong silent premise produces a confidently wrong review. |
+| Listing everything you would have done differently. | That is noise. Report defects and reuse wins you can defend; preference is not a finding. |
 | "It's just a dependency bump, skim it." | Bumps carry supply-chain and transitive risk and behaviour changes. Check the changelog/lockfile diff, not just the version string. |
-| "Apply every nit to be safe." | Each unrequested edit is scope creep and a regression surface. With `--fix`, apply the agreed findings only. |
-
-## See Also
-
-- `../review/SKILL.md` — the rsc-SDD penultimate gate keyed to `02-DOCS/wiki/sdd/`, and the *receiving* loop (process comments, push back with proof).
-- `../secure-coding/SKILL.md` — deep STRIDE/OWASP threat model with vulnerable→fixed diffs; the depth pass 4 defers to.
-- `../verify/SKILL.md` — run lint/type/test/`verify.sh` and prove green (code-review judges whether green is correct).
-- `../debug/SKILL.md` — root-cause one confirmed failure (code-review surveys for latent ones).
-- `../analyze/SKILL.md` — consistency across spec/plan/tasks *before* code exists.
-- `../ship/SKILL.md` — PR/merge/close after approval; consumes this skill's verdict.
-- Stack idiom for the change under review: `../nextjs/SKILL.md`, `../fastapi/SKILL.md`, `../go/SKILL.md`, `../typescript/SKILL.md`, `../python/SKILL.md`.
+| Applying every nit "to be safe" under `--fix`. | Each unrequested edit is scope creep and a regression surface. Apply the agreed findings only. |

package/skills/codebase-onboarding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-onboarding
-description: "Use when you land in an unfamiliar or inherited codebase and must get productive fast — map the entry points, the request/data flow, who owns the business logic, the hidden side effects (cron, webhooks, workers, listeners) and the hotspot files, before you touch anything. Triggers: 'I just cloned this repo and don't know where anything is', 'I inherited this project, map it before I change something', 'where does the business logic actually live', 'what happens behind the scenes when a request hits /checkout', 'which files are the dangerous ones nobody understands', 'acabo de heredar este repo y no sé por dónde empezar, mápamelo', 'mapea este codebase'. NOT a deep correctness/security audit of one module (that is analyze)."
+description: "Use when you land in an unfamiliar or inherited codebase and must get productive fast: a breadth-first map of entry points, request flow, module ownership, hidden side effects (cron, webhooks, workers) and churn hotspots, committed as CODEBASE-MAP.md. NOT a deep audit of one module (that is `analyze`) or chasing one failure (that is `debug`)."
 tags: [onboarding, codebase, code-mapping, legacy-code, architecture, reverse-engineering, hotspots]
 recommends: [analyze, debug, decision-records, harness, init, knowledge-ops]
 origin: risco
@@ -68,7 +68,7 @@ git log --format=format: --name-only --since=12.month \
   | grep -v '^$' | sort | uniq -c | sort -nr | head -50
 ```
 
-The richer move is **churn × complexity**: the top-right quadrant (changes constantly *and* is hard to read) is your real danger zone (understandlegacycode.com Hotspots, accessed 2026-06-02). Escalate to that — or to a tree-sitter dependency graph — only when grep + churn is not enough; see the playbook.
+The richer move is **churn × complexity**: the top-right quadrant (changes constantly *and* is hard to read) is your real danger zone (understandlegacycode.com Hotspots, accessed 2026-06-02). Escalate to that — or to a tree-sitter dependency graph — only when grep + churn is not enough: `references/recon-playbook.md` has the churn×complexity recipe (code-maat) and when codegraph PageRank / FileScopeMCP earn their setup cost.
 
 **g. Confirm hands-on.**
 Run the app, walk one end-user journey, send a real request, watch the logs. Reading alone leaves the map unverified; a single real request validates the whole trace in step c.
@@ -106,9 +106,6 @@ rg -n "queue|worker|bull|sidekiq|celery|sqs|rabbitmq|kafka|@task" -i
 
 # Env-driven branches (hidden config-conditional behavior)
 rg -n "process\.env\.|os\.environ|ENV\[|getenv" 
-
-# Hotspots: churn over the last year
-git log --format=format: --name-only --since=12.month | grep -v '^$' | sort | uniq -c | sort -nr | head -50
 ```
 
 ## Writing & maintaining the map
@@ -129,5 +126,3 @@ git log --format=format: --name-only --since=12.month | grep -v '^$' | sort | un
 | Map lives only in chat | Dies with the session; next agent redoes it | Write & commit `CODEBASE-MAP.md` |
 | Guess instead of grep | Confident-wrong is worse than slow-right | Form the hypothesis, then `rg` to confirm or kill it |
 | Stand up a tree-sitter MCP graph on a 5-file repo | Setup costs more than the whole recon | Reserve graph tools for large monorepos; grep + churn first |
-
-See `references/recon-playbook.md` for per-ecosystem entry points and side-effect patterns, the churn×complexity recipe (code-maat), and when a tree-sitter graph (codegraph PageRank, FileScopeMCP) earns its setup cost.

package/skills/cold-outreach/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cold-outreach
-description: "Use when writing a cold email or DM to someone with no prior relationship, building a follow-up sequence, deciding how fast/how much to send per inbox so it stays out of spam, or rescuing outreach that reads like a template. Covers first-touch copy under a word ceiling, 4-7 step bump sequences, email-vs-LinkedIn variants, per-inbox volume and new-domain warm-up ramps, and the CAN-SPAM/GDPR opt-out footer. Triggers: 'write me a cold email', 'fix my follow-up sequence', 'my cold emails get opened but nobody replies', 'how many emails per inbox per day before I get blacklisted', 'write a LinkedIn connection note + DM', 'this email reads like a template', 'escríbeme una secuencia de cold email en frío', 'missatge en fred a LinkedIn'. NOT the SPF/DKIM/DMARC/tracking-domain setup (that is email-deliverability), NOT sourcing the prospect list (that is lead-gen), NOT what happens after a reply (that is sales-pipeline)."
+description: "Use when writing a cold email or LinkedIn DM to a stranger and its cadence: first-touch copy under a word ceiling, 4-7 step bump sequences, per-inbox volume and warm-up limits, the compliant opt-out footer. NOT SPF/DKIM/DMARC setup (that is email-deliverability), NOT sourcing the list (that is lead-gen), NOT life after a reply (that is sales-pipeline)."
 tags: [cold-email, outreach, sequences, deliverability, sales]
 recommends: [lead-gen, sales-pipeline, email-deliverability, proposals, marketing]
 origin: risco
@@ -10,20 +10,7 @@ origin: risco
 
 *You write the message a stranger actually replies to, and the sending rhythm that keeps the mailbox provider delivering it. You do not set up DNS, source the list, or run the CRM.*
 
-This skill owns two things and only two: the **copy** of an unsolicited 1:1 touch (cold email, LinkedIn note/DM) and the **cadence** around it (step count, spacing, per-inbox volume, warm-up ramp, the compliant footer). Everything upstream and downstream belongs to a sibling — see the route table below and honor it.
-
-## When to use / When NOT
-
-Use when:
-
-- Writing a cold email or its subject line to a recipient with no prior relationship.
-- Building or fixing a multi-step follow-up sequence (the "bump" cadence) — step count and spacing.
-- Writing a LinkedIn connection note or cold DM sequence.
-- Deciding daily/weekly send volume per inbox, or a new-domain warm-up ramp.
-- Writing the CAN-SPAM/GDPR-compliant footer and one-click opt-out line.
-- Rescuing a cold email that "reads like a template" or gets opens but no replies.
-
-Do NOT use when (route to the sibling that owns it):
+This skill owns two things and only two: the **copy** of an unsolicited 1:1 touch (cold email, LinkedIn note/DM) and the **cadence** around it (step count, spacing, per-inbox volume, warm-up ramp, the compliant footer). Everything upstream and downstream belongs to a sibling — route by naming the owner, do not improvise their job:
 
 | The ask | Owner | Why it is not here |
 |---|---|---|
@@ -34,8 +21,6 @@ Do NOT use when (route to the sibling that owns it):
 | Inbound launch emails, nurture to an opted-in list, marketing-site copy | `marketing` (`../marketing/SKILL.md`) | Opted-in and broadcast copy is a different game from a 1:1 cold touch. |
 | Actually wire the send through Gmail/an ESP API or a scheduler | `email-connector` / `google-workspace` | This skill produces text + a plan; it does not push the send. |
 
-Only `marketing` exists in this catalog today, so it is the only sibling linked as a file. The rest are named by id — route by naming the owner, do not improvise their job.
-
 ## The reply-rate reality (calibrate before you write)
 
 Cold email is a low-yield channel by nature, and most "improve my copy" requests are really "stop fighting the math." Set expectations against the 2026 band:
@@ -110,7 +95,9 @@ The Good version names a real signal (`{{signal}}`), states one concrete outcome
 
 The first-touch body is literally lines 2→3→4 in order; line 1 becomes the subject. If the INFER line is generic, the email is generic no matter how many merge fields you add. **Test the INFER line in isolation: would it be false for a competitor in the same situation? If it is true of everyone, it is a platitude — go back to the OBSERVE step and pick a sharper fact.**
 
-When the user hands you only a company name and no signal, do not invent one. Ask for (or, if you have web access, look up) one of these signal classes, ranked by reply lift: a **hiring/role-change** signal > a **funding/launch/news** signal > a **tech-stack or job-description detail** > a **public number from their own site/report** > a **shared context** (mutual, group, event). A generic industry trend ("AI is changing your space") is not a signal and never clears the INFER test. Worked OBSERVE→INFER→BRIDGE→PROVE chains across six industries live in `references/hook-derivation.md`.
+Two boundaries on the OBSERVE line, because both are unrecoverable once sent: keep it **professional, public and business-relevant** ("saw you're hiring 3 SREs" is relevant; "saw you were at the lake house last weekend" is surveillance), and **never invent it** — a fabricated "I loved your recent post on X" that does not exist destroys trust on contact.
+
+When the user hands you only a company name and no signal, do not invent one. Ask for (or, if you have web access, look up) one of these signal classes, ranked by reply lift: a **hiring/role-change** signal > a **funding/launch/news** signal > a **tech-stack or job-description detail** > a **public number from their own site/report** > a **shared context** (mutual, group, event). A generic industry trend ("AI is changing your space") is not a signal and never clears the INFER test. If no true signal exists at all, that is a `lead-gen` targeting gap, not a copy task. Worked OBSERVE→INFER→BRIDGE→PROVE chains across six industries live in `references/hook-derivation.md`.
 
 ## The sequence — decision table
 
@@ -144,7 +131,9 @@ Rules that make the table work:
 
 *(LinkedIn figures: Skylead / Kondo / Expandi 2025-2026 guides, accessed 2026-06-02.)*
 
-On LinkedIn the connection note must **not** pitch — earn the connection on a real signal, then make the ask in the first DM after they accept. Skeletons for both channels live in `references/templates.md`.
+On LinkedIn the connection note must **not** pitch — earn the connection on a real signal, then make the ask in the first DM after they accept.
+
+Reusable skeletons for both channels — first-touch + 4-step bump, with every variable slot (`{{signal}}`, `{{outcome}}`, `{{proof}}`) marked — live in `references/templates.md`. Start from a skeleton, then fill every slot with a *real* value before sending. An unfilled slot is a defect, not a placeholder to ship.
 
 ## Sending cadence & deliverability guardrails
 
@@ -179,12 +168,6 @@ If the user asks you to *configure* the `List-Unsubscribe` header, SPF, or DKIM,
 
 EU enforcement varies — UK ICO and France CNIL are permissive for B2B; Germany and Poland are stricter (Poland often requires prior consent). When the recipient is in the EU, write the footer for the strictest plausible jurisdiction. The full footer wording, the LIA checklist, and the CASL/Australia matrix → `references/compliance-footer.md`.
 
-## Personalization without creepiness
-
-- **One real signal, surfaced plainly.** "Saw you're hiring 3 SREs" is relevant; "Saw you were at the lake house last weekend" is surveillance. Stay on professional, public, business-relevant signals. Then run it through the four-line bridge above — a relevant signal with a generic INFER line still reads like a template.
-- **Do not fake personalization with spintax.** Rotating "{Hi|Hey|Hello}" or `{{first_name}}`-only mail-merge is not personalization — it is a template wearing a name tag, and recipients can smell it. If the only variable is the name, the email is generic; add a real `{{signal}}` or do not send.
-- **Never invent the signal.** A fabricated "I loved your recent post on X" that does not exist destroys trust on contact. If you cannot find a true signal, that is a `lead-gen` targeting gap, not a copy task.
-
 ## Anti-patterns
 
 | Anti-pattern | Why it fails | Do instead |
@@ -193,14 +176,10 @@ EU enforcement varies — UK ICO and France CNIL are permissive for B2B; Germany
 | Pitch in sentence one | No earned relevance; reads like a billboard | Lead with the observed signal, earn the ask |
 | Two CTAs ("call OR I'll send a guide") | Splits the decision; lowers reply rate | One binary yes/no ask per email |
 | "Just following up" / "circling back" with no new angle | Adds noise, not value; trains them to ignore you | Each step adds one new angle or it is deleted |
-| Name-only mail merge as "personalization" | Recipients see the template underneath | One true `{{signal}}` per first touch or do not send |
+| Name-only mail merge or spintax (`{Hi\|Hey}`) as "personalization" | Recipients see the template underneath | One true `{{signal}}` per first touch or do not send |
 | No opt-out / no postal address | CAN-SPAM/GDPR violation; complaint-rate spike | Always append the compliant footer |
 | Subject like "Quick question!!" or "FREE" | Clickbait + spam-trigger words land you in spam | ≤6 plain words that read like a coworker wrote them |
 | Padding to 7 steps for completeness | Replies past step 5 are thin; you just annoy | Stop at the breakup unless a real new trigger appears |
 | "I hope this email finds you well" opener | The classic AI/template tell; wastes the first line | Open on the signal — your first 6 words are the hook |
 
-## Templates
-
-Reusable skeletons — first-touch + 4-step bump for email and LinkedIn, with every variable slot (`{{signal}}`, `{{outcome}}`, `{{proof}}`) marked — live in `references/templates.md`. Start from a skeleton, then fill every slot with a *real* value before sending. An unfilled slot is a defect, not a placeholder to ship.
-
 To self-check a drafted email or sequence file, run `scripts/verify.sh path/to/draft.md` — it flags missing opt-out, multiple CTAs, over-ceiling word count, and spam/AI-tell phrases (read-only).

package/skills/community/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: community
-description: "Use when building or running a persistent two-way community space — Discord, Telegram, or Circle — and you need structure, onboarding, moderation, rituals, growth, or health metrics; covers picking the platform, standing up channels/roles/spaces, the rules/verification gate, the 3-layer moderation stack, an operating-rhythm of rituals, lurker-to-contributor growth loops, and the few metrics that prove it is alive. Triggers: 'set up our Discord server', 'our community is a graveyard / dead chat', 'we keep getting spam raids and scam DMs', 'Discord vs Telegram vs Circle', 'design community rituals / weekly cadence', 'how do I get lurkers to post', 'community onboarding flow', 'community health metrics', 'monta la comunitat de Discord', 'la comunidad está muerta, nadie escribe'. NOT customer churn-prevention for a paid product (that is retention), NOT one-to-many broadcast email (that is newsletter), and NOT running a single live event (that is webinar)."
+description: "Use when building or running a persistent two-way community space — Discord, Telegram, Circle: platform choice, structure, onboarding, native→bot→human moderation, rituals, growth loops, health metrics. NOT churn of paying product customers (that is `retention`), NOT broadcast email (that is `newsletter`), NOT one live event (that is `webinar`)."
 tags: [community, discord, telegram, moderation, growth, rituals]
 recommends: [retention, newsletter, social-publisher, brand-voice, whatsapp-telegram, webinar]
 profiles: []
@@ -11,15 +11,6 @@ origin: risco
 
 Run the community like a **product with a job**, not a vanity chat room. The space — a Discord server, a Telegram group+channel, a Circle — is the product. **Onboarding is activation, rituals are the feature, moderation is reliability, and one north-star metric tied to your purpose is the only number that matters.** A room with 5,000 silent members is a failed product, not a big one. Design the system around the conversation, not the conversation itself.
 
-## When to use
-
-- Standing up a new Discord / Telegram / Circle from zero: structure, roles, onboarding, rules.
-- A community exists but is a graveyard — lurkers only, no rhythm, nobody posts — needs rituals + re-activation.
-- Moderation is on fire: spam waves, raids, scam DMs, bans applied by mood, no incident process.
-- Choosing between Discord vs Telegram vs Circle for a given audience, purpose, and monetization model.
-- Designing a growth loop that compounds (referrals, intro rituals, partner cross-posts) instead of buying dead members.
-- Defining community health metrics and targets and instrumenting the few that prove the thing is alive.
-
 ## When NOT to use — route instead
 
 | The ask | Route to |
@@ -32,9 +23,9 @@ Run the community like a **product with a job**, not a vanity chat room. The spa
 | Actually code or host the Discord/Telegram bot (gateway, slash handlers) | `whatsapp-telegram`, `automation-flows` |
 | Define the voice/name/tone the community speaks in | `../brand-voice/SKILL.md` |
 
-You own the **persistent, two-way space and its ongoing operating rhythm.** The boundary that bites most: `retention` keeps *buyers of a product* from churning; you keep *members of a shared space* active and contributing. They rhyme (cohorts, re-activation) but the subject differs — a SaaS seat vs a Discord membership. When a near-miss is really "send a broadcast," it is `newsletter`/`social-publisher`; when it is "stop churn of buyers," it is `retention`; when it is "run an event," it is `webinar`.
+You own the **persistent, two-way space and its ongoing operating rhythm.** The boundary that bites most: `retention` keeps *buyers of a product* from churning; you keep *members of a shared space* active and contributing. They rhyme (cohorts, re-activation) but the subject differs — a SaaS seat vs a Discord membership.
 
-## Step 0 — Purpose & north-star gate (hard rule)
+## Step 0 — Purpose & north-star gate
 
 **Do not design a single channel until you have (a) a one-line purpose and (b) one business metric tied to it.** Why: a community without a job becomes a dead chat — there is no signal to design toward, so you sprawl channels and beg for activity. This is the most common cause of graveyards.
 
@@ -191,7 +182,7 @@ Then validate it:
 scripts/verify.sh path/to/moderation-config.yaml
 ```
 
-`verify.sh` checks the required keys exist, that `north_star_metric` is non-empty, that all three moderation layers are declared, and that at least one ritual has a cadence — it catches the most common defect (a "plan" with no purpose, no mod layers, or no rhythm).
+`verify.sh` checks the required keys exist, that `north_star_metric` is non-empty, that all three moderation layers are declared, and that at least one ritual has a cadence — it catches the most common defect (a "plan" with no purpose, no mod layers, or no rhythm). **Do not go live until it passes and the north-star plus at least one health metric (TTFR or DAU/MAU) are instrumented.**
 
 ## Anti-patterns
 
@@ -205,21 +196,3 @@ scripts/verify.sh path/to/moderation-config.yaml
 | Treating 90% lurkers as permanent | Leaves activation on the table | 90-9-1 is a range; move lurkers up a tier |
 | Monetizing on Circle before activation works | Charging for a dead room churns instantly | Prove rhythm + retention, then gate/monetize |
 | Broadcasting in a two-way space | Wrong tool; kills conversation | One-to-many → `../newsletter/SKILL.md` / `../social-publisher/SKILL.md` |
-
-## Launch-readiness checklist
-
-Gate before "go live":
-
-- [ ] Purpose written in one line **and** one north-star business metric chosen (Step 0).
-- [ ] Platform chosen by decision rule, not vibes.
-- [ ] ≤ ~6 channels/spaces, each justified by the purpose.
-- [ ] Onboarding path wired: role-on-join → rules gate → prompted intro → where-to-ask.
-- [ ] All 3 moderation layers configured (native + bot + human) sized to expected scale.
-- [ ] ≥ 1 ritual scheduled with an explicit cadence.
-- [ ] North-star + ≥ 1 health metric (TTFR or DAU/MAU) instrumented.
-- [ ] `community-plan.md` + `moderation-config.yaml` emitted and `verify.sh` passes.
-
-## References
-
-- `references/platform-playbooks.md` — per-platform setup depth: Discord (AutoMod filters, verification levels, Rules/Membership Screening, Onboarding, bots by size), Telegram (group+channel hybrid, native anti-spam >200, slow-mode, CAPTCHA bots), Circle (Spaces, 2026 plan ladder + fees, monetization gating).
-- `references/metrics-and-rituals.md` — metric definitions + benchmarks (DAU/WAU/MAU stickiness, cohort retention, TTFR, answered rate, returning-member ratio, the business-metric menu), the 90-9-1 reality, and a ritual template library + sample weekly calendar.