@ericrisco/rsc 1.0.9 → 1.0.11

package/skills/idea-refinement/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: idea-refinement
+description: "Use when a rough product, service, workflow or feature idea needs divergent options and assumption pressure-testing before it becomes a spec. Produces a decision brief with alternatives, evidence gaps, Not Now and a cheap experiment. NOT requirements or acceptance criteria (`specify`), NOT market sizing (`market-research`)."
+tags: [ideation, idea-refinement, product-discovery, assumptions, decision-brief]
+recommends: [specify, market-research, competitor-watch, ab-testing]
+profiles: [core, full]
+origin: risco
+---
+
+# idea-refinement — make the idea earn its direction
+
+Use this before `specify`, while the question is still “which version of this idea is worth pursuing?” The output is not a backlog or a polished pitch. It is a short decision brief that widens the option space, exposes what is merely assumed, and recommends the cheapest sensible direction to test.
+
+Inspect any brief, notes, product or repository already supplied before asking questions. Ask one question at a time only when the answer would change the option space. The user may delegate a choice; “use your judgment” is valid authority when the decision is reversible and the assumptions are made visible.
+
+## The refinement loop
+
+```text
+FRAME → DIVERGE → CHALLENGE → CONVERGE → TEST
+```
+
+### 1. FRAME the real opportunity
+
+Write five lines, no solution language yet:
+
+- **Actor:** who is struggling, in what situation?
+- **Current workaround:** what do they do now, including “do nothing”?
+- **Desired progress:** what observable change would make this useful?
+- **Constraints:** time, money, channel, trust, regulation, existing product.
+- **Known / assumed:** separate evidence already seen from hypotheses that only sound plausible.
+
+If the idea is phrased as a feature (“an AI dashboard”), reframe it as a problem and outcome (“operators need to spot failed jobs before customers report them”). Keep the original idea as one candidate, not as the conclusion.
+
+### 2. DIVERGE deliberately
+
+Produce **five to eight meaningfully different directions**. Variants that only change colors, names, pricing tiers or implementation technology count as one direction.
+
+Choose two lenses that attack the largest uncertainty:
+
+- **Remove / replace / combine / reverse:** change the mechanism, not the wording.
+- **Job and workaround:** improve, automate or eliminate the thing people already do.
+- **Constraint inversion:** assume the budget, time, data or integration is unavailable.
+- **Trust ladder:** begin with advice, then approval, then automation; do not jump to full autonomy.
+- **Pre-mortem:** imagine the idea failed in six months and design away the most likely cause.
+- **Narrow wedge:** find the smallest audience and moment where the pain is strongest.
+
+For each direction give: target actor, promised progress, mechanism, largest assumption, and what makes it distinct. Do not advocate yet.
+
+### 3. CHALLENGE the attractive options
+
+Take the three strongest directions and try to disprove them. Check:
+
+- Does the pain happen often and cost enough to change behaviour?
+- Does the user control the data, budget and permissions the idea requires?
+- Is the proposal replacing a habit or tool with a worse switching cost?
+- What dependency, incentive or trust failure could make the value impossible?
+- Which claim could be tested this week without building the product?
+
+State the strongest objection fairly. If an option survives only because a critical fact is unknown, label it **unverified**, not “promising.” Route market-size and demand evidence to `../market-research/SKILL.md`; route a named-rival comparison to `../competitor-watch/SKILL.md`.
+
+### 4. CONVERGE with explicit criteria
+
+Choose three to five criteria that fit the situation, then compare the finalists on the same scale. Typical criteria are user value, evidence strength, time to learning, reversibility, distribution access and operational risk. Weight only when one criterion genuinely dominates; decorative arithmetic is not evidence.
+
+Make one recommendation with:
+
+- the direction and the dominant reason;
+- confidence: high / medium / low;
+- assumptions it depends on;
+- what was rejected and why;
+- the fact that would most likely reverse the choice.
+
+If two options remain genuinely tied, recommend the experiment that distinguishes them. Do not ask the user to choose between indistinguishable summaries.
+
+### 5. TEST before specifying
+
+Name the cheapest next test that can change the decision: five problem interviews, a concierge workflow, a fake-door measure with consent, a manual prototype, a pricing conversation, or a data audit. Define the signal that would support the direction and the signal that would kill it.
+
+Only after a direction survives does it hand off to `../specify/SKILL.md` for goals, scope, behaviour and acceptance criteria.
+
+## Decision brief
+
+```markdown
+# Idea decision — <working title>
+
+## Opportunity
+Actor · workaround · desired progress · constraints
+
+## Evidence and assumptions
+- Seen: ...
+- Assumed: ...
+
+## Directions considered
+1. ...
+
+## Comparison
+Same criteria across the three finalists.
+
+## Recommendation
+Direction · confidence · deciding reason · reversal fact.
+
+## Not Now
+Ideas deliberately excluded from the first test.
+
+## Next experiment
+Method · audience · support signal · kill signal · timebox.
+```
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| Brainstorming becomes an implementation plan | Stop at direction + falsifier; `plan` comes after an approved spec. |
+| A long questionnaire precedes any thinking | Inspect first; ask one decision-changing question at a time. |
+| A score hides missing evidence | Put the evidence gap beside the score and lower confidence. |
+| The starting idea returns as cosmetic variants | Change mechanism, trust, audience, workflow or constraint. |
+| Ideation continues after direction and falsifier are clear | Stop and run the cheapest distinguishing experiment. |
+
+## 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/idea-refinement/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — idea-refinement
+
+Routing must distinguish exploration before commitment from `specify`, market evidence, competitor monitoring, task breakdown and experiment statistics. The capability case passes only when the answer widens the idea space, attacks assumptions, converges transparently and ends with a falsifiable cheap experiment rather than a polished feature spec.

