refacil-sdd-ai 4.2.4 → 4.4.0

package/skills/attend/SKILL.md

@@ -1,70 +1,70 @@
----
-name: refacil:attend
-description: Modo escucha activa del bus. Espera preguntas dirigidas a esta sesión, las procesa y responde; luego sigue escuchando. Habilita conversación automática LLM a LLM entre repos.
-user-invocable: true
----
-
-# refacil:attend — Escuchar y responder preguntas del bus
-
-Pone esta sesión en modo escucha. Cuando llega una pregunta dirigida, la respondes usando tu conocimiento del repo y vuelves a escuchar. Así otros agentes pueden preguntarte cosas y recibir respuesta automática mientras tú estés en este modo.
-
-## Instrucciones
-
-### Paso 1: Ejecutar attend
-
-Ejecuta vía `Bash` con timeout alto (10 minutos / 600000 ms):
-
-```bash
-refacil-sdd-ai bus attend
-```
-
-**IMPORTANTE**: al invocar el `Bash` tool, pasa `timeout: 600000` (10 min) para aprovechar el máximo.
-
-El comando:
-- Revisa primero si hay preguntas pendientes dirigidas a esta sesión en el historial reciente
-- Si no hay, espera en vivo hasta 9 minutos por una nueva pregunta dirigida
-- Retorna apenas llegue una, o con un mensaje "sin preguntas" si pasa el tiempo
-
-### Paso 2: Procesar el resultado
-
-**Si el output contiene "Pregunta recibida del bus"**:
-1. Lee `de:`, `correlationId:` y `texto:` del output.
-2. Si el `texto` es una **solicitud de cambio** en **este** repo (no solo una pregunta informativa), canaliza con **`/refacil:propose`** y el flujo SDD-AI; en el `reply` resume estado o siguiente paso sin re-explicar la metodologia (quien pregunta ya esta en la sala por `join`). Ver `refacil-prereqs/BUS-CROSS-REPO.md` y `/refacil:ask` Paso 1.5.
-3. Investiga el repo para encontrar la respuesta. Usa `Read`, `Grep`, `Glob` según necesites.
-4. Responde al bus con:
-   ```bash
-   refacil-sdd-ai bus reply --text "<tu respuesta>"
-   ```
-   El broker autocompleta el `correlationId` con la última pregunta dirigida a ti (la que acabas de procesar).
-5. Si la pregunta está fuera de tu scope, igualmente responde:
-   ```bash
-   refacil-sdd-ai bus reply --text "fuera de mi alcance, consulta al repo X"
-   ```
-6. **Vuelve a ejecutar `refacil-sdd-ai bus attend`** (paso 1) para seguir escuchando.
-
-**Si el output contiene "Sin preguntas en"**:
-- No hubo preguntas en el intervalo.
-- **Vuelve a ejecutar `refacil-sdd-ai bus attend`** (paso 1) para seguir escuchando.
-
-### Paso 3: Salir del modo
-
-El loop continúa mientras el usuario (dev) no te dé otra instrucción o aborte con ESC. Si el usuario te da una tarea nueva en medio del loop, abandona el attend y atiende la nueva tarea.
-
-## Cuándo usar attend
-
-- Cuando el dev te dice *"atiende el bus un rato"* o *"quedás escuchando al bus mientras yo hago otra cosa"*.
-- Cuando sabes que otro agente te va a consultar cosas y quieres responder automáticamente.
-
-## Cuándo NO usar attend
-
-- Si tienes una tarea activa que el usuario te pidió — primero termínala.
-- Si el dev necesita usar esta sesión para algo inmediato — attend bloquea la sesión.
-
-## Reglas
-
-- Si el `ask` implica **que implementes un cambio en este repo** acordado por la sala, despues de ejecutarlo usa **`/refacil:propose`** (y el flujo SDD-AI) y **cierra al solicitante** por bus (`reply` u otro canal segun `refacil-prereqs/BUS-CROSS-REPO.md`); no cierres en silencio.
-- **Siempre re-invocar attend después de responder** — un solo `attend` atiende una sola pregunta; el loop lo mantienes tú.
-- **No respondas desde conocimiento general**: usa archivos del repo como fuente. Si no sabes, dilo.
-- **No envíes secretos ni tokens** en las respuestas — los mensajes quedan 7 días en disco local.
-- **Sesión ocupada**: mientras attend corre, el dev no puede usar esta sesión sin abortar. Si el dev te interrumpe, deja attend y atiende al dev.
-- El timeout interno (9 min) es para mantenerse dentro del límite del Bash tool; no es tope de escucha total. Al re-invocar, el loop es efectivamente infinito.
+---
+name: refacil:attend
+description: Active bus listening mode. Waits for questions directed to this session, processes them and responds; then continues listening. Enables automatic LLM-to-LLM conversation between repos.
+user-invocable: true
+---
+
+# refacil:attend — Listen and respond to bus questions
+
+Puts this session in listening mode. When a directed question arrives, you respond using your knowledge of the repo and go back to listening. This way other agents can ask you things and receive an automatic response while you are in this mode.
+
+## Instructions
+
+### Step 1: Execute attend
+
+Run via `Bash` with a high timeout (10 minutes / 600000 ms):
+
+```bash
+refacil-sdd-ai bus attend
+```
+
+**IMPORTANT**: when invoking the `Bash` tool, pass `timeout: 600000` (10 min) to take advantage of the maximum.
+
+The command:
+- First checks if there are pending questions directed to this session in the recent history
+- If not, waits live for up to 9 minutes for a new directed question
+- Returns as soon as one arrives, or with a "no questions" message if the time passes
+
+### Step 2: Process the result
+
+**If the output contains "Question received from bus"**:
+1. Read `from:`, `correlationId:`, and `text:` from the output.
+2. If the `text` is a **change request** in **this** repo (not just an informational question), channel it with **`/refacil:propose`** and the SDD-AI flow; in the `reply` summarize status or next step without re-explaining the methodology (whoever asks is already in the room via `join`). See `refacil-prereqs/BUS-CROSS-REPO.md` and `/refacil:ask` Step 1.5.
+3. Investigate the repo to find the answer. Use `Read`, `Grep`, `Glob` as needed.
+4. Respond to the bus with:
+   ```bash
+   refacil-sdd-ai bus reply --text "<your response>"
+   ```
+   The broker autocompletes the `correlationId` with the last question directed to you (the one you just processed).
+5. If the question is outside your scope, still respond:
+   ```bash
+   refacil-sdd-ai bus reply --text "out of my scope, consult repo X"
+   ```
+6. **Run `refacil-sdd-ai bus attend` again** (step 1) to continue listening.
+
+**If the output contains "No questions in"**:
+- There were no questions in the interval.
+- **Run `refacil-sdd-ai bus attend` again** (step 1) to continue listening.
+
+### Step 3: Exit the mode
+
+The loop continues while the user (dev) does not give you another instruction or aborts with ESC. If the user gives you a new task in the middle of the loop, leave attend and attend to the new task.
+
+## When to use attend
+
+- When the dev says *"attend the bus for a while"* or *"stay listening to the bus while I do something else"*.
+- When you know another agent will consult you and you want to respond automatically.
+
+## When NOT to use attend
+
+- If you have an active task the user asked for — finish it first.
+- If the dev needs to use this session for something immediate — attend blocks the session.
+
+## Rules
+
+- If the `ask` implies **implementing a change in this repo** agreed by the room, after executing it use **`/refacil:propose`** (and the SDD-AI flow) and **close to the requester** via bus (`reply` or other channel according to `refacil-prereqs/BUS-CROSS-REPO.md`); do not close silently.
+- **Always re-invoke attend after responding** — a single `attend` handles a single question; you maintain the loop yourself.
+- **Do not respond from general knowledge**: use repo files as the source. If you do not know, say so.
+- **Do not send secrets or tokens** in responses — messages stay 7 days on local disk.
+- **Busy session**: while attend runs, the dev cannot use this session without aborting. If the dev interrupts you, leave attend and attend to the dev.
+- The internal timeout (9 min) is to stay within the Bash tool limit; it is not a total listening cap. By re-invoking, the loop is effectively infinite.

