| name | b-setup-or-fix |
| description | El experto: audita un repo SvelteKit degradado (load functions y fetch manual en vez de remote functions, sintaxis Svelte 4, sobre-ingeniería, funciones duplicadas, exceso de comentarios, features desparramados) y lo migra por peldaños hacia la base canónica del plugin — o instala esa base en un proyecto nuevo. Usar SOLO cuando el usuario lo invoque directo: "rescata este repo", "limpia este proyecto", "audita el codebase", "define la base del proyecto", "genio de la botella". NO es review de un PR (eso es b6-pr-review) ni construcción de un feature nuevo (eso es b2-build-feature); ningún skill del pipeline lo encadena automático. |
| allowed-tools | Bash, Read, Write, Edit, Grep, Glob, AskUserQuestion, Skill, Agent |
Argumentos recibidos
$ARGUMENTS
Sin argumentos: flujo completo (diagnóstico → gate → escalera). Flags:
--init — proyecto nuevo o sano: instala la base (E1 + docs semilla) y termina. No audita.--audit — solo FASES 0-2: diagnóstico + plan, ningún archivo se toca. Termina en el reporte.--feature=<slug> — acota E2-E6 a un solo feature (src/routes/<slug>/). Para repos grandes o rescates incrementales.--hasta=E<n> — sube la escalera solo hasta ese peldaño (ej. --hasta=E3). El plan igual muestra todos.
b-setup-or-fix — base sana o rescate de repo SvelteKit
Los otros skills del pipeline construyen y revisan cambios (un issue, un PR). Este opina sobre el codebase entero: detecta el código que se degradó — capas inútiles, event handlers que reinventan forms, datos que viajan por load()/fetch ignorando remote functions, duplicados, prosa — y lo migra por peldaños verificados hacia la misma doctrina que b2-build-feature usa para construir y b6-pr-review usa para revisar. El resultado: cada feature en su carpeta, remote functions como única vía de datos, runas Svelte 5, mínimo comentario, documentación en archivos.
Reglas críticas:
- Solo invocación directa del usuario. Ningún skill (b7, b8, b10) lo encadena, ni siquiera al detectar deuda. Sugerir
/b-pipeline:b-setup-or-fix es lo máximo permitido a terceros.
- Herramientas PRIMERO, análisis después. Cada fase arranca con un comando; el juicio LLM filtra lo que el script contó.
- Nada se edita antes del gate humano de FASE 2. El diagnóstico completo siempre precede al primer
Edit.
- Un peldaño roto detiene la escalera. Cada peldaño deja el repo verde (check + build vs baseline) antes del siguiente; si no verifica, se revierte ese peldaño y se para con reporte. Nunca se avanza sobre base rota.
La escalera (tabla canónica)
Orden fijo: primero lo que habilita (config, seguridad), después mover archivos, después migrar datos, al final cosmética y docs (documentan el estado FINAL, no el intermedio). Detalle de transformaciones por peldaño: references/fix-ladder.md (misma numeración).
| Peldaño | Corrige | Riesgo |
|---|
| E1 Base y seguridad | flags remoteFunctions/async faltantes, scripts npm mínimos, infra requireUser/requirePermission inexistente, remote functions/endpoints sin guard, estado mutable a nivel de módulo en .server.ts, secrets hardcodeados | bajo |
| E2 Estructura | features fuera de src/routes/<feature>/, data.remote.ts genérico, *.remote.ts bajo src/lib/server/, subcarpetas ui/, wrappers <Feature>Page.svelte | bajo-medio (mueve archivos: trazar callers antes) |
| E3 Remote functions | load() en +page(.server).ts, export const actions, +server.ts internos, onMount+fetch, mutaciones sin refresh → query/form/command + single-flight | medio-alto (cambia semántica SSR: feature por feature, nunca barrido ciego) |
| E4 Runas y stack | on:click, export let, <slot>, $:, $effect que computa, spreads inmutables sobre $state, named imports shadcn, lucide-svelte, Select.Value | medio |
| E5 Desingenieria y duplicados | capas pass-through (service/repository/factory para CRUD), helpers que solo reenvían, funciones duplicadas, código muerto | medio-alto (consolidar sin tests del survivor está prohibido) |
| E6 Comentarios y docs | prosa que explica el QUÉ (se preserva // ponytail:), <feature>.md faltantes, doc nivel repo inexistente | bajo |
Catálogos canónicos — citar, no duplicar. Los antipatrones viven en ../b6-pr-review/references/sveltekit-antipatterns.md (sus secciones 1-14 son lo que este skill llama AP1-AP14) y los checks de seguridad en security-checklist.md; el layout del slice en ../b2-build-feature/references/slice-spec.md (gana ante cualquier contradicción); la escalera de simpleza en ../b2-build-feature/references/simplicity-ladder.md. Las siglas SEC-*/CAL-*/DUP-*/REG-* son notación interna de este skill — tabla de mapeo a las secciones reales al inicio de references/fix-ladder.md. Este skill solo agrega lo propio: la escalera E1-E6, las recetas de migración y el modo base.
FASE 0: Preflight
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cat "$HOME/.claude/b-pipeline.root" 2>/dev/null || ls -d "$HOME"/.claude/plugins/marketplaces/b-pipeline* 2>/dev/null | head -1)}"
. "$PLUGIN_ROOT/scripts/lib.sh"
grep -q '"@sveltejs/kit"' package.json || echo "ABORT: no es un proyecto SvelteKit"
git status --porcelain
git checkout -b "genie/$(date +%Y%m%d)-<slug>" "$(bp_default_branch)"
bash "$PLUGIN_ROOT/skills/b-setup-or-fix/scripts/rung-verify.sh" baseline
<slug> corto describiendo el alcance (rescate, init, o el --feature).rung-verify.sh baseline captura los errores preexistentes de check y build. Los peldaños se comparan contra este baseline — el genio nunca se atribuye errores que ya estaban, ni exige cero absoluto en un repo que llegó roto (se informa y se sigue).- Con
--init, correr igual este preflight completo (gate + rama + baseline) y saltar a Modo base (abajo).
FASE 1: Diagnóstico (solo lectura)
bash "$PLUGIN_ROOT/skills/b-setup-or-fix/scripts/audit.sh"
Emite secciones === E1 === … === E6 === con los hits (archivo:línea) y una línea final parseable:
AUDIT_RESULT mode=base|rescate rungs=E1:<n>,E2:<n>,E3:<n>,E4:<n>,E5:<n>,E6:<n> features=<n>
El script cuenta; el juicio LLM filtra antes de que algo sea hallazgo:
- Falsos positivos típicos a descartar:
goto() post-acción (submit/delete), $effect para DOM/timers reales, +server.ts que es webhook externo (no se migra a remote function), load de página explícitamente pública, imports directos de shadcn permitidos (Button, Input, Label, Textarea, Badge, Separator).
- Lo que el script no ve, lo cubre una pasada LLM: indirección CAL-1..3 (trazar
*.remote.ts → callees con codegraph_explore si hay .codegraph/, sino rg/Grep), duplicados DUP-1 en zonas calientes (src/lib/utils, helpers, formateo fecha/moneda, validación), código muerto (exports sin consumidor). Si el skill finding-duplicate-functions está disponible, invocarlo para E5; sino, comparación semántica manual sobre el catálogo de exportadas.
// ponytail: marca simplificación deliberada: NO es hallazgo salvo que el techo nombrado ya se superó.- Hallazgos con formato parseable de b6:
- **E<n>**: <archivo:línea> <descripción en una línea>.
FASE 2: Plan + GATE HUMANO (obligatorio, sin excepción)
Presentar el plan como tabla y preguntar vía AskUserQuestion hasta qué peldaño subir y, si el repo es grande, qué features entran en esta corrida:
| Peldaño | Hallazgos | Riesgo | Qué se hace |
|---|---|---|---|
| E1 Base y seguridad | 4 | bajo | flags + guard en 3 remote functions + 1 secret a $env |
| E3 Remote functions | 12 | medio-alto | migrar 4 features: load->query, actions->form |
| ... | | | |
--hasta=E<n> pre-fija el tope, pero la aprobación del plan sigue siendo humana.- Con
--audit (o si el usuario no aprueba): terminar aquí con el reporte y B11_RESULT mode=audit rungs_done= rungs_blocked= features=<n> (mismo shape siempre, campos vacíos incluidos — los parsers no adivinan).
- Rechazo con razón load-bearing ("ese +server.ts lo consume una app móvil") se anota en el reporte final para que una próxima corrida no lo re-sugiera.
FASE 3: Ejecución por peldaño
Loop estricto por cada peldaño aprobado, en orden E1 → E6:
-
Transformar siguiendo references/fix-ladder.md (y references/migrate-to-remote.md para E3). E2/E5 mueven o borran símbolos: trazar callers ANTES (codegraph_callers o rg -n '\b<simbolo>\(') — un caller roto fuera del diff es BLOCKER, la misma regla de regresión de callers que aplica b6 (notación REG en fix-ladder.md).
-
Verificar:
bash "$PLUGIN_ROOT/skills/b-setup-or-fix/scripts/rung-verify.sh" E<n>
RUNG_VERIFY ok exige: check sin errores NUEVOS vs baseline + build no peor que baseline. Además: svelte-autofixer sobre cada .svelte tocado, y si hay dev server corriendo, browser test rápido de los features tocados (mismo criterio de b2: código que compila pero no se vio en browser NO está listo).
-
Commitear vía Skill b3-git-commit con mensaje refactor(genie): E<n> <resumen> — nunca git add/git commit a mano. Un peldaño = un commit; prohibido mezclar peldaños.
-
RUNG_VERIFY fail → revertir SOLO ese peldaño (git checkout -- . + limpiar untracked del peldaño), reportar por qué falló, y DETENER la escalera. Los peldaños ya commiteados quedan.
Scope-growth: archivo fuera del plan aprobado se declara antes de tocarlo (heredado de b2). E3 va feature por feature — cada feature migrado debe verificar antes del siguiente dentro del peldaño.
FASE 4: Cierre y reporte
bash "$PLUGIN_ROOT/skills/b-setup-or-fix/scripts/audit.sh"
Reporte final, corto y con el delta primero:
| Peldaño | Antes | Después |
|---|---|---|
| E3 Remote functions | 12 | 2 |
- Peldaños aplicados / omitidos / bloqueados (con razón).
- Deuda restante: candidatos a issues — ofrecer /b-pipeline:b0-conversation-to-issues, no crearlos solo.
- Frase de honestidad obligatoria: "Verifiqué types y build pero NO pude browser-testear <features> porque <razón>."
Última línea, machine-readable:
B11_RESULT mode=init|audit|rescate rungs_done=<csv> rungs_blocked=<csv> features=<n>
Sugerir el siguiente paso (abrir PR vía b4, o próxima corrida con los features restantes) — sin ejecutarlo.
Modo base (--init, o AUDIT_RESULT mode=base)
Para proyecto nuevo o sano (E2-E4 en cero y menos de 3 features — E5/E6 son señales blandas y no bloquean el modo). Sin --init, el gate de FASE 2 corre igual antes de tocar nada. Aplica references/base-setup.md completo:
svelte.config.js con kit.experimental.remoteFunctions: true + compilerOptions.experimental.async: true.$lib/server/auth.ts con requireUser/requirePermission (formato verbo:sustantivo) si no existen.CLAUDE.md del repo con la doctrina en ~10 líneas + punteros a slice-spec.md.docs/ARCHITECTURE.md semilla (stack, mapa de slices, decisiones).- Primer slice vía
../b2-build-feature/scripts/scaffold-slice.sh solo si el usuario nombra un feature concreto — nada especulativo (YAGNI: cero capas, cero scaffolding "para después").
- Verificar (
rung-verify.sh E1) y commitear vía b3: chore(genie): base sveltekit.
Termina con B11_RESULT mode=init rungs_done=E1 rungs_blocked= features=<n>.
Qué NO hacer
- Editar código antes del gate de FASE 2, o continuar la escalera tras un
RUNG_VERIFY fail.
- Migrar a remote functions un repo cuya versión de SvelteKit no las soporta (< 2.27): E3 se reporta bloqueado, no se intenta (
AUDIT lo detecta en === STACK ===).
- Consolidar duplicados sin verificar que el survivor tiene tests que cubren a los borrados: ante duda, INVESTIGATE — nunca CONSOLIDATE automático.
- Borrar comentarios con contexto útil sin migrarlo antes al
<feature>.md. // ponytail: y TODO/FIXME accionables se preservan.
- Copiar los catálogos de b2/b6 dentro de este skill (drift documental).
- Resolver "rápido" un hallazgo agregando una capa nueva: la salida de cada peldaño es MENOS código, no más.
- Instalar service worker/PWA por iniciativa propia. Solo si el usuario lo pide, y ahí manda
references/pwa-setup.md.
Referencias
references/fix-ladder.md — las transformaciones exactas de cada peldaño E1-E6 con pares MAL/BIEN. Leer al ejecutar FASE 3.references/migrate-to-remote.md — recetas R1-R7 de migración a remote functions (E3): load→query, actions→form, fetch→await, single-flight. Leer al ejecutar E3.references/base-setup.md — modo base completo: config canónica, guards, docs semilla, política de comentarios. Leer con --init o mode=base.references/pwa-setup.md — manifest, service worker, cache y flujo de update. Leer SOLO si el usuario pide PWA/offline/instalable; no es parte de la escalera ni del modo base.scripts/audit.sh — diagnóstico mecánico; secciones === E<n> === + AUDIT_RESULT. Exit 3 = no es SvelteKit.scripts/rung-verify.sh — baseline captura estado inicial; E<n> compara y emite RUNG_VERIFY ok|fail rung=E<n>.../b6-pr-review/references/sveltekit-antipatterns.md + security-checklist.md — catálogos AP/SEC canónicos.../b2-build-feature/references/slice-spec.md + simplicity-ladder.md + feature-templates.md — layout, doctrina de simpleza y templates canónicos.
Notas
- Repo sin tests:
rung-verify solo cubre types + build; E3/E5 pueden romper runtime sin detectarse. Decirlo en el reporte (frase de honestidad) y recomendar browser test antes del merge.
- Baseline ya roto: registrar los errores preexistentes en FASE 0 y comparar contra ellos; informar al usuario antes de seguir, nunca atribuírselos.
- Skills externos opcionales:
finding-duplicate-functions (E5) y using-remote-functions (E3) pueden no existir — degradar a los references propios y decirlo en el reporte.
- Repos grandes: usar
--feature=<slug> y correr el rescate en tandas; el reporte deja el backlog explícito.
- Monorepos: correr desde la raíz del proyecto SvelteKit, no del monorepo.
- Todo output de este skill en español neutro sin tildes, nunca voseo.