package/skills/idea-refinement/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: idea-refinement
+
+should_trigger:
+  - prompt: "I have a vague idea for helping remote teams share what they know; explore several versions before we spec it."
+    why: "A rough product idea needs divergent directions and a choice before requirements."
+  - prompt: "No quiero que me des la razón: abre opciones y destroza los supuestos de esta idea de onboarding."
+    why: "Spanish request for option generation and assumption pressure-testing."
+  - prompt: "Tenemos una idea de automatizar soporte, pero aún no sabemos si debería aconsejar, pedir aprobación o actuar sola."
+    why: "The trust ladder is the key unresolved product direction."
+  - prompt: "Fes un pre-mortem de la idea i proposa cinc enfocaments realment diferents abans de triar-ne un."
+    why: "Catalan request for pre-mortem plus meaningful divergence."
+  - prompt: "Turn this feature-shaped idea into a problem, alternatives, Not Now list, and the cheapest experiment."
+    why: "Names the complete refinement artifact and test handoff."
+  - prompt: "We keep circling three product concepts; compare them on evidence, reversibility, and time to learning."
+    why: "Convergence across explicit criteria is owned here."
+
+should_not_trigger:
+  - prompt: "Write the approved feature spec with user stories and acceptance criteria."
+    route_to: specify
+    why: "The direction is chosen and now needs the WHAT/WHY contract."
+  - prompt: "Size the European payroll market with TAM, SAM, SOM and dated sources."
+    route_to: market-research
+    why: "Defensible market sizing and demand evidence, not ideation."
+  - prompt: "Track what Notion and Slite shipped this quarter and compare their moves."
+    route_to: competitor-watch
+    why: "Standing named-competitor intelligence."
+  - prompt: "Break the notifications spec into dependency-ordered implementation tasks."
+    route_to: tasks
+    why: "Execution decomposition occurs after spec and plan."
+  - prompt: "Design the sample size and guardrail metrics for our landing-page experiment."
+    route_to: ab-testing
+    why: "The direction is already an experiment needing statistical design."
+
+capability:
+  - scenario: "Refine a rough idea for an AI assistant that helps small agencies capture project knowledge without creating more admin work."
+    must_include:
+      - "Reframes the feature idea as actor, current workaround, desired progress, constraints, and separate evidence versus assumptions."
+      - "Produces five to eight materially different directions, including different trust or workflow mechanisms rather than cosmetic variants."
+      - "Pressure-tests the strongest directions for adoption, data, permission, switching-cost, dependency, and failure assumptions."
+      - "Compares finalists against the same explicit criteria and recommends one with confidence and a fact that could reverse the decision."
+      - "Includes a Not Now list so discarded scope does not leak into the first experiment."
+      - "Defines one cheap next experiment with both a support signal and a kill signal, then hands the survivor to specify."