package/skills/bug/SKILL.md

@@ -1,128 +1,121 @@
----
-name: refacil:bug
-description: Flujo guiado completo para investigar y corregir bugs — delega la investigacion y el fix al sub-agente refacil-debugger en dos pasadas separadas por la confirmacion del usuario
-user-invocable: true
----
-
-# refacil:bug — Entrypoint de Bug Fix
-
-Este skill es un **wrapper** que guia al usuario por el flujo de bug fix y delega el trabajo pesado al sub-agente `refacil-debugger`. El sub-agente opera en dos modos: `investigation` (analiza y propone hipotesis sin modificar nada) y `fix` (implementa la correccion aprobada, genera tests y crea trazabilidad). La confirmacion de hipotesis y la validacion de rama ocurren en este wrapper, entre las dos invocaciones.
-
-**Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
-
-## Flujo
-
-### Paso 0: Verificar prerequisito de trazabilidad
-
-1. Verifica si existe la carpeta `openspec/` en la raiz del repo.
-2. Si NO existe, deten el flujo y muestra:
-   ```
-   Este flujo de bugfix requiere OpenSpec inicializado para guardar trazabilidad.
-   Ejecuta /refacil:setup y vuelve a correr /refacil:bug.
-   ```
-3. Si existe, continua al Paso 1.
-
-### Paso 1: Describir el bug
-
-Si `$ARGUMENTS` no trae suficiente informacion, pregunta al usuario:
-- Comportamiento actual vs. esperado.
-- Pasos de reproduccion.
-- Evidencia disponible (logs, stack traces).
-- Cuando empezo a ocurrir.
-- Severidad (Critico/Alto/Medio/Bajo).
-
-Si `$ARGUMENTS` ya es claro, no preguntes de nuevo.
-
-### Paso 2: Delegar investigacion al sub-agente refacil-debugger (mode: investigation)
-
-Invoca al sub-agente `refacil-debugger` pasandole:
-- `mode: investigation`
-- `description`: descripcion completa del bug (recogida en el Paso 1 o de `$ARGUMENTS`).
-
-El sub-agente:
-- Busca en el codebase simbolos/archivos de logs o stack traces.
-- Traza el flujo desde entrada hasta el punto de falla.
-- Revisa commits recientes si el bug es nuevo.
-- Retorna hipotesis ordenadas por confianza + correccion propuesta, fenced como ` ```refacil-debug-investigation `.
-
-### Paso 3: Confirmar hipotesis con el usuario
-
-Muestra al usuario las hipotesis y la correccion propuesta. Pregunta explicitamente:
-
-```
-Hipotesis de mayor confianza: [descripcion — archivo:linea]
-Correccion propuesta: [descripcion minima]
-Archivos a modificar: [lista]
-
-¿Confirmas esta hipotesis? (si/no/otra hipotesis N)
-¿Apruebas aplicar la correccion? (si/no)
-```
-
-**NO implementes nada hasta tener aprobacion explicita del usuario.**
-
-Segun la respuesta del usuario:
-
-- **"si" / aprobacion**: pasa al Paso 4 con la hipotesis #1 como `hypothesis` confirmada.
-- **"otra hipotesis N"** (ej. "hipotesis 2"): usa esa hipotesis como `hypothesis` confirmada para el Paso 5. La correccion propuesta puede ser diferente — resume al usuario la correccion de esa hipotesis alternativa y pide confirmacion de que aprueba aplicarla antes de continuar.
-- **"no" / rechazo sin alternativa**: ofrece al usuario dos opciones:
-  1. **Reinvestigar** — vuelve al Paso 2 con descripcion enriquecida (pide al usuario que aporte mas contexto: logs adicionales, steps de reproduccion, cuando empezo). El sub-agente `refacil-debugger` se invoca de nuevo en `mode: investigation` con la descripcion actualizada.
-  2. **Cancelar** — cierra el flujo sin modificar nada.
-  No continues hasta que el usuario elija una opcion.
-
-Si el sub-agente reporto `crossRepo: true` en alguna hipotesis: antes de implementar, aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para verificar con el agente del otro repo via el bus. Usa la respuesta para confirmar si el fix va en este repo, en el otro, o en ambos.
-
-### Paso 4: Validar rama de trabajo (antes de implementar)
-
-Ejecuta `git branch --show-current` para obtener la rama actual.
-
-Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
-
-- Si la rama actual es protegida, ejecutar ese protocolo completo antes de continuar.
-- Para `refacil:bug`, el prefijo sugerido de rama es `fix/`.
-- Si la rama actual ya es de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continuar sin interrumpir.
-
-### Paso 5: Delegar implementacion al sub-agente refacil-debugger (mode: fix)
-
-Invoca al sub-agente `refacil-debugger` pasandole:
-- `mode: fix`
-- `description`: descripcion completa del bug.
-- `hypothesis`: causa raiz confirmada por el usuario en el Paso 3.
-
-El sub-agente:
-- Implementa el fix minimo y enfocado.
-- Genera tests de regresion (reproduce el bug + verifica el fix + no regresion).
-- Crea `openspec/changes/fix-<nombre>/summary.md` con trazabilidad.
-- Ejecuta todos los tests del proyecto.
-- Retorna el reporte fenced como ` ```refacil-debug-fix `.
-
-### Paso 6: Presentar resultado y siguiente paso
-
-Muestra al usuario el **reporte** (todo lo anterior al bloque `refacil-debug-fix`). No muestres el bloque JSON — es metadata interna.
-
-Agrega al final:
-
-```
-El siguiente paso es el review del fix (obligatorio antes de archivar).
-Quieres que continue con /refacil:review?
-(Luego el flujo sigue con /refacil:archive y /refacil:up-code)
-```
-
-Si el sub-agente retorno `result: "FALLO"` (tests no pasan), presenta el detalle de los tests fallidos y ofrece al usuario:
-1. **Reintentar** — el sub-agente `refacil-debugger` se invoca de nuevo en `mode: fix` con la misma hipotesis mas el contexto del fallo de tests.
-2. **Cancelar** — cierra el flujo sin archivar. Los archivos modificados quedan en la rama para revision manual.
-
-## Reglas
-
-- **Siempre investiga antes de proponer** — no delegar el fix sin hipotesis confirmada.
-- **NUNCA implementar sin aprobacion explicita del usuario** (Paso 3).
-- **Siempre valida la rama** (Paso 4) antes de delegar el fix.
-- **No repliques aqui la logica de investigacion ni de implementacion** — eso vive en `refacil-debugger`.
-- **No muestres los bloques JSON al usuario**. Son metadata interna del wrapper.
-- El Paso 3 (bus cross-repo) es **opcional** — solo aplica si el sub-agente reporto `crossRepo: true`.
-- Responder en espanol con terminos tecnicos en ingles.
-- **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad del Paso 6, invocar inmediatamente el **Skill tool** con `skill: "refacil:review"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:review`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
-
-## Ver tambien
-
-- Sub-agente: `.claude/agents/refacil-debugger.md` (fuente: `refacil-sdd-ai/agents/debugger.md`)
-- Bus cross-repo: `refacil-prereqs/BUS-CROSS-REPO.md`
+---
+name: refacil:bug
+description: Guided complete flow to investigate and fix bugs — delegates investigation and fix to the refacil-debugger sub-agent in two passes separated by user confirmation
+user-invocable: true
+---
+
+# refacil:bug — Bug Fix Entrypoint
+
+This skill is a **wrapper** that guides the user through the bug fix flow and delegates the heavy work to the `refacil-debugger` sub-agent. The sub-agent operates in two modes: `investigation` (analyzes and proposes hypotheses without modifying anything) and `fix` (implements the approved correction, generates tests, and creates traceability). Hypothesis confirmation and branch validation occur in this wrapper, between the two invocations.
+
+**Prerequisites**: `agents` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md`.
+
+## Flow
+
+### Step 0: Verify traceability prerequisite
+
+1. Verify that the `refacil-sdd/` folder exists in the repo root.
+2. If it does NOT exist, stop the flow and show:
+   ```
+   This bugfix flow requires the SDD-AI methodology initialized to save traceability.
+   Run /refacil:setup and re-run /refacil:bug.
+   ```
+3. If it exists, continue to Step 1.
+
+### Step 1: Describe the bug
+
+If `$ARGUMENTS` does not bring enough information, ask the user:
+- Current vs. expected behavior.
+- Reproduction steps.
+- Available evidence (logs, stack traces).
+- When it started occurring.
+- Severity (Critical/High/Medium/Low).
+
+If `$ARGUMENTS` is already clear, do not ask again.
+
+### Step 2: Delegate investigation to the refacil-debugger sub-agent (mode: investigation)
+
+Invoke the `refacil-debugger` sub-agent passing it:
+- `mode: investigation`
+- `description`: complete bug description (collected in Step 1 or from `$ARGUMENTS`).
+
+The sub-agent:
+- Searches the codebase for symbols/files from logs or stack traces.
+- Traces the flow from entry to the failure point.
+- Reviews recent commits if the bug is new.
+- Returns hypotheses ordered by confidence + proposed correction, fenced as ` ```refacil-debug-investigation `.
+
+### Step 3: Confirm hypothesis with the user
+
+Show the user the hypotheses and the proposed correction. Ask explicitly:
+
+```
+Most confident hypothesis: [description — file:line]
+Proposed fix: [minimal description]
+Files to modify: [list]
+
+Do you confirm this hypothesis? (yes/no/other hypothesis N)
+Do you approve applying the fix? (yes/no)
+```
+
+**Do NOT implement anything until you have explicit user approval.**
+
+According to the user's response:
+
+- **"yes" / approval**: proceed to Step 4 with hypothesis #1 as the confirmed `hypothesis`.
+- **"other hypothesis N"** (e.g. "hypothesis 2"): use that hypothesis as the confirmed `hypothesis` for Step 5. The proposed correction may differ — summarize the fix for that alternative hypothesis to the user and ask for confirmation that they approve applying it before continuing.
+- **"no" / rejection without alternative**: offer the user two options:
+  1. **Re-investigate** — return to Step 2 with an enriched description (ask the user to provide more context: additional logs, reproduction steps, when it started). The `refacil-debugger` sub-agent is invoked again in `mode: investigation` with the updated description.
+  2. **Cancel** — close the flow without modifying anything.
+  Do not continue until the user chooses an option.
+
+If the sub-agent reported `crossRepo: true` in any hypothesis: before implementing, apply the protocol from `refacil-prereqs/BUS-CROSS-REPO.md` to verify with the other repo's agent via the bus. Use the response to confirm whether the fix goes in this repo, the other, or both.
+
+### Step 4: Validate working branch (before implementing)
+
+Run `git branch --show-current` to get the current branch.
+
+Apply the **Protected branch policy and branch creation** defined in `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
+
+- If the current branch is protected, execute the full protocol before continuing.
+- For `refacil:bug`, the suggested branch prefix is `fix/`.
+- If the current branch is already a working branch (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continue without interruption.
+
+### Step 5: Delegate implementation to the refacil-debugger sub-agent (mode: fix)
+
+Invoke the `refacil-debugger` sub-agent passing it:
+- `mode: fix`
+- `description`: complete bug description.
+- `hypothesis`: root cause confirmed by the user in Step 3.
+
+The sub-agent:
+- Implements the minimal and focused fix.
+- Generates regression tests (reproduces the bug + verifies the fix + no regression).
+- Creates `refacil-sdd/changes/fix-<name>/summary.md` with traceability.
+- Runs all project tests.
+- Returns the report fenced as ` ```refacil-debug-fix `.
+
+### Step 6: Present result and next step
+
+Show the user the **report** (everything before the `refacil-debug-fix` block). Do not show the JSON block — it is internal metadata.
+
+Add at the end:
+
+```
+The next step is the fix review (mandatory before archiving).
+Do you want me to continue with /refacil:review?
+(The flow then continues with /refacil:archive and /refacil:up-code)
+```
+
+If the sub-agent returned `result: "FAILED"` (tests not passing), present the failing test details and offer the user:
+1. **Retry** — the `refacil-debugger` sub-agent is invoked again in `mode: fix` with the same hypothesis plus the test failure context.
+2. **Cancel** — close the flow without archiving. The modified files remain in the branch for manual review.
+
+## Rules
+
+- **Always investigate before proposing** — do not delegate the fix without a confirmed hypothesis.
+- **NEVER implement without explicit user approval** (Step 3).
+- **Always validate the branch** (Step 4) before delegating the fix.
+- **Do not replicate investigation or implementation logic here** — that lives in `refacil-debugger`.
+- Step 3 (bus cross-repo) is **optional** — only applies if the sub-agent reported `crossRepo: true`.
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 6, immediately invoke the **Skill tool** with `skill: "refacil:review"`. Do not describe it in text or wait for the user to type `/refacil:review`. (See `METHODOLOGY-CONTRACT.md §5`.)

