rsc-universal 0.1.1

package/skills/chrome-extension/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: chrome-extension
+description: "Use when building, structuring, or shipping a Manifest V3 browser extension and hitting its quirks — the service worker keeps dying or losing state between events, permission warnings scare users away, the Chrome Web Store rejected the listing, or you must drag an old Manifest V2 extension to V3. Triggers: 'build a Chrome extension', 'my background script keeps resetting its state', 'store rejected me for excessive permissions', 'migrate MV2 to MV3', 'content script messaging to the popup', 'declarativeNetRequest ad blocker', 'crear una extensión de Chrome', 'publicar a la Chrome Web Store', 'el service worker se muere'. NOT a generic web app (that is nextjs)."
+tags: [chrome-extension, manifest-v3, browser-extension, service-worker, chrome-web-store]
+recommends: [nextjs, react, gdpr-privacy, secure-coding, vercel]
+origin: risco
+---
+
+# Chrome extension (Manifest V3)
+
+An MV3 extension is **three isolated JavaScript contexts that never share memory and only talk via messages**:
+
+1. **Service worker** (`background.service_worker`) — the logic and lifecycle brain. Ephemeral: Chrome kills it when idle and restarts it on the next event. It has no DOM and no `window`.
+2. **Content scripts** — run inside a web page, can read/write that page's DOM, live in an isolated JS world by default. No access to most `chrome.*` APIs except messaging and `storage`.
+3. **UI surfaces** — popup (`action.default_popup`), options page, side panel. Normal web pages that load and unload as the user opens/closes them.
+
+Internalize that picture first. Most extension bugs are someone treating one of these as if it shared state with another. They do not. The wire between them is `chrome.runtime` messaging and `chrome.storage`.
+
+Manifest V3 is the only version the Chrome Web Store accepts; MV2 phase-out began June 2024 and is still rolling out. Build MV3 from the start.
+
+## Pick a skeleton
+
+| Setup | Pick when | Cost |
+|---|---|---|
+| **Vanilla** (raw files, `load unpacked`) | tiny extension, no npm imports, you want the fastest possible reload loop | no TS, no HMR, manual reloads |
+| **Vite + CRXJS** (`@crxjs/vite-plugin`) | TS, npm imports, React/Vue popup, you want HMR | a build step; you ship `dist/`, not the repo |
+
+Default to **Vite + CRXJS** the moment you want TypeScript or a framework popup — it does the manifest wiring and HMR for you. Reach for vanilla only for a one-file experiment.
+
+Minimal tree (Vite + CRXJS):
+
+```text
+my-ext/
+  manifest.json        # source of truth; CRXJS reads it
+  src/
+    background.ts       # service worker
+    content.ts          # content script
+    popup/
+      index.html
+      popup.tsx
+  public/icons/         # 16, 48, 128 px PNGs
+  vite.config.ts
+  # build output -> dist/  (this is what you zip)
+```
+
+## manifest.json — minimum viable shape
+
+```json
+{
+  "manifest_version": 3,
+  "name": "Highlighter",
+  "version": "1.0.0",
+  "description": "Highlights selected text on the current page.",
+  "icons": { "16": "icons/16.png", "48": "icons/48.png", "128": "icons/128.png" },
+  "action": { "default_popup": "popup/index.html" },
+  "background": { "service_worker": "background.js", "type": "module" },
+  "permissions": ["activeTab", "storage", "scripting"],
+  "host_permissions": [],
+  "minimum_chrome_version": "120"
+}
+```
+
+Rules that fail review or break the worker if you get them wrong:
+
+- `manifest_version` **must be `3`**. There is no `2` path forward.
+- `background.service_worker` is a **string**, not an array. There is no `background.scripts` and no `background.page` in MV3. The `persistent` key does not exist — delete it. (Source: developer.chrome.com "Migrate to a service worker", accessed 2026-06-02.)
+- `"type": "module"` lets the worker use `import`. Use it if you bundle.
+- Keep `host_permissions` empty until you can name exactly which sites and why (see permission table).
+
+## The three contexts and how they talk
+
+The service worker is **ephemeral**. It terminates when idle and wakes on an event. Two consequences govern almost all your code:
+
+- **Register every listener synchronously at the top level.** If you call `chrome.runtime.onMessage.addListener` inside an `async` callback or after an `await`, Chrome may not have registered it when it wakes the worker, and your event is lost. (Source: developer.chrome.com "Migrate to a service worker", accessed 2026-06-02.)
+- **Never keep state in a global variable.** The worker dies and your variable resets to its initial value. Persist to `chrome.storage`.
+
+```js
+// Bad — global resets to 0 every time the worker is killed and restarts
+let clickCount = 0;
+chrome.action.onClicked.addListener(() => {
+  clickCount++;                          // silently back to 1 after idle
+});
+
+// Good — durable across worker restarts, listener registered at top level
+chrome.action.onClicked.addListener(async () => {
+  const { clickCount = 0 } = await chrome.storage.local.get("clickCount");
+  await chrome.storage.local.set({ clickCount: clickCount + 1 });
+});
+```
+
+Messaging choices:
+
+- **One-shot** request/response: `chrome.runtime.sendMessage(msg)` / `chrome.tabs.sendMessage(tabId, msg)` paired with `chrome.runtime.onMessage`. Return `true` from the listener to keep the channel open for an async `sendResponse`.
+- **Long-lived** stream (e.g. a content script feeding the popup continuously): `chrome.runtime.connect()` → `Port`, with `port.onMessage` / `port.postMessage`.
+
+Content script → service worker → popup: there is no direct content-script-to-popup channel when the popup is closed. Route through the worker or through `chrome.storage` and let the popup read on open.
+
+## Permissions — least privilege or you get rejected
+
+Reviewers reject broad permissions with no justification, and broad `host_permissions` trigger a scary install-time warning that tanks conversion. Declare the **narrowest** thing that works.
+
+| Permission | Grants | Warning? | Use when |
+|---|---|---|---|
+| `activeTab` | temporary access to the current tab, only after a user gesture (toolbar click) | none | the user clicks your icon and you act on that one page |
+| `scripting` | `chrome.scripting.executeScript` to inject programmatically | none alone (needs a host or `activeTab` to target) | inject on demand instead of on every page |
+| `host_permissions: ["https://example.com/*"]` | persistent access to those origins | yes, lists the sites | you must run in the background on specific sites |
+| `host_permissions: ["<all_urls>"]` | every site | loud, broad warning | almost never — avoid; prefer `activeTab` |
+| `optional_permissions` + `chrome.permissions.request()` | runtime opt-in inside a user gesture | shown only when requested | a feature only some users need; ask when they enable it |
+| `declarativeNetRequest` | static/dynamic rules block or modify requests, no request bodies seen | install-time warning | ad/tracker blocking — replaces blocking `webRequest` |
+| `declarativeNetRequestWithHostAccess` | same, but access granted per host instead of install-time | per-host | DNR scoped to granted hosts only |
+
+Rule: write a one-sentence justification for **every** permission before you add it. If you cannot, drop it. `activeTab` covers more cases than people expect — try it first. (Source: developer.chrome.com "Declare permissions" + "declarativeNetRequest", accessed 2026-06-02.)
+
+## Content scripts: declarative vs programmatic
+
+```json
+// Declarative — in manifest. Runs automatically on matching pages.
+"content_scripts": [{
+  "matches": ["https://example.com/*"],
+  "js": ["content.js"],
+  "run_at": "document_idle"
+}]
+```
+
+```js
+// Programmatic — inject on a gesture. Needs "scripting" + activeTab or a host match.
+chrome.action.onClicked.addListener(async (tab) => {
+  await chrome.scripting.executeScript({
+    target: { tabId: tab.id },
+    files: ["content.js"],
+  });
+});
+```
+
+- `run_at`: `document_start` (before DOM), `document_end`, or `document_idle` (default, after load). Pick `document_start` only if you must beat the page's own scripts.
+- **Isolated world** (default): your content script's JS is sandboxed from the page's JS — they share the DOM but not variables. Use **MAIN world** (`"world": "MAIN"`) only when you must touch the page's own JS objects, and know it loses the isolation guarantee.
+- For dynamic, user-supplied injection, `chrome.userScripts.execute()` exists (Chrome 135, Mar 2025) — see references.
+
+## Storage, alarms, no remote code
+
+- `chrome.storage.local` (~10 MB, larger with `unlimitedStorage`) for most data; `chrome.storage.sync` (~100 KB, ~8 KB/item) only for small settings you want to follow the user across devices.
+- **`setTimeout`/`setInterval` are unreliable** in the worker — it may be asleep when they fire. Use `chrome.alarms` for anything beyond a few seconds. (Source: developer.chrome.com "Migrate to a service worker", accessed 2026-06-02.)
+- **Remotely hosted code is banned.** No `<script src="https://cdn...">`, no `eval`-of-fetched-string. All executable JS must ship inside the package — bundle every dependency. This is enforced by MV3's CSP and by review. (Source: developer.chrome.com "What is Manifest V3", accessed 2026-06-02.)
+
+## Shipping to the Chrome Web Store
+
+1. **Build**, then **zip the `dist/` output** — never the repo. No `node_modules`, no `.git`, no source maps you do not want public.
+2. Pay the **one-time $5 USD** developer registration (covers up to 20 extensions on the account).
+3. Upload the zip in the Developer Dashboard.
+4. Listing assets: a **128×128 PNG** icon, **at least one screenshot** (1280×800 or 640×400), a clear description, a category, and a **privacy-policy URL if you collect any data**.
+5. Review is typically **1–3 business days** (simple extensions often under 24h).
+
+(Source: developer.chrome.com "Register your developer account" + fee guide, accessed 2026-06-02.) For the full dashboard walkthrough, data-disclosure form, staged rollout, appeals, and the MV2→MV3 migration map, see [references/store-and-migration.md](references/store-and-migration.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks | Do instead |
+|---|---|---|
+| `background.scripts` / `persistent: true` | MV2 shape; rejected, worker never registers | `background.service_worker: "bg.js"` (string) |
+| Listener added after an `await` | Chrome wakes the worker without your listener; event lost | register all listeners synchronously at top level |
+| State in a global var | worker dies, var resets silently | persist to `chrome.storage` |
+| `<all_urls>` when a click suffices | scary install warning, review pushback | `activeTab` triggered by the toolbar click |
+| `<script src="https://cdn…">` | remote code is banned in MV3 | bundle the dependency into the package |
+| `setInterval` for periodic work | fires only while worker is alive | `chrome.alarms` |
+| Zipping the repo / `node_modules` | bloated, leaks source, may fail review | zip only the built `dist/` |
+| Auth token in a global / `sync` | lost on restart, or synced off-device | `chrome.storage.local` (or `session` for in-memory) |
+| MAIN world by default | loses isolation, page can tamper | isolated world unless you must reach page JS |
+
+Run `scripts/verify.sh <dir>` to lint a produced `manifest.json` against the MV3 invariants above.

package/skills/chrome-extension/evals/README.md

@@ -0,0 +1,12 @@
+# Evals: chrome-extension
+
+`cases.yaml` holds two things. The `should_trigger` / `should_not_trigger`
+prompts are routing checks: read each prompt cold and judge whether this skill
+(versus the named sibling) should fire — run them by hand or feed them to an
+LLM judge against the skill's description. The `capability` case is graded by
+handing the scenario to an agent loaded with the skill and checking the output
+against every item in `must_include` (a rubric, not a string match). There is no
+automated test runner here. The one mechanical check is `scripts/verify.sh
+<dir>`, which lint-checks any `manifest.json` the skill produces against the MV3
+invariants; it exits 0 when the target has no manifest, so it is safe to run on
+an empty directory.

package/skills/chrome-extension/evals/cases.yaml

@@ -0,0 +1,40 @@
+skill: chrome-extension
+
+should_trigger:
+  - prompt: "Build me a Chrome extension that highlights selected text on the page."
+    why: "Clear scaffolding-from-zero request — the core use case (manifest + content script + popup)."
+  - prompt: "My extension's background script keeps losing its state between events — the counter resets to zero."
+    why: "Non-obvious symptom of the ephemeral service worker killing globals; the fix (chrome.storage, top-level listeners) is this skill's heart."
+  - prompt: "The Chrome Web Store rejected my extension for excessive permissions. Help me fix the manifest."
+    why: "Store review + least-privilege permission model — activeTab vs host_permissions, justifications."
+  - prompt: "Migrate this Manifest V2 extension to V3 — it uses background scripts and blocking webRequest."
+    why: "MV2->MV3 migration map: background page->service worker, webRequest->declarativeNetRequest."
+  - prompt: "Crear una extensión para Chrome que bloquee anuncios con declarativeNetRequest."
+    why: "Spanish phrasing + DNR ad-blocking, the canonical replacement for blocking webRequest."
+  - prompt: "How do I send a message from my content script to the popup when the popup is closed?"
+    why: "Non-obvious cross-context messaging — there is no direct channel; route via service worker or storage."
+
+should_not_trigger:
+  - prompt: "Build a desktop app with web technologies that runs outside the browser."
+    route_to: electron
+    why: "Standalone desktop shell, not a browser extension package."
+  - prompt: "Build me a Next.js dashboard with server components."
+    route_to: nextjs
+    why: "Generic web app — the explicit NOT boundary in the description."
+  - prompt: "Write the privacy policy text for my app's data collection."
+    route_to: gdpr-privacy
+    why: "Legal copy; this skill only says where the privacy URL plugs into the store listing."
+  - prompt: "Build a cross-platform desktop app in Rust with a web frontend."
+    route_to: tauri
+    why: "Native desktop via Rust, not a Chrome extension."
+
+capability:
+  - scenario: "Scaffold a Manifest V3 extension that injects a content script on toolbar click (activeTab, not <all_urls>) and shows a click count in the popup that survives service worker restarts."
+    must_include:
+      - "manifest_version set to 3"
+      - "background.service_worker declared as a string (no background.scripts/page/persistent)"
+      - "activeTab permission rather than <all_urls> host_permissions"
+      - "count persisted with chrome.storage, not a background global variable"
+      - "event listeners registered synchronously at the top level"
+      - "chrome.scripting.executeScript or a declarative content_scripts entry"
+      - "icons (16/48/128) and a privacy/store note for shipping"

package/skills/chrome-extension/references/store-and-migration.md

@@ -0,0 +1,84 @@
+# Chrome Web Store submission + MV2→MV3 migration
+
+Two long branches offloaded from SKILL.md: getting through review, and dragging
+an old MV2 extension to MV3. Facts dated 2026-06-02 from developer.chrome.com.
+
+## Store submission, step by step
+
+1. **Register the developer account.** One-time **$5 USD** fee, covers up to 20
+   extensions on that account. Use a Google account you control long-term — it
+   owns the listings.
+2. **Prepare the package.** Build, then zip the **build output only** (`dist/`).
+   Strip `node_modules`, `.git`, README, and any source map you do not want
+   public. The zip's root must contain `manifest.json`.
+3. **Create the item** in the Developer Dashboard and upload the zip. Bump
+   `version` in `manifest.json` on every upload — the store refuses a duplicate
+   version.
+4. **Listing assets:**
+   - Icon: **128×128 PNG** (the store icon; separate from the toolbar icons).
+   - Screenshots: at least one, **1280×800 or 640×400 PNG/JPEG**. More is better
+     for conversion; show the actual UI, not marketing fluff.
+   - Optional promo tiles and a YouTube link.
+   - A clear, honest **description** and a **category**.
+5. **Privacy practices form.** You must disclose what data you collect and why,
+   certify you do not sell it for unrelated purposes, and provide a
+   **privacy-policy URL** if you collect any user data. The legal copy itself is
+   out of scope here — see `../gdpr-privacy/SKILL.md` and `../data-policy/SKILL.md`;
+   this skill only tells you the URL plugs into this form.
+6. **Permission justifications.** For each permission and each broad host match,
+   the form asks why. Write one concrete sentence per permission. Vague answers
+   ("for functionality") get rejected.
+7. **Submit.** Review is typically **1–3 business days**; simple extensions often
+   under 24h. You can use **staged rollout** to ship a new version to a
+   percentage of users first and halt if metrics tank.
+
+### Surviving review
+
+- Least privilege: every permission must map to a visible feature. `activeTab`
+  over `host_permissions`; specific origins over `<all_urls>`.
+- No remotely hosted code — bundle everything. Reviewers run static checks for
+  remote `<script src>` and `eval` of fetched strings.
+- Single clear purpose per extension; do not bundle unrelated features.
+- If rejected, the email names the policy. Fix the named issue, reply via the
+  **appeals** flow in the dashboard with what changed, and resubmit. Do not
+  silently re-upload the same package.
+
+## MV2 → MV3 migration map
+
+| MV2 | MV3 | Notes |
+|---|---|---|
+| `background.page` / `background.scripts` + `persistent: true` | `background.service_worker` (string), `"type": "module"` for imports | no DOM, no `window`; it terminates when idle |
+| long-lived global state in the background page | `chrome.storage` (+ `chrome.storage.session` for in-memory) | worker restarts wipe globals |
+| `setInterval` / `setTimeout` for periodic work | `chrome.alarms` | timers do not survive worker sleep |
+| blocking `chrome.webRequest` (modify/block requests) | `chrome.declarativeNetRequest` (static + dynamic rules) | DNR never sees request bodies; declare rule resources |
+| `chrome.tabs.executeScript(tabId, {code/file})` | `chrome.scripting.executeScript({ target: { tabId }, files })` | new signature; needs `scripting` permission |
+| `chrome.tabs.insertCSS` | `chrome.scripting.insertCSS` | same shape change |
+| remote `<script src>` / CDN libraries | bundle the library into the package | remote code is banned by MV3 CSP + policy |
+| `browser_action` / `page_action` | unified `action` | one toolbar entry point |
+| MV2-style host access by default | explicit `host_permissions` + prefer `activeTab` | broad hosts now warn loudly at install |
+
+### Migration order that works
+
+1. Flip `manifest_version` to `3` and convert `background` to a `service_worker`
+   string. Move every event listener to the top level, synchronous.
+2. Replace background-page globals with `chrome.storage` reads/writes.
+3. Swap timers for `chrome.alarms`.
+4. Convert `webRequest` blocking rules to `declarativeNetRequest` rule sets.
+5. Update every `tabs.executeScript`/`insertCSS` to the `scripting.*` signature
+   and add the `scripting` permission.
+6. Remove all remote code; bundle dependencies.
+7. Re-audit permissions — MV3 is the moment to drop `<all_urls>` for `activeTab`.
+
+## Recent platform notes (version-dated)
+
+- `chrome.userScripts.execute()` — Chrome 135 (Mar 2025): run dynamic,
+  user-supplied scripts under a dedicated permission.
+- `chrome.sidePanel.getLayout()` — Chrome 140 (Sep 2025).
+- `chrome.storage` viewer/editor in DevTools — Chrome 132 (Jan 2025): inspect
+  extension storage without a debug page.
+- Cross-browser `browser` namespace exposed in Chrome — Chrome 148 (May 2026):
+  the `browser.*` promise-based namespace now works in Chrome too, easing
+  Firefox/Edge portability.
+
+(Source: developer.chrome.com "What's new in Chrome extensions", accessed
+2026-06-02.)

package/skills/chrome-extension/scripts/verify.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# verify.sh — lint a Manifest V3 manifest.json against MV3 invariants.
+# Read-only. Exits 0 on a clean/empty target (no manifest = nothing to check).
+# Usage: scripts/verify.sh [target-dir]   (defaults to current directory)
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "verify.sh: node not found; skipping manifest lint." >&2
+  exit 0
+fi
+
+# Find manifest.json files, ignoring build/vendor dirs. No matches => clean pass.
+MANIFESTS="$(
+  find "$TARGET" \
+    -type d \( -name node_modules -o -name dist -o -name .git \) -prune -o \
+    -type f -name manifest.json -print 2>/dev/null
+)"
+
+if [ -z "$MANIFESTS" ]; then
+  echo "verify.sh: no manifest.json under '$TARGET' — nothing to check."
+  exit 0
+fi
+
+FAIL=0
+while IFS= read -r m; do
+  [ -z "$m" ] && continue
+  node - "$m" <<'NODE' || FAIL=1
+const fs = require("fs");
+const path = process.argv[2];
+const errs = [];
+let mf;
+try {
+  mf = JSON.parse(fs.readFileSync(path, "utf8"));
+} catch (e) {
+  console.error(`FAIL ${path}: invalid JSON — ${e.message}`);
+  process.exit(1);
+}
+if (mf.manifest_version !== 3) errs.push(`manifest_version must be 3 (got ${JSON.stringify(mf.manifest_version)})`);
+const bg = mf.background || {};
+if ("scripts" in bg) errs.push("background.scripts is MV2; use background.service_worker (string)");
+if ("page" in bg) errs.push("background.page is MV2; use background.service_worker (string)");
+if ("persistent" in bg) errs.push("background.persistent does not exist in MV3; remove it");
+if (mf.background !== undefined) {
+  if (typeof bg.service_worker !== "string") errs.push("background.service_worker must be a string");
+}
+if (typeof mf.name !== "string" || !mf.name) errs.push("missing name");
+if (typeof mf.version !== "string" || !mf.version) errs.push("missing version");
+if (mf.icons === undefined || typeof mf.icons !== "object") errs.push("missing icons");
+if (errs.length) {
+  console.error(`FAIL ${path}:`);
+  for (const e of errs) console.error(`  - ${e}`);
+  process.exit(1);
+}
+console.log(`OK   ${path}`);
+NODE
+done <<EOF
+$MANIFESTS
+EOF
+
+exit "$FAIL"