package/skills/observability/SKILL.md

@@ -14,6 +14,10 @@ You are wiring the *inside* view of a service: when something breaks at 3am, an
 
 **Every signal carries the same correlation identity: `trace_id`, `service.name`, `deployment.environment`.** A log line you cannot pivot to its trace, or a spiking metric you cannot pivot to an exemplar span, doubles your mean-time-to-resolution — you are back to grepping. Three signals that don't share keys are three disconnected tools; three that do are one queryable system. Set the resource once at SDK init, inject `trace_id`/`span_id` into every log, and never emit a metric you can't tie back to a service and environment.
 
+## Start from the operator's questions
+
+Before choosing signals, write **two to four questions on-call must answer during the likely incident**. For example: “Are payment retries recovering?”, “Which dependency and failure class drives exhaustion?”, “Can one payment be charged twice?”, “Which customer-visible operations need intervention now?” Then assign the cheapest signal: metrics say **that/how much**, traces show **where/causal path**, logs explain **why for this event**. If a proposed event or label answers none of the questions, do not emit it.
+
 ## The three pillars — when each earns its place
 
 Don't emit all three of everything. Each signal answers a different question at a different cost.
@@ -227,3 +231,5 @@ The instrumentation above makes these *possible* — defining them is your job;
 ## Verify
 
 Run `scripts/verify.sh` against the directory holding your Collector config + SDK init. It checks the config is valid, that every defined exporter is actually wired into a pipeline (the classic "defined but unused" footgun), that `service.name` is set, and warns on high-cardinality metric labels. It is read-only and exits 0 when there's nothing to check.
+
+Then prove the wire with one safe induced failure in a test/staging path. Confirm the expected error-rate metric changes, the trace records the failing operation and error status, and the structured log carries the same `trace_id` without PII. Query the backend/Collector output; “the instrumentation code ran” is not evidence that usable telemetry arrived. Live paging and escalation proof remains `../monitoring/SKILL.md`.

package/skills/observability/evals/cases.yaml

@@ -47,3 +47,5 @@ capability:
       - a multi-window SLO burn-rate alert defined from the emitted metrics
       - respects the cardinality rule (no user_id/request_id/email as a metric label) and logs no PII (opaque ids, redaction in the Collector)
       - exports through a Collector via OTLP, not straight to a vendor
+      - starts from two to four concrete on-call questions and maps metrics to that/how much, traces to where, and logs to why
+      - induces one safe failure and proves the correlated metric, error trace, and structured log actually arrive without PII

package/skills/performance/SKILL.md

@@ -41,6 +41,16 @@ You have two kinds of measurement and they answer different questions. Use both,
 
 The output of Step 0 is **one sentence naming the bottleneck**: "LCP is 3.8 s and 2.1 s of it is resource load delay because the hero image is lazy-loaded." Do not proceed without that sentence. Tool runbooks (Lighthouse CI flags, reading a flame chart, the Profiler workflow, wiring `web-vitals` for RUM) live in `references/profiling-playbook.md`.
 
