| name | health-check |
| description | Diagnóstico de iAmasters OS con VALIDACIÓN PROFUNDA. v0.6 - no solo comprueba que existan archivos, sino que sean válidos y funcionales (JSON parseable, hooks ejecutables, contenido real >100 chars, etc.). Cruza con ~/.claude/skills/_install-state.json para detectar drift (state dice done pero archivos faltan, o al revés). Devuelve reporte 🟢🟡🔴 con acciones concretas. Soporta auto-fix limitado. Se invoca vía /doctor o cuando otra skill detecta inconsistencia. |
health-check
Cambio crítico v0.6: ya no validas "el archivo existe". Validas que el archivo sea funcionalmente correcto: JSON parseable, contenido real, hooks ejecutables, contadores razonables.
La fuente de verdad sobre qué debería estar instalado es ~/.claude/skills/_install-state.json. Si dice que sinapsis-engine está done pero la validación profunda falla, eso es drift y hay que reportarlo (y opcionalmente arreglarlo).
Cuándo se invoca
- Usuario ejecuta
/doctor
meta-start-here detecta inconsistencia al arrancar sesión- Tras
update.sh para verificar la actualización
- Usuario reporta "algo no funciona" sin saber qué
- (NUEVA)
/install post-fase invoca para validar antes de marcar done
Process
Paso 0 · Leer fuente de verdad
Lee ~/.claude/skills/_install-state.json con la tool Read. Si NO existe:
- Reporta 🔴 instalación no iniciada
- Indica al usuario ejecutar
bash scripts/install.sh
- Para.
Guarda en memoria mental:
- Qué fases dice el state que están
done
- Lista de
completedPhases
- Errores recientes en
errors[]
Paso 1 · Verificación entorno (validación profunda)
| Check | Validación REAL | Severidad si falla |
|---|
| Claude Code CLI / app | which claude o env var CLAUDECODE / CLAUDE_DESKTOP o ~/Applications/Claude.app | 🔴 si nada detectado |
| Repo raíz correcto | CLAUDE.md + .claude/ + vendor/sinapsis/ en pwd | 🔴 si falta alguno |
| Git inicializado | .git/ existe | 🟡 |
.env válido | Existe Y no tiene líneas obviamente rotas (no sintaxis tipo KEY:value) | 🟡 |
| Node.js ≥18 | node --version parseable, mayor ≥18 | 🔴 (Sinapsis hooks lo requieren) |
| Python 3 disponible | python3 --version o py -3 --version o python --version con Python 3 | 🟡 |
Usa la tool Bash para los which/--version.
Paso 2 · Verificación Sinapsis (validación PROFUNDA)
Esta sección es la que evita "instalaciones fantasma". No te fíes de que el archivo exista — valídalo:
| Check | Validación real | Severidad |
|---|
_operator-state.json parseable | node -e "JSON.parse(require('fs').readFileSync('~/.claude/skills/_operator-state.json'))" no falla | 🔴 |
_operator-state.json tiene campos mínimos | .operator.name y .operator.language no son null/empty | 🟡 (sin esto el wizard no ha terminado) |
_catalog.json parseable | mismo | 🟡 |
| Hooks ejecutables (5 hooks) | _passive-activator.sh, _instinct-activator.sh, _session-learner.sh, _project-context.sh, _eod-gather.sh existen Y tienen permiso +x | 🔴 si falla ≥2, 🟡 si falla 1 |
| ≥1 SKILL.md instalada | find ~/.claude/skills -maxdepth 3 -name SKILL.md devuelve ≥1 resultado | 🔴 |
| Hooks registrados en settings.json | ~/.claude/settings.json parseable Y contiene la sección hooks.PreToolUse con referencias a _passive-activator.sh | 🟡 |
| Install-gate registrado | ~/.claude/settings.json contiene hooks.SessionStart con referencia a _install-gate.sh | 🟡 |
| DRIFT check | Si _install-state.json.phases.sinapsis-engine.status == "done" Y alguno de los anteriores falla → DRIFT | 🔴 con flag "STATE DRIFT" |
Para los checks de hooks ejecutables, usa Bash:
for h in _passive-activator.sh _instinct-activator.sh _session-learner.sh _project-context.sh _eod-gather.sh; do
[ -x "$HOME/.claude/skills/$h" ] && echo "OK $h" || echo "FAIL $h"
done
Paso 3 · Verificación capa OS — brand-context
| Check | Validación | Severidad |
|---|
brand-context/ existe | sí | 🔴 |
voice/voice-profile.md | Existe + >100 chars | 🟡 (skill: marketing-brand-voice) |
voice/samples.md | Existe + >100 chars | 🟡 |
| Registros A/B/C | Los 3 archivos existen | 🟡 |
positioning/positioning.md | Existe + >100 chars | 🟡 |
icp/icp.md | Existe + >100 chars | 🟡 |
Paso 4 · Verificación capa OS — context sectorizado (con drift check)
Para CADA uno de los 4 archivos críticos:
| Check | Validación | Severidad |
|---|
context/me.md | Existe + >100 chars + contiene ## Nombre con valor real | 🟡 si vacío (skill: meta-onboarding-wizard) |
context/work.md | Existe + >100 chars + contiene ## Qué hago | 🟡 |
context/current-priorities.md | Existe + >100 chars + tiene al menos una prioridad listada | 🟡 |
context/goals.md | Existe + >100 chars | 🟡 |
context/team.md | Existe (puede estar vacío si trabaja solo) | 🟢 |
context/decisions-log.md | Existe con header canónico | 🟡 auto-fix |
context/learnings.md | Existe | 🟢 auto-fix |
context/soul.md | Existe + >100 chars | 🟡 |
DRIFT check para context-files:
- Si
state.phases.context-files.status == "done" PERO alguno de los 4 archivos críticos no existe o tiene <100 chars → reporta 🔴 STATE DRIFT + propone fix:
"El state dice que context-files está done pero <archivo> está vacío/inexistente. Esto indica una marca falsa. Voy a revertir el state a in-progress y reactivar el wizard. ¿Continúo?"
Paso 4.5 · Verificación Loop Engine
Skip silencioso si no existe loops/ o no hay carpetas de loop en loops/<nombre>/ (excluye _templates/).
Si hay ≥1 loop creado:
| Check | Validación | Severidad |
|---|
context/loops-config.md | Existe | 🟡 |
loops/_index.md | Existe | 🟡 |
Cada loop tiene loop-spec.md | Existe | 🔴 |
Cada loop tiene REGLAS.md | Existe | 🔴 |
loops/_index.md lista todos los loops | Cada carpeta loops/<nombre>/ aparece en el índice | 🟡 |
| Reglas por estación | Si una estación tiene >12 reglas en un REGLAS.md → ⚠️ "esa estación necesita rediseño" | 🟡 |
Reporte sugerido:
### Loop Engine
🟢 3 loops detectados
🟢 propuestas: loop-spec.md + REGLAS.md
🟡 onboarding-clientes no aparece en loops/_index.md
🟡 propuestas · estación redacción tiene 14 reglas → esa estación necesita rediseño
Paso 5 · Verificación skills curadas
Lista skills mínimas (v0.6 Capa 1):
.claude/skills/_meta/meta-skill-creator/SKILL.md
.claude/skills/_meta/meta-onboarding-wizard/SKILL.md
.claude/skills/_meta/meta-deep-dive/SKILL.md
.claude/skills/_meta/meta-start-here/SKILL.md
.claude/skills/_meta/meta-wrap-up/SKILL.md
.claude/skills/_meta/welcome-quick-win/SKILL.md
.claude/skills/_meta/seis-sombreros/SKILL.md
.claude/skills/_meta/decisions-log/SKILL.md
.claude/skills/_meta/health-check/SKILL.md
.claude/skills/_meta/find-skills/SKILL.md
.claude/skills/marketing/marketing-brand-voice/SKILL.md
.claude/skills/marketing/marketing-positioning/SKILL.md
.claude/skills/marketing/marketing-icp/SKILL.md
.claude/skills/marketing/marketing-copywriting/SKILL.md
.claude/skills/marketing/marketing-content-repurposing/SKILL.md
.claude/skills/marketing/marketing-email-sequence/SKILL.md
.claude/skills/automation/automation-loop-engine/SKILL.md
.claude/skills/automation/automation-n8n-to-claude/SKILL.md
.claude/skills/automation/automation-n8n-builder/SKILL.md
.claude/skills/strategy/strategy-web-research/SKILL.md
.claude/skills/tools/tool-firecrawl-scraper/SKILL.md
.claude/skills/tools/tool-humanizer/SKILL.md
.claude/skills/tools/tool-output-verifier/SKILL.md
.claude/skills/visualization/tool-visual-explainer/SKILL.md
Por cada faltante: 🟡 con sugerencia "ejecuta bash scripts/update.sh para sincronizar".
Paso 6 · Verificación settings
| Check | Validación | Severidad |
|---|
.claude/settings.json del repo parseable | JSON válido | 🔴 |
~/.claude/settings.json global parseable | JSON válido | 🔴 |
| Permissions seguras (repo) | No Bash(*) ni similares peligrosos en permissions.allow | 🟡 |
| No secrets en settings | No hay strings que parezcan API keys (busca sk-, fc-, pk_) | 🔴 |
Paso 7 · Verificación API keys (opcionales, en .env)
| Check | Validación | Severidad |
|---|
FIRECRAWL_API_KEY | Set + empieza por fc- + ≥20 chars | 🟡 (sin esto, scraping manual) |
Otras keys mencionadas en .env.example | Set si están documentadas | 🟢 (informativo) |
Paso 8 · Compilar reporte
Genera reporte estructurado:
# 🩺 iAmasters OS · Health Check v0.6
📅 <fecha y hora>
📂 Repo: <ruta absoluta>
👤 Operador: <nombre desde operator-state o "(sin nombre)">
🎯 Versión OS: <leer de CHANGELOG.md primera línea>
## Resumen
🟢 OK: <N> componentes
🟡 AVISO: <N> componentes
🔴 ERROR: <N> componentes
State machine: <X>/5 required phases done · <currentPhase>
## State Drift detectado
<si hay drift, listarlo aquí. Si no, omitir esta sección>
## Detalle
### Entorno
🟢 Claude Code detectado
🟢 Node v20.10.0
🟡 Python no detectado
### Sinapsis (validación profunda)
🟢 _operator-state.json parseable + campos mínimos
🟢 _catalog.json parseable
🟢 5/5 hooks ejecutables
🟢 27 SKILL.md instaladas
🟢 Hooks Sinapsis registrados en settings.json
🟢 Install-gate registrado en settings.json
🟢 No hay drift
### Capa OS — Brand Context
🟡 voice-profile.md vacío
→ Acción: ejecuta `marketing-brand-voice` (10 min)
### Capa OS — Context sectorizado
🟢 me.md (456 chars · nombre: Angel)
🟢 work.md (812 chars)
🟢 current-priorities.md (234 chars · 3 prioridades)
🟢 goals.md (180 chars)
### Skills curadas
🟢 27/27 skills core presentes
### Settings
🟢 Repo settings.json válido
🟢 Global settings.json válido
🟢 Sin secretos hardcoded
### API keys
🟡 FIRECRAWL_API_KEY no encontrada
## Próximas acciones (orden por impacto)
1. <acción 1>
2. <acción 2>
3. <acción 3>
Paso 9 · Auto-fix limitado
Solo ofrece auto-fix para problemas reversibles y seguros:
Detecté <N> problemas con fix automático:
• Crear context/decisions-log.md con header (si falta)
• Crear context/learnings.md con header (si falta)
• Re-aplicar chmod +x a hooks Sinapsis (si no son ejecutables)
• Re-registrar _install-gate.sh en ~/.claude/settings.json (si fue removido)
¿Aplico los fixes? (s/n)
Si dice "s", aplícalos uno a uno mostrando qué hace cada uno.
Fix de DRIFT es ESPECIAL — requiere confirmación explícita extra:
🚨 STATE DRIFT detectado en fase "<X>".
El state dice "done" pero la validación profunda falla.
Quiero revertir el state a "in-progress" para que el sistema fuerce
re-ejecutar la fase. Esto NO borra archivos — solo cambia el flag.
¿Confirmas? (escribe "sí, revertir")
Si responde literal "sí, revertir": revierte el state. Si dice cualquier otra cosa: NO toques nada.
Paso 10 · Cierre
- Si todo 🟢: muestra proyectos abiertos (
projects/briefs/*/brief.md con status: active) y propón continuar
- Si hay 🟡: plan de acción priorizado
- Si hay 🔴 o DRIFT: bloqueante, sugiere fix antes de seguir
- Append a
context/learnings.md SOLO si descubriste algo recurrente (no por cada ejecución)
Outputs
- Reporte en chat (Paso 8)
- Opcional: HTML compartible vía
tool-visual-explainer si >5 🟡
- (Si auto-fix aplicado) archivos creados/permisos modificados
Edge cases
- Repo abierto pero no es iamasters-os: detecta ausencia de
vendor/sinapsis/ → "no estás en un repo iamasters-os, este check no aplica"
- State file no existe: reporta como 🔴 fundamental, sugiere
bash scripts/install.sh
- State file corrupto (JSON inválido): reporta 🔴, sugiere
bash scripts/install.sh --force-reinstall
- Drift en múltiples fases simultáneamente: lista cada una con su detalle, ofrece revertir todas con UN solo confirmador
- Cliente activo en
clients/<X>/: validar también su sub-context
Auto-fixes disponibles (resumen)
| Fix | Sin preguntar | Requiere "sí" | Requiere "sí, revertir" |
|---|
| Crear decisions-log.md / learnings.md vacío | — | ✓ | — |
| chmod +x a hooks | — | ✓ | — |
| Re-registrar install-gate hook | — | ✓ | — |
| Revertir state drift | — | — | ✓ |
Crear .env desde .env.example | — | ✓ | — |
| Cualquier fix de Sinapsis instalación | (delegar a bash scripts/install.sh --resume) | | |
Notas operativas
- NO recolectas datos personales ni cambias configuración de comportamiento
- Output rápido de leer — usuario debe entender en 30s el estado general
- 🟡 NO bloquea uso, 🔴 SÍ bloquea uso, DRIFT es 🔴 con tratamiento especial
- Si reporta >8 🟡 considera generar HTML compartible
