skill: community

should_trigger:
  - prompt: "Set up our Discord server for the SaaS user community — channels, roles, and rules."
    why: Core stand-up job — structure + onboarding + moderation for a persistent two-way space.
  - prompt: "Our Telegram group is a graveyard, nobody posts anymore. How do we revive it?"
    why: Non-obvious — no setup words, but it is a dead two-way space needing rituals + re-activation, the heart of this skill.
  - prompt: "We keep getting spam raids and scam-DM waves in our community — lock it down."
    why: Moderation / incident response (native + bot + human stack, raid runbook) is owned here.
  - prompt: "Should we run our paid membership on Circle or just use Discord?"
    why: Platform decision including monetization — the decision table routes this.
  - prompt: "La comunitat de Discord està morta, ningú escriu — com la reactivem?"
    why: Catalan phrasing for a graveyard re-activation; rituals + growth loops.
  - prompt: "How do I get the lurkers in our community to actually post something?"
    why: Lurker-to-contributor growth (90-9-1 is a range, move members up a tier) is a core job.

should_not_trigger:
  - prompt: "Our SaaS users keep cancelling in month 2 — build a win-back and churn-reduction flow."
    route_to: retention
    why: Paying-customer churn of a product, not activity in a shared member space.
  - prompt: "Write this week's broadcast email to our subscriber list."
    route_to: newsletter
    why: One-to-many opted-in email, not a two-way persistent space.
  - prompt: "Schedule and cross-post our launch announcement across X, LinkedIn, and Instagram."
    route_to: social-publisher
    why: Public-feed posting, not a community space.
  - prompt: "Run our product-launch webinar end-to-end: registration page, speakers, and replay."
    route_to: webinar
    why: A single timed live event, not a persistent two-way space.

capability:
  - scenario: "Stand up a Discord community for an indie game-dev audience whose business goal is converting free players into paying supporters."
    must_include:
      - States or extracts a one-line purpose AND one north-star business metric before designing anything (Step 0 gate).
      - Justifies Discord over Telegram and Circle for this audience using the decision rules.
      - Minimal channel set (no sprawl) + role-on-join + an onboarding "first meaningful action" path with the rules/membership gate.
      - 3-layer moderation — native AutoMod + a verification level, a bot, and human mods — sized to expected scale.
      - At least one weekly ritual with an explicit cadence.
      - Names the one business metric plus at least one health metric (e.g. TTFR or DAU/MAU ≥20% floor).
      - Emits a community-plan.md + moderation-config artifact and references scripts/verify.sh.

# Evals — community

`cases.yaml` is a judging harness, not an executable test suite. Run it with a human or an LLM judge. The `should_trigger` and `should_not_trigger` cases check routing discipline: each `should_trigger` prompt should pull in this skill (including the non-obvious "graveyard" and Catalan phrasings), and each `should_not_trigger` prompt should route to the named sibling (`retention`, `newsletter`, `social-publisher`, `webinar`) instead of here. The `capability` case is run end-to-end against a real session: give the agent the scenario and score the response against the `must_include` rubric — every bullet must be satisfied (purpose+north-star gate, platform rationale, onboarding path, 3-layer moderation, a ritual with cadence, the metrics, and the emitted artifact validated by `scripts/verify.sh`). Structural defects in the emitted `moderation-config` are caught mechanically by `scripts/verify.sh`; the rubric covers the process rigor that no script can check.

# Metrics & rituals

The health scorecard and the operating-rhythm library. Use this with the Metrics and Rituals sections of `../SKILL.md`. Facts carry source + access date.

## The metric clusters

Metrics cluster into three groups plus exactly one business metric tied to your Step-0 purpose.

### Cluster 1 — activation / retention
- **DAU / WAU / MAU** and **stickiness = DAU/MAU**. Benchmark band for social/messaging products is **~50–80%**; treat **≥ 20% as a floor** for a healthy community. Below 20% the room is decaying.
- **30 / 60 / 90-day cohort retention** — track each join-cohort's survival; it is the truest read on whether onboarding actually activates.
- **Returning-member ratio** — share of members who came back this period; the direct signal that rituals are working.

### Cluster 2 — member value
- **Time-to-first-response (TTFR)** — how long until a newcomer's first post gets a reply. Lower is better; this is the newcomer's first lived experience of the room.
- **Answered rate** — share of questions that get any answer. Drive toward 100%; unanswered questions teach members not to ask.

### Cluster 3 — exactly ONE business metric
Pick **one** that matches the purpose, and only one:
- **Support deflection** — questions answered by members vs tickets filed.
- **Retention uplift** — product retention of members vs non-members.
- **Expansion revenue** — upgrades/supporter conversions sourced from the space.
- **Qualified referrals** — warm intros / leads the community generates.

Source: Bevy *Top 11 Community Engagement Metrics for 2025*, Discourse *20 Community Metrics Explained* (2025-04), Geckoboard *DAU/MAU*, accessed 2026-06-02.

## The 90-9-1 reality