package/skills/explore/SKILL.md

@@ -1,63 +1,73 @@
----
-name: refacil:explore
-description: Explorar e investigar el codebase antes de hacer cambios — delega al sub-agente refacil-investigator para analizar arquitectura, flujos y dependencias sin modificar nada
-user-invocable: true
----
-
-# refacil:explore — Entrypoint de Exploracion
-
-Este skill es un **wrapper delgado** que delega la investigacion al sub-agente `refacil-investigator`. El sub-agente corre en contexto aislado (no satura tu sesion principal con lecturas masivas de archivos) y retorna un reporte conciso con arquitectura, flujos y recomendaciones.
-
-**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` — usa `AGENTS.md` como contexto activo durante toda la exploracion.
-
-## Flujo
-
-### Paso 0: Validar pregunta
-
-- Si `$ARGUMENTS` viene vacio, pide al usuario la pregunta o topico a explorar ANTES de invocar al sub-agente.
-- Si hay pregunta, continua.
-
-### Paso 1: Delegar al sub-agente refacil-investigator
-
-Invoca al sub-agente `refacil-investigator` pasandole:
-- La pregunta del usuario (`$ARGUMENTS`).
-- Si el usuario pidio modo detallado explicitamente, indicaselo (`mode: detailed`). Default: conciso.
-
-El sub-agente:
-- Delega a OpenSpec explore para la exploracion base.
-- Enriquece con patrones y convenciones de `AGENTS.md`.
-- Detecta dependencias cross-repo y, si corresponde, consulta el bus segun `refacil-prereqs/BUS-CROSS-REPO.md`.
-- Retorna un reporte con arquitectura, flujos, dependencias y recomendaciones de siguiente paso.
-
-### Paso 2: Presentar el reporte
-
-Muestra al usuario el reporte completo que retorno el sub-agente. No hay artefactos que escribir — exploracion es puramente analitica.
-
-Si el sub-agente pidio clarificacion (porque el prompt no traia pregunta explicita), propaga la pregunta al usuario.
-
-### Paso 3: Siguiente paso
-
-El sub-agente ya incluye recomendaciones al final de su reporte. Aplica la regla de continuidad natural de `METHODOLOGY-CONTRACT.md §5`:
-
-- Si el reporte converge en **un solo** siguiente paso (ej. el hallazgo claramente indica un feature nuevo o un bug), cierra con la formula unica:
-  - *"El siguiente paso es [descripcion]. Quieres que continue con `/refacil:propose`?"* (o `/refacil:bug`, segun corresponda).
-- Si hay **varios caminos validos**, listalos numerados y pide al usuario seleccionar.
-
-## Reglas
-
-- **Siempre delega al sub-agente**. No repliques la logica de exploracion aqui.
-- **No invoques sin pregunta**. Si `$ARGUMENTS` esta vacio, pide la pregunta primero.
-- **No escribes archivos**. Exploracion es read-only end-to-end.
-- **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad del Paso 3, invocar inmediatamente el **Skill tool** con el nombre exacto resuelto a partir del hallazgo del sub-agente. Resolucion determinista:
-  - Hallazgo = feature nuevo o mejora → `skill: "refacil:propose"`
-  - Hallazgo = bug funcional o error en produccion → `skill: "refacil:bug"`
-  - Hallazgo = falta configuracion inicial del repo → `skill: "refacil:setup"`
-  - Hallazgo = duda de flujo o no queda claro el siguiente comando → `skill: "refacil:guide"`
-  - Si no hay match claro, NO invocar — listar opciones numeradas al usuario y pedir seleccion explicita antes de continuar.
-
-  No describirlo en texto ni esperar que el usuario escriba el comando. (Ver `METHODOLOGY-CONTRACT.md §5`.)
-
-## Ver tambien
-
-- Sub-agente: `.claude/agents/refacil-investigator.md` (fuente: `refacil-sdd-ai/agents/investigator.md`)
-- Bus cross-repo: `refacil-prereqs/BUS-CROSS-REPO.md`
+---
+name: refacil:explore
+description: Explore and investigate the codebase before making changes — delegates to the refacil-investigator sub-agent to analyze architecture, flows, and dependencies without modifying anything
+user-invocable: true
+---
+
+# refacil:explore — Exploration Entrypoint
+
+This skill is a **thin wrapper** that delegates the investigation to the `refacil-investigator` sub-agent. The sub-agent runs in an isolated context (does not saturate your main session with massive file reads) and returns a concise report with architecture, flows, and recommendations.
+
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` — use `AGENTS.md` as active context throughout the entire exploration.
+
+## Flow
+
+### Step 0: Validate question
+
+- If `$ARGUMENTS` is empty, ask the user for the question or topic to explore BEFORE invoking the sub-agent.
+- If there is a question, continue.
+
+### Step 0.1: Duplicate exploration guard (CA-11)
+
+Before delegating, check the current session conversation context for a prior complete exploration report with overlapping scope (same modules, files, or question topic):
+
+- **If a prior complete exploration exists for the same or highly overlapping topic**: summarize the already-known context in 2-3 sentences and ask:
+  ```
+  I already explored [topic] earlier in this session. The key findings were: [summary].
+  Do you want me to run a targeted follow-up on a specific aspect, or proceed with a new full exploration?
+  ```
+  Wait for the user's answer before proceeding.
+- **If there is no prior exploration** (or it is on a clearly different topic): continue to Step 1 without interruption.
+
+### Step 1: Delegate to the refacil-investigator sub-agent
+
+Invoke the `refacil-investigator` sub-agent passing it:
+- The user's question (`$ARGUMENTS`).
+- If the user explicitly requested detailed mode, indicate it (`mode: detailed`). Default: concise.
+
+The sub-agent:
+- Explores the codebase natively (Read/Grep with discipline — see sub-agent rules).
+- Enriches with patterns and conventions from `AGENTS.md`.
+- Detects cross-repo dependencies and, if appropriate, consults the bus according to `refacil-prereqs/BUS-CROSS-REPO.md`.
+- Returns a report with architecture, flows, dependencies, and next-step recommendations.
+
+### Step 2: Present the report
+
+Show the user the full report returned by the sub-agent. There are no artifacts to write — exploration is purely analytical.
+
+If the sub-agent asked for clarification (because the prompt did not carry an explicit question), propagate the question to the user.
+
+### Step 3: Next step
+
+The sub-agent already includes recommendations at the end of its report. Apply the natural continuity rule from `METHODOLOGY-CONTRACT.md §5`:
+
+- If the report converges on **one single** next step (e.g. the finding clearly indicates a new feature or a bug), close with the single formula:
+  - *"The next step is [description]. Do you want me to continue with `/refacil:propose`?"* (or `/refacil:bug`, as appropriate).
+- If there are **multiple valid paths**, list them numbered and ask the user to select.
+
+## Rules
+
+- **Always delegate to the sub-agent**. Do not replicate the exploration logic here.
+- **Do not invoke without a question**. If `$ARGUMENTS` is empty, ask for the question first.
+- **Do not write files**. Exploration is read-only end-to-end.
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 3, immediately invoke the **Skill tool** with the exact name resolved from the sub-agent's finding. Deterministic resolution:
+
+  | Finding | Skill |
+  |---------|-------|
+  | New feature or improvement | `refacil:propose` |
+  | Functional bug or production error | `refacil:bug` |
+  | Missing initial repo configuration | `refacil:setup` |
+  | Flow doubt or next command unclear | `refacil:guide` |
+  | No clear match | Do NOT invoke — list numbered options and ask for explicit selection |
+
+  Do not describe it in text or wait for the user to type the command. (See `METHODOLOGY-CONTRACT.md §5`.)