+**Measurement honesty:** static source can identify a *plausible* bottleneck, never a measured LCP/INP/CLS, latency win or byte saving. If runtime/field data is unavailable, label the finding `POTENTIAL`, name the exact trace/benchmark needed, and make no numeric improvement claim. Do not turn code inspection into fictional telemetry.
+
+Keep one experiment card per change:
+
+```text
+metric + conditions | baseline distribution | one hypothesis/change | after distribution | keep/revert | next
+```
+
+Use the same device, data volume, cache state, build mode and sampling method before and after. Repeat enough runs to see ordinary variance; a one-off result inside that noise is neutral. Keep a change only when it moves the target beyond the noise without violating another budget. Revert a neutral or worse experiment with a targeted edit and preserve the card — failed attempts prevent the next person from paying for the same guess.
+
 ## CWV "good" thresholds (field p75)
 
 | Metric | Good | Needs improvement | Poor |
@@ -210,6 +220,9 @@ Use **streaming SSR with `<Suspense>`** to flush the static shell immediately an
 | Images/embeds with no reserved space | content reflows on load → CLS | explicit width/height or `aspect-ratio` |
 | Micro-optimizing a non-bottleneck phase | effort moves a number off the critical path | fix only the phase the trace points at |
 | "Done" without re-measuring | the fix may not have moved the metric | re-measure against the threshold, then stop |
+| Reporting source-only review as a measured win | no trace/field/benchmark ran, so the number is invented | label POTENTIAL and name the measurement |
+| Changing three levers in one experiment | you cannot attribute the result or reuse the learning | one hypothesis/change per card, then re-measure |
+| Keeping a neutral optimization | complexity rose but the target did not beat normal variance | targeted revert; retain the failed-experiment record |
 
 ## Stop rule
 

package/skills/performance/evals/cases.yaml

@@ -45,3 +45,5 @@ capability:
       - "Proposes a concrete bundle cut — replace/remove a heavy dep, dynamic import() for non-critical UI, or fix a whole-library import — in payoff order."
       - "Does NOT blanket-memoize React components (notes React 19 compiler auto-memoizes) and does not guess fixes without the profile."
       - "Re-measures against the numeric targets (LCP ≤ 2.5s field p75 and a bundle budget) and stops at 'good' rather than gold-plating."
+      - "Never reports source inspection as a measured result; without runtime/field data it labels findings POTENTIAL and names the exact trace or benchmark required."
+      - "Records baseline conditions and variance, changes one lever, re-measures under the same conditions, and targeted-reverts neutral or worse experiments while preserving the failed-attempt record."