- **Participation inequality / "1% rule":** ~**90% lurk, 9% contribute occasionally, 1% drive most activity** — but this is a **range, not a law**.
- Healthier communities skew far more active: observed profiles like **55-30-15** and **17-57-26**.
- Design implication: **do not accept 90% lurkers as fixed.** Move lurkers up a tier with prompts, one-tap reactions, and direct asks.
- Source: NN/g *Participation Inequality* (Nielsen) + Higher Logic *90-9-1 … Officially Outdated*, accessed 2026-06-02.

## Ritual template library

Predictable cadence beats sporadic effort. Run each on time, every time; consistency is the whole point.

| Ritual | Cadence | Friction | What it produces |
|---|---|---|---|
| "What are you working on?" thread | Weekly (Mon) | Low — one reply | Re-engagement hook, surfaces who's active |
| Office hours / AMA | Weekly (Wed) | Medium — opt-in | High-value 1:1-in-public, answered-rate boost |
| "Wins of the week" | Weekly (Fri) | Low — a reaction counts | Positive loop, social proof |
| Monthly show-and-tell / demo day | Monthly | Medium | Deepens the 1%/9%, content for announcements |
| Onboarding "intro Tuesday" round-up | Weekly | Low | Pulls new members into threads day one |
| Poll of the week | Weekly | Very low — one tap | Cheap participation for lurkers |

### Sample weekly calendar
```text
Mon  WIP thread posted 09:00 local
Wed  Office hours 17:00–18:00 (opt-in @office-hours role)
Fri  Wins thread + react-to-celebrate
Sun  (mod) scorecard glance: TTFR, answered rate, new-member activation
```

### Low-friction participation rules
- Prefer **reactions and polls** over "write a paragraph" — every tier can participate.
- Use **opt-in role pings** for ritual reminders; never `@everyone` for routine beats (over-pinging trains mutes, and a muted member is functionally gone).
- Reserve `@everyone` for genuine all-hands moments only.

# Platform playbooks

Per-platform setup depth. Pick the platform with the decision table in `../SKILL.md`; this file is the build manual for each. Every load-bearing fact carries its source + access date.

## Discord — the real-time default

### AutoMod (native layer)
- **Keyword filters**: one **Commonly-Flagged-Words preset rule** (`KEYWORD_PRESET`: Insults & Slurs, Sexual Content, Severe Profanity), **1 per guild**, **plus up to 6 custom keyword rules** (`KEYWORD` trigger), each filter holding **up to 1,000 terms** (60 chars each). Use a custom rule for your scam-phrase blocklist and link patterns. Note: the "1,000" is the per-rule *filter* size; do not confuse it with the 100-entry cap on a `KEYWORD` rule's per-rule *allow_list* (exception terms).
- **Mention-spam cap** (`MENTION_SPAM`, 1 per guild): configurable up to **50 unique role/user mentions per message** before AutoMod acts. Set this low (e.g. 5) for raid resistance.
- Actions per rule: block message, alert a mod channel, timeout the author. Always route a copy to a private `#mod-log`.
- Source: Discord — *Auto Moderation* developer docs (docs.discord.com/developers/resources/auto-moderation) + *AutoMod FAQ* (support.discord.com), accessed 2026-06-02.

### Verification levels
- Set **Medium** as the baseline: verified email + member for >5 minutes before talking. **High** adds a 10-minute server-tenure requirement; **Highest** requires a verified phone. Raise the level temporarily during a raid (the "lockdown" lever).

### Rules Screening / Membership Screening
- Gates **talking and DMs** until a new member explicitly acknowledges the rules. This both stops drive-by spam and forces the first deliberate click of the onboarding funnel.
- Pair with **Onboarding** (role/interest selection on join) so the rules-ack flows straight into role-on-join → personalized channels.
- Source: Discord — *Rules Screening FAQ* + community-building playbooks, accessed 2026-06-02.

### Layered defense by size (Discord's own guidance)
| Size | Recommended stack |
|---|---|
| Small (< 1,000) | Native AutoMod + Medium verification |
| > 1,000 | Add a specialized moderation bot + custom keyword rules |
| > 10,000 | Robust multi-tool bots + Commonly-Flagged filters on |
| > 100,000 | Multiple specialized bots + tiered human mod org |
- Canonical 3-layer stack everywhere: **native tools → bot automod → human mods**.
- Source: Discord safety guidance summarized in friendify.net *Discord Moderation & AutoMod Complete Guide (2025)*, accessed 2026-06-02.

## Telegram — mobile-first, broadcast-heavy

### The hybrid pattern (2026 standard)
- **Groups = two-way conversation; channels = one-way broadcast.** A bare group has no clean announce lane; a bare channel has no conversation. Run a **channel for announcements + a linked discussion group** so each post can spawn a thread.
- Source: Metricgram — *Telegram Group vs Channel*, accessed 2026-06-02.

