rsc-universal 0.1.1

package/skills/analytics/references/event-taxonomy.md

@@ -0,0 +1,75 @@
+# Event taxonomy reference
+
+Depth offloaded from `../SKILL.md` Step 1. The taxonomy is the contract; design it before SDK code.
+
+## Naming rules
+
+- **`object_action`, `snake_case`, action in past tense.** `signup_completed`, `checkout_started`,
+  `invoice_paid`. Object = noun, action = what happened.
+- **Detail goes in properties, not the name.** One `cta_clicked` with `{ location }` beats four named
+  variants you can never aggregate.
+- **GA4 hard limits** (the SDK silently truncates/drops violators): name ≤ 40 chars, `[a-z0-9_]` only,
+  **must start with a letter**; ≤ 25 params/event; ≤ 25 user properties.
+- **Prefer GA4 recommended events** (`sign_up`, `login`, `purchase`, `add_to_cart`, `search`,
+  `generate_lead`) — they unlock prebuilt reports/audiences a custom name cannot.
+- **The anti-rename rule:** you may add events forever; never rename a live one. A rename forks the metric —
+  the old funnel flatlines, the new one starts at zero. Deprecate in a doc instead.
+
+## Property conventions
+
+- Stable, lowercase, snake_case keys: `plan`, `source`, `value`, `currency`, `referrer`.
+- Types stay consistent: `value` is always a number, `currency` always an ISO code. Mixed types break
+  aggregation downstream.
+- **No PII in props** — see the banlist below. Identity goes on the person profile via `identify`, set once,
+  not stamped on every event.
+
+## Identify vs anonymous vs group
+
+| Concept | When | Call |
+| --- | --- | --- |
+| Anonymous | pre-login; identity is `client_id` / `distinct_id` | nothing — auto |
+| Identify | on authentication; merge anonymous history into the user | `identify(stableId, { plan })` — `stableId` is a DB id / UUID, **never email** |
+| Group | B2B account-level rollups (per company/workspace) | `group('company', orgId, { name })` |
+| Reset | on logout, especially shared machines | `reset()` — prevents identity bleed |
+
+## PII banlist (never in event props)
+
+`email`, `phone`, full name, raw IP, geo coordinates, `password`, `token`, `secret`, API keys,
+`session_id`, `credit_card`, `ssn`, IBAN. Scrub these at a single `capture()` wrapper rather than trusting
+every call site.
+
+## Starter SaaS catalog
+
+| Event | Key properties | Funnel stage |
+| --- | --- | --- |
+| `signup_started` | `source` | acquisition |
+| `signup_completed` | `method` (`google` / `email`) | acquisition |
+| `onboarding_step_completed` | `step`, `step_number` | activation |
+| `project_created` | `template` | activation |
+| `invite_sent` | `count` | activation |
+| `subscription_started` | `plan`, `value`, `currency` | revenue |
+| `invoice_paid` | `value`, `currency`, `invoice_id` | revenue |
+| `feature_used` | `feature` | retention |
+
+Example funnel: `signup_started → signup_completed → project_created → invoice_paid`.
+
+## Starter e-commerce catalog (GA4-aligned)
+
+| Event | Key properties |
+| --- | --- |
+| `view_item` | `items`, `value`, `currency` |
+| `add_to_cart` | `items`, `value`, `currency` |
+| `begin_checkout` | `items`, `value`, `currency` |
+| `add_payment_info` | `payment_type` |
+| `purchase` | `transaction_id`, `value`, `currency`, `items` |
+| `refund` | `transaction_id`, `value`, `currency` |
+
+Example funnel: `view_item → add_to_cart → begin_checkout → purchase`.
+
+## Sources
+
+- GA4 event-name constraints / Measurement Protocol: https://developers.google.com/analytics/devguides/collection/protocol/ga4
+- GA4 recommended events: https://support.google.com/analytics/answer/9267735
+- PostHog identify/group: https://posthog.com/docs/references/posthog-js
+
+Accessed 2026-06-02.

package/skills/analytics/references/ga4-setup.md