package/skills/simplify-code/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: simplify-code
+description: "Use when correct working code is unnecessarily hard to read, change or verify and needs behaviour-preserving simplification in a bounded scope. Characterizes the observable contract, removes accidental complexity one concept at a time and proves equivalence. NOT fixing a failure (`debug`), NOT read-only diff judgment (`review`/`code-review`)."
+tags: [code-simplification, refactoring, readability, complexity, behavior-preservation]
+recommends: [code-review, review, verify, debug, performance]
+profiles: [core, full]
+origin: risco
+---
+
+# simplify-code — fewer moving parts, same contract
+
+Use this when the code already works and the desired change is easier reasoning, not new behaviour. The output is a smaller or clearer implementation plus proof that callers cannot tell the difference.
+
+Default scope is the files or symbols the user named, or the recently changed slice. Expanding into adjacent cleanup requires a concrete dependency and must be stated. Never “clean the whole repository” as a side effect.
+
+## The equivalence loop
+
+```text
+BOUND → CHARACTERIZE → BASELINE → REDUCE → VERIFY → EXPLAIN
+```
+
+### 1. BOUND the work
+
+Record:
+
+- target files/symbols and why they are difficult;
+- callers and public interfaces that must remain stable;
+- generated/vendor code and project-marked protected regions to leave alone;
+- performance, ordering, compatibility or serialization constraints;
+- unrelated dirty-worktree changes that belong to someone else.
+
+Respect protected regions through repository instructions and explicit comments. Do not hide them by rewriting files on disk, swapping placeholders in and out, or relying on a cleanup hook to restore them later.
+
+### 2. CHARACTERIZE the observable contract
+
+Tests are necessary but may be incomplete. Write down what must remain the same:
+
+- return values and data shapes;
+- thrown/rejected error types, messages when contractual, and timing;
+- ordering, deduplication and mutation behaviour;
+- I/O, logs, analytics and other side effects;
+- async/concurrency semantics;
+- hot-path allocations or latency when performance is part of the contract.
+
+If the behaviour cannot be stated or observed, add characterization tests before refactoring. When the current behaviour is a bug, stop and route to `../debug/SKILL.md`; simplification must not smuggle in a fix.
+
+### 3. BASELINE current evidence
+
+Run the narrow tests first and preserve their output. Then run type/lint/build checks appropriate to the slice. For a performance-sensitive path, capture a representative benchmark under named conditions. A baseline proves what “same” means and prevents a cleaner-looking regression.
+
+### 4. REDUCE one source of accidental complexity
+
+Prefer changes with a visible reasoning payoff:
+
+- remove dead branches, duplicate calculations or needless state;
+- replace nested control flow with guard clauses when ordering stays identical;
+- extract a name for a real concept, not every three lines;
+- collapse pass-through wrappers that enforce no policy;
+- replace clever compact expressions with direct ones;
+- make data flow single-directional and ownership explicit;
+- reuse an existing local abstraction when it is simpler than both copies.
+
+Change one concept at a time and inspect the diff. Complexity moved into a new helper, generic abstraction or dependency is not removed. Lines of code are supporting evidence, never the target.
+
+Do not redesign a public API, rename unrelated symbols, update formatting across untouched files, add features, change error policy, or create a speculative framework “for future reuse.”
+
+### 5. VERIFY after every coherent step
+
+Run the focused characterization tests, then the relevant repository gate. Compare benchmark conditions when applicable; keep a performance claim only when the difference exceeds normal run-to-run noise. Review the diff specifically for contract drift and accidental scope growth.
+
+If a step is neutral or worse for understandability, revert **that step only** using a targeted edit. Never use `git reset --hard`, overwrite the working tree, or discard unrelated user changes. Do not commit automatically.
+
+### 6. EXPLAIN the gain
+
+Report:
+
+- scope simplified;
+- complexity removed, not merely relocated;
+- observable contract preserved;
+- tests/checks/benchmark run and results;
+- anything intentionally left complex and the invariant that justifies it.
+
+“Cleaner” is too vague. Prefer: “removed three mutable states and one duplicate parse; preserved error type/message, insertion order and one-read I/O semantics; 18 focused tests plus full typecheck pass.”
+
+## Stop rule
+
+Stop when another edit would trade one defensible style for another without lowering the number of states, branches, concepts or proof obligations. Readability has diminishing returns. A bounded, verified improvement is done even if neighbouring legacy code remains ugly.
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| A failing behaviour is “cleaned up” | Diagnose with `debug`; simplification must not smuggle in a fix. |
+| A read-only review starts editing | Keep verdict work in `review`/`code-review`. |
+| A speed hunch justifies a refactor | `performance` measures first; preserve a benchmark when speed is contractual. |
+| An odd public behaviour is silently normalized | Preserve it until a behaviour change is explicitly authorized. |
+| Cleanup commits, pushes, resets or deploys on its own | These are separate authorized operations; use targeted edits only. |
+
+## 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/simplify-code/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — simplify-code
+
+The cases distinguish correct-but-complex code from debugging, review, verification, performance and API redesign. The capability case requires an explicit behavioural contract, characterization baseline, one-concept reductions, full evidence and safe worktree handling.

