@ericrisco/rsc 1.0.10 → 1.0.12

package/skills/deprecation/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: deprecation
+description: "Use when retiring a public API, feature, integration, service or legacy path without abandoning consumers. Inventories usage, classifies advisory vs compulsory migration, ships compatibility/tooling, assigns owners and gates removal on evidence. NOT live schema expand-contract (`db-migrations`), NOT replacement API design (`api-design`)."
+tags: [deprecation, migration, compatibility, consumer-migration, removal]
+recommends: [api-design, db-migrations, deployment, git-workflow, monitoring]
+profiles: [core, full]
+origin: risco
+---
+
+# deprecation — removal is a consumer migration
+
+Deprecation is not a date in a changelog. It is the controlled transfer of real consumers from an old contract to a supported replacement, followed by evidence that removal no longer breaks anyone important.
+
+This skill owns the cross-consumer program. It delegates the replacement interface to `../api-design/SKILL.md`, live schema mechanics to `../db-migrations/SKILL.md`, release/version mechanics to `../git-workflow/SKILL.md`, and rollout/rollback execution to `../deployment/SKILL.md`.
+
+## The retirement sequence
+
+```text
+INVENTORY → CLASSIFY → ENABLE → NOTIFY → MIGRATE → OBSERVE → REMOVE
+```
+
+### 1. INVENTORY the contract and consumers
+
+Identify:
+
+- exact endpoints, events, schemas, flags, SDK methods, jobs, services and docs being retired;
+- internal and external consumers, owners and contractual notice periods;
+- traffic/usage by consumer, version and operation;
+- data written only by the old path and compatibility obligations;
+- support, reseller or offline consumers invisible to runtime telemetry;
+- current fallback and restoration options.
+
+“No known users” is not an inventory. Query telemetry, code search, dependency graphs, access keys, support records and account owners. Record where visibility is incomplete.
+
+### 2. CLASSIFY the migration
+
+- **Advisory:** the old path remains supported; migration is encouraged for benefit or future-proofing.
+- **Compulsory:** support will end or continued use creates unacceptable security, reliability, legal or operating risk.
+
+Only compulsory migrations justify a removal deadline. State the forcing reason and who has authority to accept exceptions. A deadline should respect contracts, effort and evidence; do not import a universal 30/60/90-day calendar.
+
+### 3. ENABLE migration before announcing removal
+
+The replacement must be usable first:
+
+- compatible contract or adapter where feasible;
+- migration guide with old → new mappings and changed semantics;
+- tooling, codemod, SDK or dual-write/read path for repetitive work;
+- test/sandbox path and representative examples;
+- rollback or temporary compatibility mode;
+- ownership for data backfill and reconciliation.
+
+For database changes, use expand → backfill → switch reads/writes → contract through `../db-migrations/SKILL.md`. Do not promise a generic `down` migration for irreversible data transformations; prove the actual restoration/reconciliation path instead.
+
+### 4. NOTIFY through machine and human channels
+
+Use the channels the consumer will actually see: response headers, compiler/runtime warnings, API dashboards, release notes, direct account contact, support and status communications. A warning must name the replacement, action, consequence, evidence link and earliest removal condition.
+
+Versioned public APIs should follow their compatibility policy and SemVer where it applies. Machine warnings without a migration guide create noise; an email without runtime identification misses the real owner. Use both when the surface permits.
+
+### 5. MIGRATE with explicit ownership
+
+The team introducing the deprecation owns the common migration path: inventory, docs, automation, default internal consumers and escalation. Consumer teams own domain-specific acceptance and scheduling, not rediscovering the replacement.
+
+Track each consumer as: uncontacted, acknowledged, testing, migrated, exempted with expiry, unreachable, or blocked. Give blockers an owner and next action. Reseller-managed or unknown consumers need a separate reachability plan; do not silently exclude them from the denominator.
+
+### 6. OBSERVE real cutover
+
+Instrument old-path usage by consumer and operation, plus errors on the replacement. Where risk warrants it, shadow or dual-run and compare results before switching authority. Dashboards must distinguish legitimate residual traffic, retries and synthetic probes from active dependency.
+
+Define the removal gate up front, for example:
+
+- no non-exempt production use for a representative window;
+- every contractually covered consumer notified and migrated or explicitly exempted;
+- replacement error/SLO health acceptable;
+- rollback/compatibility response tested;
+- support, docs and on-call ready for late discoveries.
+
+The representative window depends on consumer cadence. A monthly batch needs more than a quiet week.
+
+### 7. REMOVE in a reversible order
+
+Disable entry first, observe, then delete implementation, flags, compatibility code, credentials, dashboards and documentation that exist only for the old path. Preserve audit/history records. Update dependency and ownership maps so the retired system does not remain a zombie operational obligation.
+
+If unexpected material traffic appears, re-enable the bounded compatibility path and return to migration. Do not restore an undocumented permanent fork.
+
+## Deprecation record
+
+```markdown
+# Deprecation — <old> → <replacement>
+
+## Classification and reason
+Advisory/compulsory · forcing reason · authority · notice constraints.
+
+## Inventory
+Contracts · consumers · owners · baseline usage · visibility gaps.
+
+## Migration path
+Compatibility · guide/tooling · data plan · rollback/reconciliation.
+
+## Consumer ledger
+Consumer · state · owner · last old-path use · blocker/exception expiry.
+
+## Removal gate and evidence
+Window · zero-use evidence · replacement health · support/rollback readiness.
+
+## Removal log
+Disabled · observed · deleted · residual artifacts.
+```
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| The calendar arrives while material traffic remains | Hold removal; the gate is evidence, not date alone. |
+| Every consumer writes the same adapter | The deprecating team owns common tooling and default migrations. |
+| Internal code search proves external zero-use | Combine runtime identity, contracts, support and account ownership. |
+| Temporary compatibility has no owner or expiry | Track an explicit exception with accountable owner and end condition. |
+| Deprecation silently grants deploy authority | Keep live rollout/rollback explicit through `deployment`. |
+
+## 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/deprecation/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — deprecation
+
+Routing separates the consumer-migration program from schema mechanics, replacement API design, Git versioning, deployment and ADR authoring. The capability case requires consumer completeness, contractual timing, migration enablement, multichannel notice, measured cutover and a reversible removal sequence.