package/skills/clarify/SKILL.md

@@ -0,0 +1,159 @@
+---
+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)."
+tags: [sdd, clarify, questions]
+recommends: [plan]
+profiles: [core, full]
+origin: risco
+---
+
+# Clarify — the de-risking gate before planning
+
+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.
+
+## When to use / when NOT to use
+
+Use when:
+
+- 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.
+
+## Read first — the inputs
+
+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.
+
+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.
+
+## The ambiguity taxonomy — where specs hide their gaps
+
+Scan the spec against these categories. Most real gaps fall into one of them; walking the list is how you find the ones the author didn't think to write down.
+
+| Category | What to hunt | Tell-tale phrasing in the spec |
+| --- | --- | --- |
+| **Underspecified behavior** | A described feature with a missing branch — what happens in the *other* case | "the user logs in" (and if it fails? locked out? wrong password vs no account?) |
+| **Unstated assumptions** | Defaults the author assumed everyone shares | no mention of auth, tenancy, currency, timezone, locale |
+| **Edge & boundary cases** | Empty, zero, max, duplicate, concurrent, first-run, offline | lists with no empty-state, counts with no upper bound |
+| **Ambiguous terms** | A word doing two jobs | "user" (end-user or admin?), "delete" (soft or hard?), "fast" (how fast?) |
+| **Missing acceptance criteria** | A goal with no observable done-condition | "should be performant", "easy to use", "handle errors gracefully" |
+| **Scope edges** | What's explicitly OUT vs left dangling | features hinted at but never bounded — "for now", "eventually" |
+| **Data & state** | Lifecycle, ownership, retention, migration of existing data | new entity with no story for what happens to old records |
+| **Failure & recovery** | What happens when a dependency is down, a write half-completes, input is hostile | happy-path-only flows |
+| **Non-functional** | Performance, scale, security, accessibility, i18n targets | vague "non-functional requirements" or none at all |
+| **Actors & permissions** | Who can do each thing | a verb with no subject — "can be edited" (by whom?) |
+
+You are not filling every cell for every spec. You are scanning all ten so the gaps that *do* exist surface instead of hiding.
+
+## The pass — five steps
+
+Run in order. The discipline is: find many candidate gaps, keep only the ones that change the build, ask those well, write the answers back.
+
+1. **Inventory.** Walk the spec against the taxonomy above. Produce a raw list of every candidate ambiguity, edge case, and unstated assumption. Over-collect here; you'll prune next. Note for each which category it is and where in the spec it lives.
+
+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).
+
+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.
+
+5. **Bake the answers back into the spec.** This is the deliverable. 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.
+
+## 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.
+
+## Worked micro-example
+
+Spec line: *"Users can upload a profile photo."*
+
+Clarify's inventory against the taxonomy:
+
+```text
+- Ambiguous term  : "photo" — which formats? (PNG/JPG/HEIC/SVG?)
+- Boundary        : max file size? max dimensions? what if it's 50 MB?
+- Edge case       : no photo uploaded — is there a default/placeholder?
+- Failure         : upload fails mid-transfer — retry, or lose it?
+- Data lifecycle  : replacing a photo — is the old file deleted or orphaned?
+- Actors          : can an admin change another user's photo?
+- Non-functional  : is the image resized/compressed server-side? stored where?
+- Security        : is the file type validated, or can someone upload an .svg with script?
+```
+
+Resolved-internally (cite): constitution fixes storage to the project's object store → "stored where" is answered. Must-ask, ranked: formats + max size (changes validation and UX), security validation (changes the upload path), old-file deletion (changes data model). Cosmetic placeholder choice → propose a default, don't burn a question on it.
+
+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
+
+| Rationalization | Reality / fix |
+| --- | --- |
+| "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).
+
+## Next in the chain
+
+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.
+
+## See Also
+
+- `../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).
+
+## 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/clarify/evals/README.md

@@ -0,0 +1,70 @@
+# Eval harness — `clarify` skill
+
+These evals check two things: that the skill **triggers** on the right prompts
+(and stays quiet on near-misses that belong to a neighbouring SDD phase), and
+that it **measurably improves** the de-risking pass over a spec. Cases live in
+`cases.yaml`. There is no pure shell runner — grading is a judgment call done by
+an **agent harness** (a Claude Code agent with the skill catalog loaded) plus a
+human spot-check.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `clarify` (a spec exists; the user
+  wants it de-risked / hole-poked / readiness-checked before planning).
+- `should_not_trigger` — near-misses routed to the genuinely correct sibling
+  via `route_to` (`specify`, `plan`, `analyze`, `debug`, `constitution`).
+- `capability` — a scenario with a `must_include` rubric to grade WITH vs
+  WITHOUT the skill loaded.
+
+## Triggering eval
+
+Goal: the skill fires when a spec needs de-risking, and never on an adjacent
+SDD phase.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing — the SDD chain siblings (`specify`, `plan`, `analyze`, `debug`,
+   `constitution`, and the rest) plus the stack/process skills (`harness`,
+   `init`, `fastapi`, `nextjs`, `go`, `postgresdb`, `flutter`, `design`,
+   `marketing`, …) so routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold and record whether `clarify`
+   is the skill loaded. Run **3–5 trials** per prompt with fresh context.
+3. For each `should_not_trigger` prompt: confirm `clarify` does NOT load and
+   that 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 `specify` and `plan` near-misses — those are
+the known traps. The boundary clarify must hold: no-spec-yet is `specify`,
+how-to-build-it is `plan`. If it grabs either, the description is leaking.
+
+## Capability eval
+
+Goal: prove the skill changes the de-risking pass, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `clarify` loaded).
+   - **WITH** the `clarify` skill loaded.
+2. Grade each output against the `must_include` checklist — one point per
+   checkable item covered. A human or grading agent marks each present / absent.
+3. Compute coverage = `items_covered / total_items` per run.
+
+**Pass bar: WITH the skill covers ≥ 80% of `must_include`; WITHOUT clearly
+lower** (target a ≥ 30-point gap). The discriminating behaviors are the ones a
+base agent reliably misses: reading the constitution and citing what's already
+resolved, ranking gaps by leverage instead of dumping every question, framing
+questions as decisions-with-a-recommendation, and — the highest-signal item —
+actually **baking answers back into the spec with a dated Clarifications log**
+rather than just listing questions in chat.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The single highest-signal capability check is **the edit-back**: an answer
+  that asks good questions but never modifies the spec or records the reasoning
+  is a capability failure even if the questions are sharp. Clarify's deliverable
+  is the sharpened spec, not the conversation.
+- A second tell: a base agent often slides into proposing *how to build* the
+  feature. A correct clarify pass stays on WHAT and defers HOW to `plan`. Treat
+  architecture suggestions as a scope-leak failure.
+- Re-run after any edit to `SKILL.md` — wording changes shift both triggering
+  (especially the `specify`/`plan` boundary) and rubric coverage.