@@ -0,0 +1,122 @@
+# GA4 setup reference
+
+Depth offloaded from `../SKILL.md` Steps 2-3. Use current gtag.js APIs.
+
+## Install — Next.js App Router
+
+Load the tag once, globally. The consent default block (below) MUST execute before `gtag('config', ...)`.
+
+```tsx
+// app/layout.tsx
+import Script from 'next/script';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Script id="ga-consent" strategy="beforeInteractive">{`
+          window.dataLayer = window.dataLayer || [];
+          function gtag(){ dataLayer.push(arguments); }
+          gtag('consent', 'default', {
+            ad_storage: 'denied',
+            ad_user_data: 'denied',
+            ad_personalization: 'denied',
+            analytics_storage: 'denied',
+            wait_for_update: 500,
+          });
+        `}</Script>
+        <Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX" strategy="afterInteractive" />
+        <Script id="ga-config" strategy="afterInteractive">{`
+          gtag('js', new Date());
+          gtag('config', 'G-XXXXXXXXXX');
+        `}</Script>
+      </body>
+    </html>
+  );
+}
+```
+
+Custom event from the client:
+
+```ts
+gtag('event', 'purchase', { value: 49.0, currency: 'EUR', transaction_id: 'ord_123' });
+```
+
+## Consent Mode v2 — region-scoped defaults
+
+Default to `denied` for EEA/UK/CH; you may default `granted` elsewhere. Enforced for EEA/UK traffic since
+**21 July 2025** — tags without connected consent lose conversion tracking, remarketing, and demographics.
+
+```html
+<script>
+  // EEA/UK/CH: deny by default
+  gtag('consent', 'default', {
+    ad_storage: 'denied', ad_user_data: 'denied', ad_personalization: 'denied',
+    analytics_storage: 'denied', wait_for_update: 500,
+    region: ['ES','FR','DE','IT','PT','NL','BE','IE','PL','SE','DK','FI','AT','GR','CZ','RO','HU','GB','CH','NO','IS','LI'],
+  });
+  // rest of world: allow by default
+  gtag('consent', 'default', {
+    ad_storage: 'granted', ad_user_data: 'granted', ad_personalization: 'granted',
+    analytics_storage: 'granted',
+  });
+  // on banner accept:
+  function onConsentAccepted() {
+    gtag('consent', 'update', {
+      ad_storage: 'granted', ad_user_data: 'granted',
+      ad_personalization: 'granted', analytics_storage: 'granted',
+    });
+  }
+</script>
+```
+
+The four params are required: `ad_storage`, `ad_user_data`, `ad_personalization`, `analytics_storage`.
+`wait_for_update` (ms) holds tags briefly so a fast banner choice is respected before the first hit.
+
+## Measurement Protocol — server-side event
+
+For actions off the browser (payment confirmation, webhook, cron). Send the **same `client_id`** the
+browser used so the event stitches to the right user. Must arrive within **48h** of the client timestamp.
+
+```bash
+curl -X POST \
+  "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_SECRET" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "client_id": "1234567.7654321",
+    "user_id": "db_user_42",
+    "events": [{ "name": "purchase",
+      "params": { "value": 49.0, "currency": "EUR", "transaction_id": "ord_123" } }]
+  }'
+```
+
+Limits: ≤ 25 events per request; event name ≤ 40 chars, alphanumeric + underscore, must start with a letter;
+≤ 25 params/event; ≤ 25 user properties. If you set `user_id` server-side, set the **same** value
+browser-side or you create duplicate users.
+
+## Recommended events (prefer over custom names)
+
+| Event | Key params | Unlocks |
+| --- | --- | --- |
+| `sign_up` | `method` | sign-up reports / audiences |
+| `login` | `method` | engaged-user segments |
+| `purchase` | `value`, `currency`, `transaction_id`, `items` | revenue reports, ecommerce |
+| `add_to_cart` | `value`, `currency`, `items` | cart-abandon funnels |
+| `search` | `search_term` | site-search reports |
+| `generate_lead` | `value`, `currency` | lead audiences for Ads |
+
+## Validate before shipping
+
+Open **Admin → DebugView** (or filter the network tab for `/g/collect`). Confirm each event fires **once**
+with the expected params and that the `client_id` is stable. A double `/g/collect` for one action means a
+render-fired event — guard it.
+
+## Sources
+
+- Consent guide + July-2025 enforcement: https://developers.google.com/tag-platform/security/guides/consent
+- Measurement Protocol: https://developers.google.com/analytics/devguides/collection/protocol/ga4
+- Sending events: https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events
+- Recommended events: https://support.google.com/analytics/answer/9267735
+
+Accessed 2026-06-02.