package/skills/simplify-code/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: simplify-code
+
+should_trigger:
+  - prompt: "This parser works and its tests are green, but the nested branches are impossible to follow; simplify it without changing behavior."
+    why: "Correct code needs bounded behaviour-preserving simplification."
+  - prompt: "Simplifica esta función, pero conserva exactamente errores, orden y efectos laterales."
+    why: "Spanish request explicitly names observable contract preservation."
+  - prompt: "The feature is done; now remove the accidental complexity from only the files we changed."
+    why: "Post-feature bounded cleanup is the default scope."
+  - prompt: "Fes el codi menys enginyós i més directe, amb tests de caracterització abans de tocar-lo."
+    why: "Catalan request for characterization-led simplification."
+  - prompt: "Collapse these pass-through wrappers and duplicate state if callers cannot observe a difference."
+    why: "Specific removable complexity with an equivalence condition."
+  - prompt: "Refactor this hot path for clarity, but keep the benchmark and allocation profile within noise."
+    why: "Performance is part of the observable simplification contract."
+
+should_not_trigger:
+  - prompt: "The parser throws on valid quoted values; reproduce the bug and fix it."
+    route_to: debug
+    why: "Behaviour is incorrect, so diagnosis precedes any cleanup."
+  - prompt: "Review this pull request and list correctness issues, but do not edit it."
+    route_to: code-review
+    why: "Read-only spec-less diff judgment."
+  - prompt: "Verify the finished SDD implementation against every acceptance criterion."
+    route_to: verify
+    why: "Evidence gate rather than code editing."
+  - prompt: "The page is slow; profile Core Web Vitals and fix the measured bottleneck."
+    route_to: performance
+    why: "Measured speed work owns the task."
+  - prompt: "Redesign the public API and migrate all callers to the new contract."
+    route_to: api-design
+    why: "The requested behaviour/interface change is not simplification."
+
+capability:
+  - scenario: "Simplify an 80-line configuration parser whose current tests cover the happy path but whose callers depend on comment handling, quoting, numeric conversion, insertion order and ignored malformed lines."
+    must_include:
+      - "Bounds the target and inspects callers, dirty-worktree state, generated code, and explicit protected regions without mutating files to hide content."
+      - "States the observable contract including return shape, ignored input, type conversion, order, errors and side effects."
+      - "Adds characterization cases for uncovered contract edges and records a green baseline before refactoring."
+      - "Removes one source of complexity at a time without adding features, redesigning public APIs, or relocating complexity into speculative abstractions."
+      - "Runs focused tests plus relevant lint/type/build gates after coherent steps and compares a benchmark when performance is contractual."
+      - "Uses targeted edits for a bad step and never resets, auto-commits, pushes, deploys, or discards unrelated changes."

package/skills/solid-js/references/router-and-start.md