### Native anti-spam + slow-mode
- **Native ML anti-spam activates for groups > 200 members**, with an **"Aggressive" mode** that auto-deletes suspected spam. Below that threshold it is unavailable.
- For low-traffic groups (**≤ 30 messages/hour**), **slow-mode alone** is the recommended zero-setup control — no bot needed.
- Source: Metricgram — *Best Telegram Anti-Spam Bots* / *Supergroups Explained*, accessed 2026-06-02.

### Raid gate
- **CAPTCHA-on-join** is the standard raid wall: button / math / question challenge (e.g. **Shieldy**). New accounts must pass before they can post.
- Source: Metricgram — *Anti-Spam Bots*, accessed 2026-06-02.

## Circle — the paid / monetized end

### Spaces and structure
- Content is organized into **Spaces**, which structure **tiered membership** and bundle **courses and events**. This is the monetization primitive — gate Spaces by paid tier.

### 2026 plan ladder + fees
Circle **discontinued the old "Basic" tier** — **Professional is now the entry plan**.

| Plan | Approx monthly | Circle transaction fee |
|---|---|---|
| Professional (entry) | ~$89 annual / ~$129 monthly | 2% |
| Business | ~$199 annual / ~$219 monthly | 1% |
| Circle Plus (Enterprise, custom) | ~$419+ | 0.5% |
- The transaction fee is **tiered 0.5%–2%** (2% Professional, 1% Business, 0.5% Circle Plus) and is charged by Circle **on top of Stripe's standard 2.9% + $0.30** per transaction — budget both layers when modeling take rate.
- **Real-time chat is weaker than Discord** — choose Circle for monetized membership + content bundling, not for fast live conversation.
- Source: Circle.so *Pricing* (circle.so/pricing) summarized in SchoolMaker *Circle.so Pricing 2026*, accessed 2026-06-02.

### Monetization gating
- Do **not** monetize before activation works. Charging for a dead room produces instant churn. Prove rhythm + cohort retention on the free or trial tier first, then gate the high-value Spaces.

#!/usr/bin/env bash
# verify.sh — structural check for a community moderation-config artifact.
# Read-only. Validates required keys, a non-empty north-star, all 3 moderation
# layers, and at least one ritual with a cadence. Exits 0 on a clean/empty target.
#
# Usage: scripts/verify.sh [path/to/moderation-config.yaml|.json]
# If no path is given, scans the working tree for moderation-config.{yaml,yml,json}.
# No target found => nothing to check => exit 0 (no false failure).

set -euo pipefail

fail() { echo "FAIL: $1" >&2; exit 1; }
ok()   { echo "OK: $1"; }

# --- resolve targets -------------------------------------------------------
targets=()
if [ "$#" -ge 1 ]; then
  for arg in "$@"; do
    [ -f "$arg" ] || fail "no such file: $arg"
    targets+=("$arg")
  done
else
  while IFS= read -r f; do targets+=("$f"); done < <(
    find . -type f \( -name 'moderation-config.yaml' -o -name 'moderation-config.yml' -o -name 'moderation-config.json' \) 2>/dev/null
  )
fi

if [ "${#targets[@]}" -eq 0 ]; then
  echo "OK: no moderation-config artifact found — nothing to verify."
  exit 0
fi

# --- per-file checks -------------------------------------------------------
check_file() {
  local file="$1"
  local body
  body="$(cat "$file")"

  # Parse-only sanity for JSON; YAML is checked line-wise via grep below.
  case "$file" in
    *.json)
      if command -v python3 >/dev/null 2>&1; then
        python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$file" \
          || fail "$file is not valid JSON"
      fi
      ;;
  esac

  # required top-level / nested keys (token presence is enough for the structural gate)
  local required=(platform purpose north_star_metric onboarding_path moderation rituals)
  local k
  for k in "${required[@]}"; do
    grep -Eq "(\"$k\"[[:space:]]*:|^[[:space:]]*$k[[:space:]]*:)" <<<"$body" \
      || fail "$file is missing required key: $k"
  done

  # north_star_metric must be non-empty (the no-purpose defect)
  local nsm
  nsm="$(grep -E "(\"north_star_metric\"|north_star_metric)[[:space:]]*:" <<<"$body" \
        | head -n1 | sed -E 's/.*north_star_metric"?[[:space:]]*:[[:space:]]*//' \
        | tr -d '",' | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
  [ -n "$nsm" ] || fail "$file has an empty north_star_metric"

  # moderation must declare all three layers
  local layer
  for layer in native bot human; do
    grep -Eq "(\"$layer\"[[:space:]]*:|^[[:space:]]*$layer[[:space:]]*:)" <<<"$body" \
      || fail "$file moderation does not declare the '$layer' layer"
  done

  # at least one ritual with a non-empty cadence
  grep -Eq "(\"cadence\"|cadence)[[:space:]]*:[[:space:]]*[\"']?[[:alnum:]]" <<<"$body" \
    || fail "$file has no ritual with a non-empty cadence"

  ok "$file passed all structural checks."
}

for t in "${targets[@]}"; do
  check_file "$t"
done

echo "OK: all ${#targets[@]} artifact(s) verified."
exit 0