package/skills/analytics/references/posthog-setup.md

@@ -0,0 +1,100 @@
+# PostHog setup reference
+
+Depth offloaded from `../SKILL.md` Step 2. Use current `posthog-js` and `@posthog/next` APIs.
+
+## `posthog.init` options that matter
+
+```ts
+import posthog from 'posthog-js';
+
+posthog.init('phc_xxx', {
+  api_host: '/ingest',                 // reverse proxy first-party path (recommended)
+  ui_host: 'https://eu.posthog.com',   // EU cloud; use https://us.posthog.com for US
+  person_profiles: 'identified_only',  // no profile per anonymous visitor — cost + privacy default
+  defaults: '2025-05-24',              // pin behavior defaults to a known date
+  autocapture: true,                   // clicks/inputs/forms on a, button, form, input, select, textarea, label
+  capture_pageview: true,
+});
+```
+
+- `person_profiles: 'identified_only'` — the recommended default. Without it you create a person profile for
+  every anonymous visitor (more cost, more data).
+- **EU vs US host:** pick the region your account is in; EU keeps data in the EU for residency.
+- `autocapture: false` — set this if you want a deliberate, named-only taxonomy with no DOM noise.
+
+## Core API
+
+```ts
+posthog.capture('signup_completed', { method: 'google' }); // never put email/token in props
+posthog.identify(user.id, { plan: user.plan });            // stable id, NOT the email
+posthog.group('company', org.id, { name: org.name });      // B2B account-level analytics
+posthog.register({ app_version: '2.1.0' });                // super-properties on every event
+posthog.unregister('app_version');
+posthog.reset();                                           // on logout — critical on shared machines
+```
+
+## Consent
+
+```ts
+// EEA visitor: start opted-out; opt in only on banner accept.
+posthog.opt_out_capturing();
+function onConsentAccepted() { posthog.opt_in_capturing(); }
+```
+
+The legal banner text is `gdpr-privacy`'s job; this only wires the opt-in/opt-out signal.
+
+## Reverse proxy (Next.js rewrite)
+
+Serving the SDK + ingestion under a first-party path beats ad-blockers and tracking-prevention, which
+otherwise eat a meaningful share of events.
+
+```ts
+// next.config.js
+async rewrites() {
+  return [
+    { source: '/ingest/static/:path*', destination: 'https://eu-assets.i.posthog.com/static/:path*' },
+    { source: '/ingest/:path*',        destination: 'https://eu.i.posthog.com/:path*' },
+  ];
+}
+```
+
+## Server-side capture with `@posthog/next`
+
+Use for trusted server-side captures (payment confirmation, webhook, server action). `getPostHog()` reads
+identity from the PostHog cookie and opts the route into dynamic rendering (it calls `cookies()`).
+
+```ts
+// app/api/checkout/route.ts
+import { getPostHog } from '@posthog/next';
+
+export async function POST(req: Request) {
+  const posthog = await getPostHog();
+  posthog.capture({ event: 'invoice_paid', properties: { value: 49, currency: 'EUR' } });
+  return Response.json({ ok: true });
+}
+```
+
+## Feature flags
+
+```ts
+if (posthog.isFeatureEnabled('new-checkout')) { /* ... */ }
+const variant = posthog.getFeatureFlag('pricing-test');
+```
+
+Reading a flag emits a `$feature_flag_called` event — expected, not a bug; budget for it in event volume.
+Experiment *design and stats* belong to `ab-testing`, not here.
+
+## Validate
+
+Watch the **Activity / live events** feed in PostHog after a test action. Confirm each named event arrives
+**once** and that `distinct_id` stays stable across the session and survives login (via `identify`).
+
+## Sources
+
+- JS SDK: https://posthog.com/docs/references/posthog-js — repo: https://github.com/posthog/posthog-js
+- Config: https://posthog.com/docs/libraries/js/config
+- Feature flags: https://posthog.com/docs/feature-flags
+- `@posthog/next`: https://github.com/posthog/posthog-js/tree/main/packages/next
+- Reverse proxy: https://posthog.com/docs/advanced/proxy
+
+Accessed 2026-06-02.