@@ -87,7 +87,7 @@ export default function Todos() {
 
 - **Deployment**: SolidStart uses Nitro-style adapters; for Vercel/Netlify/Node
   targets configure the adapter in `app.config.ts`. Deployment specifics →
-  [`../vercel/SKILL.md`](../vercel/SKILL.md).
+  [`vercel`](../../vercel/SKILL.md).
 
 Version note: SolidStart 1.x is the maintained stable line; **2.0.0-alpha** tracks
 Solid 2.0. Default to 1.x unless the task targets the alpha.

package/skills/source-grounded-development/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: source-grounded-development
+description: "Use when implementation or review depends on current version-specific framework, SDK, protocol or platform behaviour and memory is unsafe. Detects exact local versions, verifies primary sources, tests applicability and marks unknowns. NOT a standalone cited memo (`research-ops`), NOT diagnosis of a reproduced failure (`debug`)."
+tags: [official-docs, primary-sources, version-detection, implementation, verification]
+recommends: [research-ops, decision-records, debug, technical-writing]
+profiles: [core, full]
+origin: risco
+---
+
+# source-grounded-development — make current facts part of the change
+
+Use this when correctness depends on what a framework, SDK, API, standard or hosted platform **does now for the exact version in this repository**. The deliverable is still code, a review or an implementation decision; sources are the evidence behind it, not a separate essay.
+
+This is narrower than `../research-ops/SKILL.md`: research-ops answers an open question with a cited memo. Here, the question exists because a concrete change cannot safely proceed from memory.
+
+## The loop
+
+```text
+DETECT → QUESTION → SOURCE → APPLY → PROVE → REPORT
+```
+
+### 1. DETECT the actual version and environment
+
+Read the repository before the web:
+
+- lockfiles and manifests, not only a README;
+- runtime and compiler configuration;
+- generated client/server versions;
+- deployment target and enabled compatibility flags;
+- existing wrapper code that may override documented defaults.
+
+Record an evidence line such as: `Next 16.2.1 from pnpm-lock.yaml; Node 24 from .nvmrc; App Router; deployed to Vercel.` If versions conflict, stop treating the docs as applicable until the conflict is resolved.
+
+### 2. QUESTION only the claims that can change the implementation
+
+Build a small claim ledger. Each row is one decision-sensitive statement:
+
+```text
+claim | exact component/version | evidence needed | source | applicability | status
+```
+
+Examples: whether a callback is invoked on retry, the default cookie policy, an API’s idempotency semantics, a deprecated option’s replacement, or a browser feature’s support boundary. Do not cite obvious local code or generic programming facts just to make the list longer.
+
+### 3. SOURCE by authority and freshness
+
+Prefer, in order:
+
+1. the repository and installed type definitions for local truth;
+2. official versioned documentation and migration/release notes;
+3. specifications, RFCs or provider API references;
+4. upstream source or tests when documentation is ambiguous;
+5. reputable secondary material only as a lead, never as the final authority for a disputed behaviour.
+
+Use the current page that matches the detected version. A search snippet, an undated blog, a forum answer or remembered API shape is not proof. When two primary sources disagree, show the disagreement and test the behaviour; do not average them into false certainty.
+
+### 4. APPLY the source to this repository
+
+For every useful source, state why it applies here:
+
+- same major/minor version or a documented compatibility range;
+- same runtime, router, transport, deployment mode or feature flag;
+- no local wrapper/configuration that changes the default;
+- publication or update date appropriate to a fast-moving claim.
+
+Then make the smallest implementation decision that the evidence supports. Do not turn examples from docs into architecture by cargo cult. Examples demonstrate an API; the repository still determines ownership, boundaries and error policy.
+
+### 5. PROVE behaviour locally
+
+Documentation tells you intended behaviour. A local test proves the integration:
+
+- add or run a focused contract/regression test;
+- compile against installed types;
+- exercise a minimal reproduction when defaults or runtime order matter;
+- run the stack’s normal verification gate after the focused proof.
+
+If local evidence contradicts the source, preserve the reproduction and investigate version/config drift. Do not silently choose whichever result is more convenient.
+
+### 6. REPORT without polluting the code
+
+End with:
+
+- versions and environment detected;
+- material claims verified and their primary links;
+- implementation choices those claims changed;
+- local evidence run;
+- assumptions still **UNVERIFIED**, with the consequence if wrong.
+
+Put source links in the final report, PR description or a durable decision record when the rationale must outlive the task. Do not scatter documentation URLs through source comments unless the code’s invariant genuinely cannot be understood without that external contract.
+
+## Stop conditions
+
+Stop searching when every decision-sensitive claim is verified, contradicted or explicitly marked unverified and the local proof is green. Search breadth is not quality. A fifth article repeating the official reference adds no evidence.
+
+Do not use this skill as a reason to delay reversible work indefinitely. If a primary source is unavailable, name the uncertainty, choose the safest reversible option, add a proof/guard, and state what would trigger revisiting it.
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| A reproduced bug is replaced by a docs tour | `debug` owns diagnosis; use this only for the disputed versioned claim. |
+| A broad open question is forced into implementation | Route the cited memo to `research-ops`. |
+| A lasting architecture choice disappears into a task summary | Preserve it in `decision-records` with this ledger as evidence. |
+| A search result or secondary article is presented as official | Follow it to the primary source or mark the claim unverified. |
+| “Latest docs” are read before the lockfile | Detect the local version and mode first; then choose applicable docs. |
+
+## 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/source-grounded-development/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — source-grounded-development
+
+The routing cases separate version-sensitive implementation evidence from general research, debugging, ADRs, docs and security review. The capability rubric requires the full local-version → primary-source → applicability → local-proof chain and treats unverified deployment assumptions as visible risk.

package/skills/source-grounded-development/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: source-grounded-development
+
+should_trigger:
+  - prompt: "Before changing sessions, verify the installed Express and express-session versions against their official production guidance."
+    why: "A concrete implementation depends on current version-specific framework behaviour."
+  - prompt: "No te fíes de memoria: mira el lockfile y la documentación oficial de Stripe para comprobar la semántica de reintentos."
+    why: "Spanish request for local version detection and primary-source verification."
+  - prompt: "This SDK changed between majors; prove which callback contract applies to the version in this repo."
+    why: "A version boundary changes implementation correctness."
+  - prompt: "Comprova amb fonts primàries si aquesta opció està deprecada en la versió instal·lada i quin reemplaçament toca."
+    why: "Catalan request for official deprecation evidence tied to the installed version."
+  - prompt: "Implement the browser API only after checking its current specification and support boundary, then test the fallback."
+    why: "Protocol/browser behaviour requires primary evidence plus local proof."
+  - prompt: "Review this integration and cite the official pages behind every provider-specific claim that affects the verdict."
+    why: "A review depends on current provider contracts rather than recalled assumptions."
+
+should_not_trigger:
+  - prompt: "Research whether passkeys improve consumer login conversion and deliver a cited memo."
+    route_to: research-ops
+    why: "The artifact is a standalone research memo, not an implementation grounded in an installed version."
+  - prompt: "The checkout test fails on every third retry; reproduce it and find the root cause."
+    route_to: debug
+    why: "A concrete failure needs diagnosis; documentation may support but does not own the workflow."
+  - prompt: "Record why we selected Kafka over SQS and preserve the rejected alternatives."
+    route_to: decision-records
+    why: "Durable decision rationale is an ADR."
+  - prompt: "Write the public setup guide for our SDK users."
+    route_to: technical-writing
+    why: "The deliverable is documentation, not source-grounded implementation."
+  - prompt: "Audit this webhook handler for SSRF and secret leakage."
+    route_to: secure-coding
+    why: "Security threat/control review owns the task."
+
+capability:
+  - scenario: "Implement production session cookies for an application whose framework and session-library versions are pinned but whose deployment proxy behaviour is unclear."
+    must_include:
+      - "Reads lockfiles, runtime configuration, deployment target, and local wrappers before choosing documentation."
+      - "Creates a bounded claim ledger covering cookie defaults, proxy trust, secure transport, secret handling, and session-store production requirements."
+      - "Uses version-matching official docs, release/migration notes, specifications, or upstream source; secondary sources are not treated as final authority."
+      - "Explains why each material source applies to this runtime and flags deployment facts that remain unverified."
+      - "Adds or runs focused local proof plus the repository's normal verification gate instead of trusting documentation alone."
+      - "Reports citations in the result or decision record without filling ordinary source comments with URLs."

package/skills/suggest/evals/cases.yaml

@@ -59,7 +59,7 @@ capability:
       - "Checks what is already installed (npx @ericrisco/rsc list) and never proposes a skill the user already has"
       - "Makes at most one suggestion and does not interrupt the flow for nice-to-haves"
 
-  - scenario: "Mid-conversation, after base install, the user says 'quiero montar una pagina web para vender cursos online'. `init`, `harness`, `orient`, and `suggest` are already installed; `nextjs` is not. Show how rsc-suggest behaves."
+  - scenario: "Mid-conversation, after base install, the user says 'quiero montar una pagina web para vender cursos online'. `init`, `harness`, `orient`, `suggest`, and `bro` are already installed; `nextjs` is not. Show how rsc-suggest behaves."
     must_include:
       - "Treats the message as in-agent capability intent, not as a CLI-only consult task"
       - "Runs `npx @ericrisco/rsc catalog --available` to see the not-installed skills (already excludes installed `init`/`harness`)"