package/skills/deprecation/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: deprecation
+
+should_trigger:
+  - prompt: "We need to retire the v1 public API without stranding 200 external consumers."
+    why: "Public contract retirement with consumer migration is the core workflow."
+  - prompt: "Planifica la retirada del login legado: inventario, avisos, migración, telemetría y puerta de borrado."
+    why: "Spanish request names the complete deprecation program."
+  - prompt: "This SDK method is deprecated; ship a codemod and prove no supported clients still call it before removal."
+    why: "Migration tooling plus measured zero-use gate."
+  - prompt: "Hem de retirar una integració antiga, però alguns clients només executen un batch mensual."
+    why: "Catalan case where the observation window must match consumer cadence."
+  - prompt: "Classify this migration as advisory or compulsory and define who can grant expiring exceptions."
+    why: "The forcing model and exception authority are deprecation decisions."
+  - prompt: "Track every consumer from uncontacted to migrated and gate deletion on replacement health and tested rollback."
+    why: "Consumer ledger and evidence-based removal gate."
+
+should_not_trigger:
+  - prompt: "Add a nullable column, backfill ten million rows in batches, then enforce NOT NULL without downtime."
+    route_to: db-migrations
+    why: "Concrete live schema expand-contract mechanics."
+  - prompt: "Design the v2 API resources, error envelope, pagination and OpenAPI contract."
+    route_to: api-design
+    why: "Replacement interface design precedes the migration program."
+  - prompt: "Choose the SemVer tag and write the Conventional Commit for this breaking release."
+    route_to: git-workflow
+    why: "Version and Git release conventions."
+  - prompt: "Deploy the compatibility adapter to production with a healthcheck and rollback command."
+    route_to: deployment
+    why: "Authorized live rollout execution."
+  - prompt: "Write an ADR explaining why the team chose v2 over extending v1."
+    route_to: decision-records
+    why: "Durable decision rationale, not consumer migration execution."
+
+capability:
+  - scenario: "Deprecate a v1 REST API used by 200 organizations; v2 is live, current telemetry sees 173 active keys, twelve accounts are reseller-managed, and the largest contract requires 90 days' notice."
+    must_include:
+      - "Inventories exact v1 surfaces, all consumer classes, owners, contractual notice, baseline usage, data obligations, and telemetry/reachability gaps."
+      - "Classifies advisory versus compulsory with a forcing reason, authority, and expiring exception policy rather than an arbitrary universal timeline."
+      - "Makes v2 usable first through compatibility, guide, tooling/SDK, test path, data reconciliation, and a real restoration strategy."
+      - "Uses both machine-visible warnings and direct human channels, including a plan for reseller-managed and unreachable consumers."
+      - "Maintains a per-consumer migration ledger and assigns common migration work to the deprecating team rather than every consumer."
+      - "Defines a representative zero-use and replacement-health removal gate, then disables, observes, and deletes in reversible order."

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."