@damiangilgonzalez/harness 1.3.7

package/skills/level-design/references/guidance-and-readability.md

@@ -0,0 +1,152 @@
+# Guidance & readability — direct the player without hand-holding
+
+How to make a player always know where to go, understand what they can do, and
+feel clever for exploring — using the environment instead of arrows. Also
+covers the playtest protocol, traversal telemetry, and reward/secret placement,
+because those are how you *diagnose and fix* readability.
+
+## The layers of guidance (strongest to weakest)
+
+The eye is drawn, roughly in this priority, to: **motion → light/brightness →
+high contrast → saturated color → the different/odd → framed shapes.** Stack
+these on the path you want taken; strip them from paths you don't.
+
+### Light leads
+
+Players move toward light — the moth effect — and toward higher value contrast.
+
+- Light the **critical path, the objective, and the exit**; keep dead-ends,
+  non-paths, and cut branches dim.
+- A bright opening at the end of a dark corridor is an irresistible pull.
+- Use light *in greybox* as a design tool, not a final-art afterthought — the
+  guidance is authored in placeholder lighting and art merely honors it.
+- Contrast beats absolute brightness: a shaft of light in gloom guides harder
+  than a uniformly bright room.
+
+### Color as language
+
+Reserve **one saturated accent color** to mean "you can interact / go here" and
+use it *nowhere else*.
+
+- Precedents: Mirror's Edge's "runner red" for the traversal path; Dishonored's
+  faint glint on usable objects; the near-ubiquitous "yellow = climbable/grab"
+  convention.
+- The value of the convention *is its consistency*. The moment the interact
+  color appears on decoration, you've lied — the player learns to distrust it
+  and starts checking everything, which is the opposite of guidance.
+- Keep the rest of the palette desaturated relative to the accent so it pops.
+
+### Composition
+
+Compose the space like a photographer composes a shot.
+
+- **Leading lines** — rails, beams, roads, pipes, tiling that point toward the
+  objective.
+- **Framing** — arches, doorways, foreground silhouettes that box the eye onto
+  the target.
+- **Negative space** and **contrast** to isolate what matters.
+- From every decision point, the critical path should be the most-framed,
+  highest-contrast, best-lit option.
+
+### Affordances & signifiers
+
+(Norman/Gibson.) An affordance is what the environment *lets* you do; a signifier
+is the visual cue that advertises it.
+
+- A ledge that looks grabbable **must** be grabbable; a wall that looks solid
+  **must** be solid. A door-shaped thing that never opens teaches the player to
+  ignore doors.
+- Establish the visual language **early** and hold it: if a specific trim, decal,
+  or material means "climb here," that cue appears **only** where you can climb.
+- Inconsistent affordances are the #1 source of "I didn't know I could do that"
+  and "I thought I could do that and died." Consistency > cleverness.
+- Prefer **diegetic signifiers** (a rope, scuff marks, a worn path, a ladder)
+  over UI prompts; save prompts for genuinely non-obvious systemic actions.
+
+### Landmarks & self-location
+
+- One **dominant landmark** per area — a large, distinct, distant silhouette
+  (Disney's "weenie": the visual magnet that pulls you forward). It answers
+  "where am I / where's the goal" without a minimap.
+- Keep landmarks visible from key decision points; if the player can't see the
+  landmark when they need to choose, it isn't doing its job.
+- **Deny wrong turns visually** — subtle dead-ends, unlit gaps, a distinct
+  "not-a-path" material — rather than relying on invisible collision, which
+  feels arbitrary and cheap.
+
+### The critical-path readability self-test
+
+Stand at each decision point in the greybox and ask: *with no HUD and no prior
+knowledge, is the intended next step the most obvious thing here?* If you have
+to argue for it, a fresh player will get lost. Fix with light/framing/landmark
+before reaching for a waypoint.
+
+## Playtesting — observe, don't coach
+
+You cannot see your own level fresh; your knowledge of it is the one thing a
+player won't have.
+
+1. **Fresh, uncoached tester.** Say "play." Then stay silent.
+2. **Log four signals:**
+   - **Hesitation / stopping** → readability gap (they can't tell where to go).
+   - **Wrong turn / backtrack** → navigation gap (guidance points wrong or is
+     absent).
+   - **Repeated death** → telegraph or difficulty gap (threat unfair or
+     unreadable).
+   - **Skipped content** → reward-placement or guidance gap.
+3. **Never answer "where do I go?"** — that question *is* the finding. Answering
+   it destroys the data and hides the bug.
+4. **Ask after, not during**: "Where did you think you were supposed to go? What
+   did you expect that button to do? Where did you feel stuck?" Open questions,
+   no leading.
+5. Test on the **greybox**, early and often — fixes are cheap while it's grey.
+
+## Traversal telemetry & heatmaps
+
+Turn anecdote into pattern by logging player data across many sessions:
+
+| Metric | What it shows | The fix when it's bad |
+|---|---|---|
+| **Position heatmap** | Where players spend time; **cold zones** they never enter | Cold zone = dead space: re-light it, add a landmark/reward, or cut it |
+| **Death heatmap** | Where players die; **clusters** = unfair/unreadable threats | Fix the telegraph, the arena, or the difficulty — not the player |
+| **Path traces** | Are they on the golden path or lost? | Divergence from intended path = guidance failure at that fork |
+| **Dwell time** at forks | Long dwell = unclear guidance | Add light/framing/landmark to make the choice obvious |
+| **Look / aim heatmap** | Did they even *see* the landmark or reward? | If not looked-at, it's mis-placed or out-competed — reposition |
+| **Time-to-objective** | Pacing vs intent (too fast/slow) | Adjust distance, breather length, or beat spacing |
+
+Read the map as instructions: a branch nobody takes needs a visible reward at
+its mouth; a region everyone avoids isn't pulling them — fix the pull or remove
+the region.
+
+## Reward & secret placement
+
+- **Reward the wandering eye.** Put secrets where a *curious* player naturally
+  looks — behind the waterfall, up the ledge you already lit and framed, down
+  the branch you breadcrumbed. Reward **observation**, not pixel-hunting.
+- **Breadcrumb every secret.** A glint, an out-of-place object, a suspicious
+  seam, an odd bit of geometry visible from the path. The player should feel
+  clever — which means the game showed them the thread first. A secret with no
+  breadcrumb is just frustration.
+- **Never hide mandatory progression like a secret.** A required key or door
+  disguised as optional is a stuck-player generator. Secrets are optional by
+  definition; the critical path stays legible.
+
+## Risk vs reward
+
+- Gate the **best** optional reward behind the **biggest** optional risk or
+  detour — a hard side-arena, a long climb, a resource gamble, a no-checkpoint
+  stretch.
+- Keep the **critical path rewarding on its own** so risk-averse players aren't
+  punished for playing it safe; put the *extra* behind the *extra* effort.
+- Make the risk and the reward both *visible before committing* so the choice is
+  informed: the player should see the treasure across the deadly gap and decide.
+
+### Reward taxonomy (vary these so exploration stays fresh)
+
+| Type | Example | Notes |
+|---|---|---|
+| **Power / upgrade** | new ability, weapon, permanent buff | Strongest pull; use sparingly |
+| **Resources** | ammo, health, currency | Steady exploration incentive |
+| **Lore / collectible** | note, audio log, vista, cosmetic | For the curious; light them in breathers |
+| **Shortcut unlock** | a door back to the hub, a lowered ladder | Best long-term reward — reshapes the level, cuts backtracking |
+| **Spectacle** | a view, a scripted moment, an Easter egg | Pure delight; costs no systemic balance |

package/skills/level-design/references/pacing-and-encounters.md

@@ -0,0 +1,142 @@
+# Pacing & encounters — rhythm, arenas, and teaching through space
+
+A level is a piece of music, not a list of rooms. This reference covers the
+intensity graph, the breather, the difficulty curve, the encounter template, the
+introduce→develop→twist→combine teaching pattern, and arena-shape design.
+
+## The intensity graph
+
+Plot intended intensity (danger + cognitive load + stimulus) against time for
+the whole level. The target shape is a **sawtooth trending upward**: a peak
+(combat, chase, platforming gauntlet, tense stealth), a sharp drop to a valley
+(a breather), then a higher peak. Overall the line climbs, ending on the level's
+hardest, most spectacular moment.
+
+```text
+intensity
+  ^                                        ___/\   <- climax (hardest, last)
+  |            ___/\           ___/\      /
+  |     __/\  /     \    __/\  /     \___/
+  |  __/    \/       \__/    \/            <- breathers (valleys)
+  +---------------------------------------------> time
+     intro  peak  rest  peak  rest  build  climax
+```
+
+Two failure shapes to avoid:
+
+- **Flat-high** — sustained maximum intensity. The player fatigues and the peaks
+  stop reading as peaks; it flattens into undifferentiated noise. This is the
+  most common "my level is exhausting / boring despite lots of action" cause.
+- **Flat-low** — long stretches with no tension or stimulus. Reads as padding
+  and boredom even if each individual moment is competent.
+
+Draw this graph *before* building encounters; it tells you where fights go and
+how long the gaps between them should be.
+
+## The breather (safe room)
+
+After each peak, a valley: a **safe room** with no threat, low stimulus, and
+usually a save point and/or restock. The breather does three jobs:
+
+1. **Lets adrenaline drop** so the next peak spikes instead of blending in.
+   (Halo's cadence is often described as "thirty seconds of fun" on repeat — the
+   calm between is what makes the fun read.)
+2. **Rewards observation** — a quiet room is where lore, a secret, or a vista
+   lands, because the player has attention to spare.
+3. **Sets up the next escalation** — telegraph what's coming (a locked blast
+   door, distant sound, a corpse) so the next peak feels earned, not random.
+
+Vary breather length with the peak that preceded it: a brutal fight earns a
+longer rest; a light skirmish gets a short beat.
+
+## Difficulty curve within a level
+
+The macro trend is up, but it **resets at checkpoints** — the sawtooth again.
+Let the player re-enter a checkpoint competent and confident, then ramp. A curve
+that only climbs with no resets feels punishing; one that never climbs feels
+trivial. Signposting difficulty (a visibly tougher enemy, a bigger arena) lets
+the player brace, which is fairer than a surprise spike.
+
+## Encounter design
+
+An **encounter = enemy composition × space × objective × available resources.**
+Change any single factor to create a fresh encounter without new assets:
+
+- **Composition** — which enemy types, how many, in what waves.
+- **Space** — the arena shape (below); the same enemies feel new in a new arena.
+- **Objective** — kill all / survive N seconds / reach the exit / protect / hold
+  ground / retreat. The objective reshapes how the space is used.
+- **Resources** — ammo, health, cover, high ground the player can seize.
+
+### The encounter template
+
+```text
+ENCOUNTER — <name>
+  Teaches / tests ..... which mechanic or threat (and which of I/D/T/C beat)
+  Space ............... arena shape, sightline length, cover, flanks, verticality
+  Composition ......... enemy types + counts + wave timing
+  Objective ........... win condition (kill / survive / reach / hold / escort)
+  Resources ........... ammo/health/cover/high-ground and where they sit
+  Entry / exit ........ how the player arrives (telegraph) and leaves (release valve)
+  Intensity ........... where this sits on the level's graph (peak height)
+```
+
+## Introduce -> develop -> twist -> combine
+
+The four-beat progression that teaches a new element through space, without
+text. (The pattern behind Portal's test chambers, Half-Life 2's set-pieces, and
+much Nintendo level craft.)
+
+1. **Introduce** — meet it where it cannot hurt you. A turret across a safe gap;
+   one tile of the new hazard with a wall to watch from. Zero-risk learning.
+2. **Develop** — use it for real, low stakes. The turret now guards a corridor
+   you must cross; the hazard is a gap you must jump.
+3. **Twist** — recontextualize it. Two turrets flanking; the turret behind glass
+   you must lure enemies past; the hazard now moves. The rule you learned bends.
+4. **Combine** — the mastery test: the new element + everything learned earlier,
+   at full intensity, as the section's climax.
+
+### Worked example — a "gravity plate" that flings the player upward
+
+- **Introduce**: one plate in a safe room; step on it, get flung to a ledge with
+  a reward. No threat. Player learns "plate = launch."
+- **Develop**: cross a pit by chaining two plates — miss and you just fall back,
+  retry. Low stakes, real use.
+- **Twist**: a plate launches you *into* a turret's line of fire — now you must
+  time the launch, or use the plate to reach the turret's flank.
+- **Combine**: an arena where plates are the only way to reach high cover, under
+  fire, while enemies also use them. Everything at once.
+
+## Arena shape — the geometry is the difficulty knob
+
+The shape a fight happens in matters as much as the enemies:
+
+- **Sightline length ↔ threat range.** Long lanes favor ranged play and
+  sniping; tight rooms favor shotguns/melee and force close engagements. Set the
+  lane length to the range you want to be dominant.
+- **Cover rhythm.** Space cover so the player *advances in beats* — peek, move,
+  peek — rather than turtling in one spot. Low cover (peek over) vs full cover
+  (peek around) change the fight's tempo.
+- **Flanks.** Give at least one flank route so a fight isn't a static peek-war;
+  a flank forces the player to move and makes the space three-dimensional in
+  play, not just in geometry.
+- **Verticality.** High ground is pressure and reward. The Doom (2016) arena
+  is the reference: multi-tier, with resources and enemies placed to pull the
+  player *through* and *up* the space rather than hunker in a corner.
+- **Chokepoints + release valves.** A choke concentrates danger (good for a
+  last stand); always pair it with an exit or a way to break the standoff, or
+  the fight stalls into a stalemate.
+- **Entry and exit.** Telegraph the fight before the player commits (see the
+  arena from a safe threshold), and give a clear release when it's won.
+
+### Arena patterns
+
+| Pattern | Shape | Good for |
+|---|---|---|
+| **Corridor / lane** | Long, narrow, few flanks | Tension, forced pace, ranged duels |
+| **Open arena** | Wide, multi-cover, multi-flank | Skill expression, mobile fights |
+| **Vertical arena** | Stacked tiers, ramps/lifts | High-ground contests, push-forward combat |
+| **Hub** | Central space, spokes off it | Wave defense, "hold ground" objectives |
+| **Pinch** | Wide → choke → wide | Escalation, last-stand beats |
+
+Match the pattern to the encounter's job on the intensity graph, not to habit.

package/skills/leyes-de-percepcion/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: leyes-de-percepcion
+description: "Use when composing or reviewing a screen and you need to decide what the eye sees first and how things are grouped — proximity, similarity, common region, closure, continuity, figure-ground, the Von Restorff effect, and visual hierarchy. This is the package of Gestalt laws applied to interface design."
+tags: ["gestalt", "visual-perception", "ui-design"]
+profiles: [ui, full]
+---
+
+# Leyes de percepcion
+
+El ojo humano organiza lo que ve antes de que el cerebro lea una sola palabra. Estas leyes describen como lo hace. No son opiniones esteticas: son reflejos perceptivos. La unica decision que tienes es si los disenaste a proposito o los dejaste al azar.
+
+Usalas para dos cosas: **componer** (decidir agrupacion y orden de lectura) y **diagnosticar** (por que una pantalla se siente ruidosa, plana o desordenada).
+
+---
+
+## 1. Proximidad — el espacio agrupa mas fuerte que nada
+
+Los elementos cercanos se perciben como un grupo. El aire separa; la cercania implica relacion. Es la herramienta de agrupacion mas fundamental y la mas barata: no cuesta ni un pixel de tinta.
+
+- **Entre grupos**: mas espacio para senalar separacion.
+- **Dentro de un grupo**: menos espacio para senalar pertenencia.
+- Lo que crea la jerarquia es la **relacion** entre el espacio interno y el externo, no un valor fijo en pixeles. Una regla practica solida: el hueco entre grupos al menos el doble que el hueco dentro de uno.
+
+| Patron | Regla de proximidad |
+|---|---|
+| Campos de formulario | La etiqueta mas pegada a su campo que al campo siguiente |
+| Contenido de tarjeta | Titulo, cuerpo y metadatos juntos; la tarjeta separada de las vecinas |
+| Cabeceras de seccion | Menos espacio debajo de la cabecera (hacia su contenido) que encima (desde la seccion anterior) |
+| Grupos de botones | Acciones relacionadas juntas; la accion destructiva separada |
+
+**Diagnostico**: si una cabecera parece pertenecer a la seccion equivocada, casi siempre es porque tiene el mismo espacio arriba que abajo.
+
+## 2. Similitud — el aspecto compartido agrupa a distancia
+
+Los elementos que comparten caracteristicas visuales se perciben como relacionados, aunque no esten juntos. La mente agrupa por parecido de forma automatica.
+
+La similitud se transmite por:
+- **Color**: el mismo relleno senala la misma categoria, rol o estado.
+- **Forma**: iconos del mismo estilo (contorno frente a relleno) se leen como un conjunto.
+- **Tamano**: elementos del mismo tamano se leen como pares; la diferencia de tamano senala jerarquia.
+- **Estilo**: mismo peso de ilustracion, mismo tratamiento tipografico, mismo radio, mismo grosor de trazo.
+
+**Proximidad frente a similitud**: cuando chocan, gana la proximidad para lo cercano y la similitud para lo lejano. Si dos elementos deben leerse como pares pero estan en extremos opuestos de la pantalla, la unica herramienta que te queda es la similitud.
+
+**Diagnostico**: si dos cosas se ven iguales pero hacen cosas distintas, la interfaz esta mintiendo. Y al reves: si dos cosas hacen lo mismo y se ven distintas, el usuario cree que son distintas.
+
+## 3. Region comun — un contenedor agrupa aunque haya distancia
+
+Los elementos encerrados en un limite compartido o sobre un fondo compartido se perciben como grupo, aunque no esten especialmente cerca. Es una de las senales de agrupacion mas fuertes que existen.
+
+| | Proximidad | Region comun |
+|---|---|---|
+| Mecanismo | Cercania espacial | Limite o fondo compartido |
+| Ideal para | Elementos ya cercanos | Elementos que necesitan un limite explicito o mas fuerte |
+| Coste | Cero: solo espaciado | Peso visual: hay un borde o un fondo |
+| Cuando preferirla | Casi toda la agrupacion de layout | Tarjetas, paneles, barras laterales, pestanas, modales |
+
+Usa proximidad primero; anade region comun cuando la proximidad no baste o cuando el limite del grupo deba ser explicito (una tarjeta sobre la que se puede actuar como unidad, una seccion dentro de un formulario mas grande).
+
+## 4. Cierre — el ojo completa las formas insinuadas
+
+La mente prefiere las formas completas y familiares. Ante una forma incompleta, rellena las partes que faltan. **No necesitas dibujar todas las lineas para crear un limite visual: necesitas informacion suficiente para que la mente cierre la forma.**
+
+- Un circulo con un hueco se lee como anillo o indicador de progreso.
+- Un elemento que asoma parcialmente por el borde de un contenedor con scroll comunica "hay mas" sin ninguna etiqueta.
+- Una rejilla de tarjetas sin bordes, solo con alineacion y aire, se lee igual de agrupada y pesa mucho menos.
+
+Usalo para **quitar peso visual**: cada borde y cada linea separadora que puedas borrar sin perder la estructura es una ganancia.
+
+## 5. Continuidad — el ojo sigue las lineas y las alineaciones
+
+La mente prefiere trayectorias suaves y continuas a los cambios bruscos de direccion. Los elementos dispuestos a lo largo de una linea, aunque sea implicita, se perciben como relacionados, y el ojo recorre esa linea.
+
+- La alineacion es la aplicacion mas basica: un borde izquierdo continuo crea un eje vertical que el ojo sigue de arriba abajo.
+- Cada borde suelto rompe la continuidad y se lee como ruido.
+- **Romper la continuidad a proposito senala un cambio**: un elemento que rompe la alineacion se lee como el inicio de otra cosa.
+- En secuencias (pasos, lineas de tiempo, carruseles), la continuidad es lo que comunica "esto va detras de aquello".
+
+## 6. Figura-fondo — que capa esta delante y es accionable
+
+La mente separa automaticamente el campo visual en sujeto (figura) y contexto (fondo). La figura se percibe delante, delimitada y foco de atencion. El fondo se percibe detras, sin limites y en retroceso.
+
+| Figura (primer plano) | Fondo |
+|---|---|
+| Parece estar delante | Parece estar detras |
+| Delimitada, con bordes | Sin limites, se extiende mas alla |
+| Foco de atencion | Contexto para la atencion |
+
+Esto no es opcional: toda superficie de UI dispara la separacion figura-fondo. La pregunta es si la disenaste tu.
+
+- **Modales y capas**: el velo de oscurecimiento existe para empujar el contenido al fondo y dejar claro que capa es accionable. Sin el, el usuario no sabe donde puede hacer clic.
+- **Ambiguedad = fallo**: si dos capas compiten por ser figura, el usuario duda.
+- **Profundidad**: la sombra, el desenfoque y la escala son las herramientas para asignar capa. Usalas de forma consistente.
+
+## 7. Efecto Von Restorff — lo que se sale es lo que se recuerda
+
+El elemento que difiere de sus vecinos es el que se nota y el que se recuerda. La homogeneidad visual es la base; la desviacion atrae el ojo.
+
+**El efecto depende del contraste con el contexto. Si todo destaca, no destaca nada.** Solo funciona cuando:
+- Uno (o muy pocos) elementos se desvian.
+- Los elementos de alrededor son visualmente consistentes entre si.
+- La desviacion tiene significado, no es decorativa.
+
+| Contexto | Como aplicarlo |
+|---|---|
+| Llamada a la accion | Un unico boton relleno; los demas fantasma o de texto |
+| Precios | Destaca un unico plan recomendado; baja el peso visual de los demas |
+| Navegacion | El estado activo claramente distinto del inactivo |
+| Tablas | Resalte de fila o negrita para el registro clave |
+
+**Diagnostico**: cuenta cuantos elementos de la pantalla piden atencion. Si son mas de dos, ninguno la tiene.
+
+## 8. Jerarquia visual — el orden en el que aterriza el ojo
+
+Las seis herramientas, en orden de fuerza:
+
+- **Tamano**: lo grande se ve primero. Para una distincion clara, diferencias de al menos 1,5x.
+- **Peso**: la negrita, los trazos gruesos y los iconos rellenos pesan mas que sus variantes ligeras.
+- **Color y contraste**: el alto contraste atrae. Usa el color de forma estrategica para CTA, estado y enfasis.
+- **Espaciado**: mas aire alrededor de un elemento aumenta su importancia percibida.
+- **Posicion**: arriba a la izquierda (en lectura de izquierda a derecha) se ve primero. Sobre el pliegue importa. Patrones de barrido en F y en Z.
+- **Densidad**: lo aislado destaca; lo agrupado se barre como una unidad.
+
+Tres niveles, no mas:
+
+1. **Primario**: titulo de pagina, CTA principal. Se ve primero.
+2. **Secundario**: cabeceras de seccion, contenido clave. Se barre despues.
+3. **Terciario**: texto de apoyo, metadatos. Se lee bajo demanda.
+
+**La prueba de entrecerrar los ojos**: entorna la vista hasta que la pantalla se desenfoque. Lo que sigues distinguiendo es tu jerarquia real. Si no coincide con la que pretendias, el problema es de tamano, peso o contraste, no de contenido.
+
+---
+
+## Como usar este paquete
+
+**Al componer**: decide primero la agrupacion (proximidad, luego region comun si hace falta), luego el orden de lectura (continuidad y jerarquia), luego el enfasis (Von Restorff, uno solo) y por ultimo la profundidad (figura-fondo).
+
+**Al diagnosticar**, en este orden:
+
+1. Entorna los ojos: se ve la jerarquia pretendida? Si no, arregla tamano, peso y contraste.
+2. Cuenta los elementos que piden atencion. Mas de dos, reduce.
+3. Mide el espacio entre grupos frente al espacio dentro de ellos. Si no hay al menos el doble, la agrupacion es ruido.
+4. Busca bordes sueltos que rompan la alineacion sin querer decir nada.
+5. Busca bordes y separadores que el espacio ya sostiene. Borralos.
+6. Comprueba que en cada capa esta claro que es figura y que es fondo.

package/skills/leyes-de-percepcion/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: leyes-de-percepcion
+
+should_trigger:
+  - prompt: "Revisa que ve el ojo primero en esta pantalla."
+    why: "Disparador directo de leyes-de-percepcion."
+  - prompt: "Necesito aplicar las leyes de la Gestalt a este layout."
+    why: "Disparador directo de leyes-de-percepcion."
+  - prompt: "Como deberia agrupar estos elementos para que se lean juntos."
+    why: "Disparador directo de leyes-de-percepcion."
+  - prompt: "Apply Gestalt principles like proximity and figure-ground to this screen."
+    why: "Disparador directo de leyes-de-percepcion."
+  - prompt: "Ayudame a decidir la jerarquia visual de esta interfaz."
+    why: "Disparador directo de leyes-de-percepcion."
+
+should_not_trigger:
+  - prompt: "Escribe el texto del boton de confirmar."
+    route_to: "mejor-redaccion"
+    why: "Escribir el texto de un boton es el trabajo de mejor-redaccion, no de leyes-de-percepcion."
+  - prompt: "Elige la paleta de colores del modo oscuro."
+    route_to: "mejor-colores"
+    why: "Elegir la paleta de colores es el trabajo de mejor-colores, no de leyes-de-percepcion."
+  - prompt: "Revisa el contraste de este texto."
+    route_to: "mejor-colores"
+    why: "Medir el contraste es el trabajo de mejor-colores, no de leyes-de-percepcion."
+  - prompt: "Ajusta el espaciado responsive de esta grid."
+    route_to: "mejor-layout"
+    why: "Ajustar el espaciado y los breakpoints es el trabajo de mejor-layout, no de leyes-de-percepcion."
+
+capability:
+  - scenario: "El usuario compone o revisa una pantalla y necesita decidir agrupacion visual."
+    must_include:
+      - "Gestalt"

package/skills/leyes-de-retencion/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: leyes-de-retencion
+description: "Use when diagnosing why people abandon a flow halfway through, or when designing decisions, forms, steps, response times, and closing moments — Hick's law, Fitts's law, Miller's law, Jakob's law, the Doherty threshold, the Zeigarnik effect, the serial position effect, the peak-end rule, and Tesler's law."
+tags: ["retention", "ux-laws", "behavioral-design"]
+profiles: [ui, full]
+---
+
+# Leyes de retencion
+
+Por que la gente se va a mitad de camino. Estas nueve leyes vienen de investigacion en psicologia cognitiva y de UX, y cada una explica una clase distinta de abandono. Usalas para diagnosticar un flujo que pierde gente, y para disenar uno que no la pierda.
+
+**Diagnostico rapido**: emparéjá el sintoma con la ley.
+
+| Sintoma | Ley |
+|---|---|
+| El usuario se queda parado ante la pantalla sin elegir | Hick |
+| Falla el objetivo, sobre todo en movil | Fitts |
+| Rellena mal el formulario o se pierde a mitad | Miller |
+| No encuentra algo que esta a la vista | Jakob |
+| Da varias veces al mismo boton, o se va durante la espera | Doherty |
+| Empieza el flujo y no vuelve | Zeigarnik |
+| Se salta lo del medio de una lista o un menu | Posicion serial |
+| Completa el flujo pero lo recuerda mal | Pico-final |
+| Todo parece simple y aun asi el usuario sufre | Tesler |
+
+---
+
+## 1. Ley de Hick — el tiempo de decision crece con el numero de opciones
+
+El tiempo para tomar una decision crece de forma logaritmica con el numero de opciones simultaneas. Duplicar las opciones no duplica el tiempo, pero cada opcion anadida cuesta algo.
+
+- Menos opciones a la vez acelera la decision.
+- Agrupar y revelar progresivamente reduce la complejidad aparente sin esconder funcionalidad.
+- **La claridad de las opciones importa tanto como el numero**: opciones ambiguas o solapadas son mas dificiles de elegir que un conjunto mayor de opciones bien distintas.
+
+Donde aplicarla: menus de navegacion (limita el primer nivel), barras de acciones (saca las comunes, mete el resto en un desbordamiento), onboarding (una decision por paso), formularios (menos campos opcionales, obligatorios primero), tablas de precios (tres planes es el punto dulce convencional), listados (paginacion y carga progresiva).
+
+## 2. Ley de Fitts — el tiempo de alcance depende del tamano y la distancia
+
+El tiempo para alcanzar un objetivo es funcion de la distancia y del tamano. En llano: los objetivos grandes y cercanos se pulsan rapido; los pequenos y lejanos son lentos y propensos a error. Las dos dimensiones cuentan por separado.
+
+**Tamano**
+- Objetivo tactil minimo: 44x44pt (Apple) / 48x48dp (Material).
+- Con puntero puede ser menor, pero generoso igualmente: 24x24px minimo.
+- El objetivo es el area interactiva, no el icono: un icono de 16px puede tener 44px de area de pulsacion.
+- Agranda los objetivos de las acciones frecuentes o de mucha consecuencia.
+
+**Distancia**
+- Coloca las acciones cerca del contenido sobre el que actuan: la accion de una tarjeta vive en la tarjeta, no al otro lado de la pantalla.
+- Los bordes y las esquinas de la pantalla son objetivos de tamano infinito con puntero (no te puedes pasar). Usalos para navegacion persistente.
+- En movil, la zona alcanzable con el pulgar es la mitad inferior. Las acciones principales van ahi, no arriba del todo.
+
+## 3. Ley de Miller — agrupa en trozos de unos cuatro
+
+El articulo de 1956 propuso 7 +/- 2 elementos en memoria de trabajo, y se ha citado tanto como se ha malaplicado. La investigacion posterior (Cowan, 2001) situa el limite realista de **trozos con significado en torno a 4 +/- 1**. El matiz que el propio Miller senalo: el 7 aplica a **trozos**, no a elementos crudos.
+
+Lo que significa para el diseno: **agrupar en trozos con significado reduce la carga sea cual sea el numero exacto**. No cites "7 elementos" como regla; cita el agrupamiento como estrategia.
+
+Donde aplica: navegacion (agrupa por categoria; una lista plana de 10+ se barre peor que 3 grupos de 3-4), formularios (parte los largos en secciones con cabecera, cada una completable como unidad), numeros y codigos (formateados en trozos), tablas (agrupacion visual para partir listas largas), onboarding (3-5 fases con nombre en vez de 12 pasos numerados), listas de funcionalidades y precios (3-5 vinetas por plan; a partir de ahi se deja de leer).
+
+## 4. Ley de Jakob — el usuario espera que funcione como lo demas que usa
+
+El usuario pasa casi todo su tiempo en OTROS productos. Llega al tuyo con expectativas ya construidas sobre donde vive la navegacion, que significa un icono de carrito, como se comporta un interruptor y donde se buscan los ajustes.
+
+No es un argumento para copiar a la competencia. Es un argumento para **entender que convenciones cargan una expectativa lo bastante fuerte como para que apartarse de ellas imponga un coste real de aprendizaje**, y ser deliberado cuando lo hagas.
+
+Las convenciones mas fuertes: el logo arriba a la izquierda vuelve al inicio; la navegacion principal arriba o en lateral; la busqueda con lupa; el carrito arriba a la derecha; el formulario se envia con un boton al final; el enlace subrayado o de otro color; el gesto de volver atras; el cierre arriba del todo del modal.
+
+Rompe un patron familiar solo si puedes demostrar que es mejor, y entonces pruébalo, no lo supongas.
+
+## 5. Umbral de Doherty — por debajo de 400ms se conserva el flujo
+
+Doherty y Thadani (IBM, 1982) establecieron que cuando el sistema responde a una accion en **menos de 400ms**, la productividad sube de forma sustancial: el usuario se queda en flujo en vez de perder el hilo.
+
+| Tiempo de respuesta | Percepcion |
+|---|---|
+| 0-100ms | Instantaneo: el sistema se siente como extension directa de la accion |
+| 100-300ms | Rapido: perceptible pero no molesto |
+| 300-400ms | En el limite: algunos usuarios lo notan |
+| 400ms-1s | Lento: el usuario sabe que espera; hace falta un indicador |
+| 1s+ | Claramente lento: hace falta feedback de progreso; el flujo se rompe |
+| 10s+ | Interrupcion de tarea: el usuario cambia de contexto |
+
+Donde mas importa por debajo de 400ms: transiciones entre vistas, respuesta al pulsar un boton, filtrado y busqueda incremental, apertura de menus y desplegables.
+
+**Y cuando no puedes bajar de ahi**: la percepcion tambien se disena. Una respuesta optimista (actualizar la UI antes de que confirme el servidor), un esqueleto con la forma del contenido real y una animacion mas rapida hacen que lo mismo se sienta mas rapido.
+
+## 6. Efecto Zeigarnik — lo incompleto sigue activo en la mente
+
+La gente recuerda mejor las tareas interrumpidas o sin terminar que las completadas. Lo inacabado ocupa bucles abiertos en la memoria de trabajo. **La incompletitud es un estado motivacional**: algo empezado y sin terminar tira hacia su finalizacion.
+
+Aplicaciones honestas:
+- Indicadores de progreso en flujos de varios pasos: ver "paso 2 de 4" tira hacia el 4.
+- Un perfil al 60% con lo que falta enumerado.
+- Borradores guardados que sobreviven a la interrupcion: el usuario vuelve porque puede volver.
+- Un primer paso ya marcado al empezar (progreso dotado), que convierte "no he empezado" en "voy por la mitad".
+
+**Donde se vuelve abuso**: bucles abiertos que no puedes cerrar, contadores de notificaciones que nunca llegan a cero, o interrumpir a proposito una tarea para forzar el retorno. Eso no retiene: quema.
+
+## 7. Efecto de posicion serial — se recuerdan el principio y el final
+
+En una secuencia, se recuerdan los elementos del principio (primacia) y los del final (recencia). Los del medio se recuerdan menos: la atencion y la codificacion caen ahi. Ese hueco es el "valle de posicion serial".
+
+- Coloca los elementos criticos de un menu o una lista al principio o al final.
+- Si algo importante tiene que ir en el medio por logica, **compénsalo con distincion visual** (ahi es donde entra Von Restorff).
+- En una tabla de precios, el plan que quieres que se elija va en un extremo o marcado; en el medio y sin marcar es el que menos se recuerda.
+- En una barra de navegacion, el ultimo elemento tiene mas peso del que la gente cree: ahi suele ir el CTA.
+
+## 8. Regla del pico-final — un flujo se recuerda por su momento mas intenso y por el final
+
+La investigacion de Kahneman encontro que la gente no evalua una experiencia como la media de sus momentos. El juicio retrospectivo lo dominan dos:
+
+1. **El pico**: el momento emocionalmente mas intenso, positivo o negativo.
+2. **El final**: como concluyo.
+
+La duracion y la calidad media de todo lo demas aportan mucho menos. Es la "negligencia de la duracion": la gente juzga mal cuanto duro algo, pero bien como se sintio en los extremos.
+
+Implicaciones:
+- **Disena el final a proposito.** Una pantalla de exito, una confirmacion que dice exactamente que ha pasado y que viene despues, un momento de celebracion proporcionado. Un flujo que termina en una pagina en blanco se recuerda como peor de lo que fue.
+- **Busca los picos negativos y arreglalos primero.** Un unico error humillante a mitad del formulario pesa mas en el recuerdo que veinte campos que fueron bien.
+- **La cancelacion y la baja tambien tienen final.** Un flujo de baja digno es lo que hace que alguien vuelva; uno que pone trabas es el pico negativo que se cuenta a otros.
+
+## 9. Ley de Tesler — la complejidad no se elimina, se mueve
+
+Toda aplicacion tiene una cantidad irreducible de complejidad. No se puede eliminar: solo se puede mover. La decision de diseno es: **la absorbe el usuario o la absorbe el producto?**
+
+Simplificar la interfaz no quita complejidad. La reubica.
+
+- **Complejidad inherente**: viene de la naturaleza de la tarea. Reservar un vuelo con varios pasajeros, asientos concretos y una escala es genuinamente complejo. Quitar esa complejidad es quitar capacidad.
+- **Complejidad accidental**: la que anade la implementacion y no la tarea. Esa si se borra.
+
+El fallo tipico: una interfaz que parece limpia porque ha empujado la complejidad al usuario, que ahora tiene que saber cosas, recordar formatos, o hacer el trabajo en otra herramienta y pegarlo. **Todo parece simple y aun asi el usuario sufre**: eso es Tesler.
+
+Preguntas para aplicarla:
+- Que esta teniendo que saber el usuario que el producto podria deducir?
+- Que esta teniendo que recordar que el producto podria guardar?
+- Que paso esta haciendo a mano que el producto podria hacer por defecto?
+- Y al reves: que hemos escondido tanto que ahora el usuario no puede hacer su trabajo?
+
+---
+
+## Como usar este paquete en un diagnostico de abandono
+
+1. **Mide donde se cae la gente**, no donde crees que se cae.
+2. En ese punto, pasa las leyes en este orden: **Doherty** (esta esperando?), **Hick** (hay demasiado que decidir?), **Miller** (hay demasiado que retener?), **Fitts** (el objetivo es alcanzable?), **Jakob** (esperaba otra cosa?), **Tesler** (le hemos pasado el trabajo a el?).
+3. Para la retencion a medio plazo, mira **Zeigarnik** (hay un bucle abierto al que volver, y puede volver de verdad?).
+4. Para la valoracion y la recomendacion, mira **pico-final** (cual es el pico negativo, y como termina esto?).
+5. Para lo que la gente recuerda de un menu o un listado, mira **posicion serial**.

package/skills/leyes-de-retencion/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: leyes-de-retencion
+
+should_trigger:
+  - prompt: "La gente abandona este formulario a mitad, ayudame a diagnosticarlo."
+    why: "Disparador directo de leyes-de-retencion."
+  - prompt: "Aplica la ley de Hick a este menu con demasiadas opciones."
+    why: "Disparador directo de leyes-de-retencion."
+  - prompt: "Necesito disenar mejor los pasos de este flujo de onboarding."
+    why: "Disparador directo de leyes-de-retencion."
+  - prompt: "Use Fitts's law and the peak-end rule to redesign this checkout flow."
+    why: "Disparador directo de leyes-de-retencion."
+  - prompt: "Por que la gente no termina este proceso de varios pasos."
+    why: "Disparador directo de leyes-de-retencion."
+
+should_not_trigger:
+  - prompt: "Elige la tipografia de este texto largo."
+    route_to: "mejor-tipografia"
+    why: "Elegir la tipografia es el trabajo de mejor-tipografia, no de leyes-de-retencion."
+  - prompt: "Revisa el contraste de color de este boton."
+    route_to: "mejor-colores"
+    why: "Medir el contraste es el trabajo de mejor-colores, no de leyes-de-retencion."
+  - prompt: "Anade una animacion de entrada a esta tarjeta."
+    route_to: "animar"
+    why: "Anadir una animacion es el trabajo de animar, no de leyes-de-retencion."
+  - prompt: "Escribe el copy del estado vacio."
+    route_to: "mejor-redaccion"
+    why: "Escribir el copy de un estado vacio es el trabajo de mejor-redaccion, no de leyes-de-retencion."
+
+capability:
+  - scenario: "El usuario diagnostica abandono en un flujo o disena sus pasos y tiempos."
+    must_include:
+      - "abandona"