package/skills/analytics/scripts/verify.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — analytics skill gate. Run from your PROJECT root (or pass a path).
+#
+# What it does (read-only, idempotent, NEVER connects to a network/SDK):
+#   1. Discovers source files (js/ts/jsx/tsx/html/vue/svelte), skipping vendor dirs.
+#   2. PII literals inside capture/track/gtag('event' calls            -> [fail]
+#   3. GA4 event names breaking <=40 chars / leading-letter / charset  -> [fail]
+#   4. GA present (gtag(/gtag.js) but no gtag('consent','default'      -> [fail] missing consent gate
+#   5. posthog.init( with no host option nearby                        -> [warn] reverse-proxy reminder
+#
+# Exit non-zero ONLY on a hard failure (2,3,4), printing the offending file:line.
+# Check 5 is advisory. An empty or clean target exits 0. Stock macOS bash 3.2.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="${1:-$(pwd)}"
+if [ ! -e "$ROOT" ]; then skip "path not found: $ROOT — nothing to lint"; ok "verify.sh passed (empty target)"; exit 0; fi
+
+FILES=()
+while IFS= read -r -d '' f; do
+  FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.next/*' \
+       -o -path '*/dist/*' -o -path '*/build/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f \( -name '*.js' -o -name '*.jsx' -o -name '*.ts' -o -name '*.tsx' \
+               -o -name '*.mjs' -o -name '*.cjs' -o -name '*.html' -o -name '*.vue' -o -name '*.svelte' \) \
+    -print0 2>/dev/null
+)
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  skip "no source files found under $ROOT — nothing to lint"
+  ok "verify.sh passed (empty target)"
+  exit 0
+fi
+
+# Lines that look like an analytics capture call.
+CAPTURE_RE='(\.capture\(|posthog\.capture\(|\.track\(|gtag\([[:space:]]*['"'"'"]event['"'"'"])'
+# PII key names that must never ride inside a capture call.
+PII_RE='(email|e_mail|password|passwd|token|secret|api_?key|access_?key|ssn|credit_?card|card_?number|cvv|iban|phone_?number)'
+
+GA_PRESENT=0
+GA_CONSENT=0
+
+for f in "${FILES[@]}"; do
+  # --- (2) PII literals inside capture/track/gtag event calls (hard fail) ---
+  while IFS= read -r hit; do
+    [ -n "$hit" ] && err "$f:$hit — PII-looking key inside a capture/track call; scrub before sending"
+  done < <(grep -nEi "$CAPTURE_RE" "$f" 2>/dev/null | grep -Ei "$PII_RE" | cut -d: -f1)
+
+  # --- (3) GA4 event names breaking the rule (hard fail) ---
+  # extract names from gtag('event', '<name>'...) and validate.
+  while IFS= read -r ln; do
+    lineno="${ln%%:*}"
+    name="$(printf '%s' "$ln" | sed -E "s/.*gtag\([[:space:]]*['\"]event['\"][[:space:]]*,[[:space:]]*['\"]([^'\"]*)['\"].*/\1/")"
+    [ -z "$name" ] && continue
+    if [ "${#name}" -gt 40 ]; then err "$f:$lineno — GA4 event name '$name' exceeds 40 chars"; fi
+    if ! printf '%s' "$name" | grep -Eq '^[A-Za-z][A-Za-z0-9_]*$'; then
+      err "$f:$lineno — GA4 event name '$name' must start with a letter and use only [A-Za-z0-9_]"
+    fi
+  done < <(grep -nE "gtag\([[:space:]]*['\"]event['\"]" "$f" 2>/dev/null)
+
+  # --- track GA presence + consent for check (4) ---
+  if grep -Eq "gtag\(|googletagmanager\.com/gtag/js" "$f" 2>/dev/null; then GA_PRESENT=1; fi
+  if grep -Eq "gtag\([[:space:]]*['\"]consent['\"][[:space:]]*,[[:space:]]*['\"]default['\"]" "$f" 2>/dev/null; then GA_CONSENT=1; fi
+
+  # --- (5) posthog.init with no host nearby (advisory) ---
+  while IFS= read -r ln; do
+    lineno="${ln%%:*}"
+    # look at the init line and the 8 lines after it for api_host/ui_host/host.
+    if ! sed -n "${lineno},$((lineno+8))p" "$f" 2>/dev/null | grep -Eq '(api_host|ui_host|[^a-z_]host)[[:space:]]*:'; then
+      note "$f:$lineno — posthog.init( with no api_host/ui_host; consider a reverse proxy to dodge ad-blockers"
+    fi
+  done < <(grep -nE 'posthog\.init\(' "$f" 2>/dev/null)
+done
+
+# --- (4) GA present but no consent default gate (hard fail) ---
+if [ "$GA_PRESENT" -eq 1 ] && [ "$GA_CONSENT" -eq 0 ]; then
+  err "GA4/gtag detected but no gtag('consent','default', ...) gate found — required for EEA/UK since 21 Jul 2025"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then
+  ok "verify.sh passed — scanned ${#FILES[@]} file(s)"
+else
+  err "verify.sh found failures"
+fi
+exit "$EXIT"

package/skills/analyze/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: analyze
+description: "Use when the spec, plan and task list are written and you want a last consistency check BEFORE any code is touched — the pre-implementation GATE of the rsc-sdd chain. It cross-reads constitution vs spec vs plan vs tasks and reports gaps, contradictions, duplication, ambiguity and scope drift, mapping every artifact to the requirements it claims to satisfy. Report-only: it never edits artifacts and never writes code; the user decides each resolution. Triggers: 'analyze', 'analiza la spec antes de implementar', 'cross-check constitution spec plan tasks', 'consistency gate', 'are spec and plan aligned', 'did we miss any requirement', 'scope drift check', 'gap analysis before coding', 'is the plan complete', 'sanity-check before implement', 'coverage of requirements'. NOT clarifying a single spec (that is `clarify`), NOT writing the plan or tasks, NOT running tests/lint (that is `verify`), NOT root-causing a bug (that is `debug`)."
+tags: [sdd, analyze, consistency]
+recommends: [implement]
+profiles: [core, full]
+origin: risco
+---
+
+# Analyze — the pre-implementation consistency gate
+
+You have a **constitution**, a **spec**, a **plan** and a **task list**. Four artifacts written at four different moments, by a mind that drifted a little each time. `analyze` is the last checkpoint before the first line of code: it reads all four *against each other* and surfaces where they disagree. It is the cheapest place in the whole chain to catch a problem — a contradiction found here costs a sentence; the same contradiction found mid-implement costs a rewrite.
+
+This is the **sixth phase** of the rsc-sdd chain (`constitution → specify → clarify → plan → tasks → analyze → implement`). It is a **gate, not a worker**: it produces a report and stops. It does not patch the spec, does not reorder tasks, does not touch code. The user reads the findings and decides what to fix, and which phase to send each fix back to.
+
+## The one rule that defines this skill
+
+**Report only. Resolve nothing.** `analyze` never edits the constitution, spec, plan or tasks, never opens a code file to "just fix it", never silently reconciles a contradiction by picking a side. It names the conflict, shows both artifacts with their locations, proposes where it should be resolved, and hands the decision back. The moment you feel the urge to edit an artifact, you have left this skill — stop and route the fix to the phase that owns it.
+
+Why so strict? Because a gate that quietly fixes things stops being a gate. If `analyze` patches the spec on its own, the user never learns the spec was wrong, the plan built on the old assumption stays stale, and the "consistency check" has manufactured a new inconsistency. The value is the *honest report*, not the patch.
+
+## When to use / when NOT to use
+
+Use when:
+
+- The plan and tasks exist and you are about to start implementing — run this first, every time.
+- A spec or plan changed after the others were written and you want to re-check alignment.
+- Implementation stalled because the artifacts seem to contradict each other.
+- You want a requirements-coverage map: which task satisfies which spec requirement, and what is orphaned.
+
+Do NOT use when (route elsewhere):
+
+- A single spec is fuzzy and you need to ask the user questions and bake answers in → `clarify` (analyze reports the ambiguity; clarify resolves it).
+- The plan or tasks don't exist yet → write them first (`plan`, then `tasks`).
+- You want to run lint/types/tests/acceptance after coding → `verify` (post-implementation gate; analyze is pre-implementation).
+- A test is failing or behavior is wrong → `debug`.
+- You intend to fix what you find right now → that is `implement`/`clarify`/`plan`/`tasks` work, not analyze. Analyze only reports.
+
+## Read the accompaniment dial first
+
+Before reporting, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment level (the harness dial, L0..L3). It shapes how the report reads — not what gets checked. The six analyses always run in full; verbosity flexes:
+
+- **L0** — the finding table only: severity, the two artifacts, the conflict in one line. No prose.
+- **L1** — the table plus a one-line *why it matters* per CRITICAL/HIGH finding.
+- **L2** — the table plus, per finding, the recommended resolution phase and the trade-off of leaving it.
+- **L3** — full walk-through: for each finding, quote both sides, explain the consequence at implement time in plain language, and lay out the options so a non-technical user can choose.
+
+If no profile exists, default to L2 and note that the harness has not gauged the user yet.
+
+## Inputs — locate the four artifacts
+
+Read all four before analyzing. The rsc-sdd artifacts live under `02-DOCS/wiki/sdd/` (the harness Karpathy-wiki convention), indexed from the root `CLAUDE.md` `## Knowledge map`:
+
+| Artifact | Canonical location | Role in the check |
+| --- | --- | --- |
+| Constitution | `02-DOCS/wiki/sdd/constitution.md` | The non-negotiables. Everything below must obey it. |
+| Spec | `02-DOCS/wiki/sdd/specs/<slug>.md` | WHAT & WHY. The source of truth for requirements. |
+| Plan | `02-DOCS/wiki/sdd/plans/<slug>.md` | HOW. Must cover every spec requirement, add nothing the spec didn't ask for. |
+| Tasks | task list inside the plan artifact | The ordered, verifiable steps. Must implement the plan, no more. |
+
+If any artifact is missing, **stop and say so** — analyze cannot gate what isn't there. Name the missing one and the phase that produces it. If a `<slug>` is ambiguous (several specs), ask which feature is being gated; do not analyze all of them blindly.
+
+## The six analyses
+
+Run every one. Each compares a specific pair (or the whole set against the constitution) and emits findings.
+
+1. **Constitution compliance** — does any spec requirement, plan decision or task violate a non-negotiable (stack canon, quality bar, convention)? A constitution breach is the highest-severity finding there is; the constitution wins by definition.
+2. **Requirement coverage (spec → plan → tasks)** — map every spec requirement forward. Each must trace to at least one plan section and at least one task. A requirement with no task is a **gap** (it will silently not ship). Build the coverage map below.
+3. **Scope drift (tasks/plan → spec)** — map backward. Any plan section or task that satisfies *no* spec requirement is **drift** — work the spec never asked for. Flag it; the fix is either cut the work or amend the spec, and that is the user's call.
+4. **Contradiction** — direct disagreements between two artifacts: the spec says Postgres, the plan says SQLite; the spec says "no auth in v1", a task adds login. Quote both sides.
+5. **Duplication** — the same requirement stated twice in conflicting words, or two tasks doing the same job. Duplication is where contradictions breed later.
+6. **Ambiguity / underspecification** — requirements or tasks too vague to implement or to verify ("handle errors gracefully", "make it fast" with no number, a task with no done-check). These do not block by themselves but feed back to `clarify` (spec) or `tasks` (missing done-check).
+
+### Requirement coverage map (build this every run)
+
+A copy-able table that makes gaps and drift visible at a glance:
+
+```text
+REQ-ID | Spec requirement (short)        | Plan section | Task(s) | Status
+------ | ------------------------------- | ------------ | ------- | ----------
+R1     | Email/password sign-up          | §3 Auth      | T2,T3   | covered
+R2     | Rate-limit login (5/min/IP)     | §3 Auth      | —       | GAP
+R3     | —                               | §5 Webhooks  | T9      | DRIFT
+R4     | "Fast" search                   | §4 Search    | T6      | AMBIGUOUS (no metric)
+```
+
+- `GAP` — spec requirement with no task → it won't be built.
+- `DRIFT` — plan/task with no spec requirement → unrequested scope.
+- `AMBIGUOUS` — covered but not specific enough to verify later.
+- `covered` — traces cleanly spec → plan → task.
+
+## Severity scale
+
+Rank every finding so the user triages fast:
+
+- **CRITICAL** — constitution violation, or a contradiction that makes the artifacts un-implementable as written. Must resolve before `implement`.
+- **HIGH** — a coverage GAP on a core requirement, or scope DRIFT that adds real cost. Resolve before implement.
+- **MEDIUM** — duplication, or AMBIGUOUS items with no number/done-check. Resolve or consciously accept.
+- **LOW** — wording mismatches, cosmetic inconsistencies. Note and move on.
+
+## Output — the report (and where it goes)
+
+Produce a single consistency report:
+
+1. **Verdict line** — `GATE: PASS` (zero CRITICAL/HIGH) or `GATE: BLOCKED` (one or more CRITICAL/HIGH), with the counts.
+2. **Coverage map** — the table above.
+3. **Findings table** — `# | Severity | Type | Artifact A (loc) | Artifact B (loc) | Conflict | Resolve in (phase)`.
+4. **Recommended routing** — group fixes by the phase that owns them (`clarify` for spec ambiguity, `plan` for missing architecture, `tasks` for a missing done-check, `constitution` if a principle itself is wrong).
+
+Write the report to `02-DOCS/wiki/sdd/analysis/<slug>.md` (create the dir if absent) and add/refresh its row in the root `CLAUDE.md` `## Knowledge map` under the `sdd/` topic, so the next phase and the harness can find it. The report is the artifact analyze owns — it is the *only* thing analyze writes. Per-run point-in-time; overwrite on re-run, the wiki keeps history.
+
+Adapt the rendered verbosity to the dial (L0 = table only; L3 = full walk-through). Do not log a decision to `decisions.md` — analyze decides nothing; the phase that resolves the finding logs its own decision.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "This contradiction is trivial, I'll just fix the spec myself" | Then you are `clarify`/`plan`, not `analyze`. Report it; the user resolves. A gate that edits stops being a gate. |
+| "No CRITICAL findings, so I'll start coding from here" | Analyze never transitions to code. Pass the verdict to `implement`; that phase starts the work. |
+| "The plan adds caching the spec didn't mention — obviously a good idea, I'll allow it" | That is DRIFT. Flag it. Good ideas still need the spec amended (user's call), or they are silent scope creep. |
+| "I'll only check coverage; contradictions are rare" | Run all six analyses every time. The one you skip is the one that bites at implement time. |
+| "The spec is vague but I can guess what they meant" | Guessing defeats the gate. Mark AMBIGUOUS and route to `clarify`; do not encode your guess. |
+| "I'll fold the findings straight into the task list to save a step" | No. Editing tasks is the `tasks` phase. Report, route, hand back. |
+| "Constitution says Postgres but plan picked Mongo for good reasons — I'll side with the plan" | The constitution wins by definition. Flag CRITICAL. If the principle is wrong, that is a `constitution` change the user makes, not a quiet override here. |
+| "I read the spec and tasks; the constitution is boilerplate, skip it" | The constitution is analysis #1 and the highest severity. Never skip it. |
+
+## Red flags — stop and report instead of analyzing
+
+- An artifact is missing (no plan, no tasks) → say which, name the phase, do not fabricate it.
+- Multiple specs match the slug → ask which feature; don't analyze the wrong one.
+- You catch yourself opening a source file → you have left the gate; close it.
+- Findings are pouring in across all six checks → the artifacts diverged badly; recommend the user re-runs `clarify`/`plan` before a line-by-line analyze is even useful.
+
+## Next in the chain
+
+When the verdict is `GATE: PASS` (or the user has consciously accepted the remaining MEDIUM/LOW findings), proceed to **`implement`** — execute the tasks with TDD discipline, delegating concrete test tooling to the relevant stack skill (`fastapi`, `nextjs`, `go`, `flutter`, `postgresdb`). If the verdict is `GATE: BLOCKED`, route each CRITICAL/HIGH finding to its owning phase (`clarify`, `plan`, `tasks`, or `constitution`), let the user resolve, then re-run `analyze`. The gate only opens once.

package/skills/analyze/evals/README.md

@@ -0,0 +1,72 @@
+# Eval harness — `analyze` skill
+
+`analyze` is the rsc-sdd **pre-implementation consistency gate**. These evals
+check two things: that the skill **triggers** on the right prompts (a
+cross-check of the planning artifacts before coding) and stays quiet on
+near-misses (anything that resolves, builds, runs, or debugs code), and that it
+**measurably changes the answer** — reporting and routing instead of editing
+artifacts or jumping into code. Cases live in `cases.yaml`. There is no shell
+runner: triggering and report quality are judgment calls graded by an agent
+harness plus a human spot-check.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `analyze` (several avoid the word
+  "analyze" to test intent, not keyword).
+- `should_not_trigger` — near-misses routed to the correct existing sibling via
+  `route_to` (debugging, verification via a stack skill, plan authoring, code
+  review, harness bootstrap, db perf).
+- `capability` — a full BLOCKED-gate scenario with a `must_include` rubric to
+  grade with vs without the skill.
+
+## Triggering eval
+
+Goal: the gate fires when the four artifacts exist and a cross-check is wanted,
+and never on a near-miss.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing (analyze + harness, init, the stack skills fastapi/nextjs/go/
+   flutter/postgresdb, secure-coding, deployment, design, marketing,
+   presentations, course-storytelling, building-agents) so routing competes
+   realistically. When the other rsc-sdd phase skills (clarify, plan, tasks,
+   implement, verify, review, debug) are added to the repo, include them too —
+   they are the closest competitors and the sharpest test of the boundary.
+2. For each `should_trigger` prompt: feed it cold, record whether `analyze` is
+   the skill the agent loads. Run **3-5 trials** per prompt (fresh context).
+3. For each `should_not_trigger` prompt: confirm `analyze` does NOT load and the
+   chosen skill matches `route_to`. Same 3-5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: >= 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the debugging and verification near-misses
+(those are the known traps — "is it ready to ship / why is it failing" is a
+post-implementation or runtime concern, not a pre-implementation artifact gate).
+
+## Capability eval
+
+Goal: prove the skill changes the answer, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `analyze` loaded).
+   - **WITH** the `analyze` skill loaded.
+2. Grade each output against the `must_include` checklist — one point per item
+   covered. A human or grading agent marks each item present / absent.
+3. Compute coverage = `items_covered / total_items` for each run.
+
+**Pass bar: WITH the skill covers >= 80% of `must_include`; WITHOUT clearly
+lower** (target a >= 30-point gap). The discriminating behaviors are the
+report-only discipline (no artifact edits, no code), running all six analyses,
+the constitution-violation + GAP double-flag on the missing rate limit, the
+DRIFT call on the Redis cache, the coverage map, the verdict line, and the
+hand-off to the next phase.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The highest-signal capability check is **restraint**: a correct answer reports
+  and routes, it does not "helpfully" rewrite the spec or start coding. Treat a
+  confident answer that edits an artifact or begins implementation as a
+  **capability failure** even if its analysis is otherwise sharp — that behavior
+  defeats the gate.
+- Re-run after any edit to `SKILL.md`. Wording changes shift both triggering and
+  rubric coverage, and the report-only boundary is easy to soften by accident.