Communitygithub.com

majiayu000/skill-registro-datos-claude

Investigación sistemática y análisis de causa raíz. Útil para depurar problemas persistentes, comprender sistemas complejos o antes de tomar decisiones arquitectónicas.

¿Qué es skill-registro-datos-claude?

Esta habilidad está diseñada para ayudar a agentes de IA como Claude a realizar investigaciones sistemáticas y análisis de causa raíz. Es particularmente útil cuando se enfrentan errores persistentes que no se resuelven después de múltiples intentos de corrección, para comprender bases de código desconocidas, investigar incidentes de producción o tomar decisiones arquitectónicas informadas. La habilidad proporciona un árbol de decisión rápido para determinar cuándo cambiar del modo de iteración al modo de investigación, principios básicos como investigar antes de iterar, leer fuentes primarias (documentación oficial, código fuente), reproducir problemas localmente e inspeccionar datos reales. También incluye flujos de trabajo detallados para escenarios comunes como discrepancias de tipos de datos, incidentes de producción y exploración de bases de código desconocidas, así como un marco de verificación de límites para sistemas distribuidos. La habilidad se basa en herramientas como AWS CLI, Git, ripgrep, jq, curl y DevTools del navegador, y es compatible con plataformas como Claude Code, Cursor y Codex, guiando al agente a través de un proceso estructurado de observación, hipótesis, investigación, validación y reflexión.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/analysis/research-awannaphasch2016-jousef-landing

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Habilidad de Investigación

Stack Tecnológico: AWS CLI, Git, ripgrep, jq, curl, DevTools del navegador

Fuente: Extraído de los principios de investigación y patrones de depuración de CLAUDE.md.


Cuándo Usar Esta Habilidad

Usa la habilidad de investigación cuando:

  • ✓ El mismo error persiste después de 2+ intentos de corrección
  • ✓ Necesitas comprender una base de código desconocida
  • ✓ Estás investigando incidentes de producción
  • ✓ Estás tomando decisiones arquitectónicas
  • ✓ Estás depurando interacciones complejas del sistema
  • ✓ Estás aprendiendo una nueva tecnología/biblioteca

NO uses esta habilidad para:

  • ✗ Primer intento de corrección (prueba primero la solución obvia)
  • ✗ Problemas bien comprendidos (simplemente arréglalos)
  • ✗ Incidentes críticos de tiempo (corrige primero, investiga después)

Árbol de Decisión Rápida para Investigación

¿Cuál es el problema?
├─ ¿Es la primera vez que ves este problema?
│  ├─ SÍ → Intenta la corrección obvia (iteración)
│  └─ NO → ¿El mismo error después de 2 intentos? → INVESTIGACIÓN
│
├─ ¿Incidente de producción?
│  ├─ ¿Afecta a usuarios AHORA? → Reversión/corrección rápida primero, investigar después
│  └─ ¿Análisis posterior al incidente? → Investigación profunda
│
├─ ¿Necesitas comprender la base de código?
│  ├─ ¿Función/módulo específico? → Leer código + pruebas
│  ├─ ¿Arquitectura del sistema? → Rastrear el flujo de solicitudes
│  └─ ¿Contexto histórico? → Git blame + historial de commits
│
├─ ¿Decisión tecnológica?
│  ├─ Leer documentación oficial (no publicaciones de blog)
│  ├─ Comparar alternativas (compensaciones)
│  ├─ Crear prototipo con un caso de uso real
│  └─ Documentar la decisión (ADR)
│
└─ ¿Integración de API/Biblioteca?
   ├─ Leer requisitos de tipo (no asumir)
   ├─ Verificar compatibilidad de versiones
   ├─ Probar un ejemplo mínimo
   └─ Verificar con datos reales

Patrón de Bucle: Meta-Bucle → Inicial-Sensible

Desencadenante de Escalada:

  • /reflect revela: "He intentado 3 correcciones, todas fallaron con el mismo error"
  • La salida de /trace es idéntica en todos los intentos
  • Patrón: Atascado en un bucle de reintento (la ejecución cambia, el resultado no)
  • Acción: Usa /hypothesis para cuestionar suposiciones (cambiar a inicial-sensible)

Herramientas Utilizadas:

  • /observe - Observar el comportamiento del sistema (qué está fallando)
  • /hypothesis - Generar explicaciones alternativas (¿por qué podría fallar de manera diferente a lo que pienso?)
  • /research - Probar hipótesis sistemáticamente
  • /validate - Verificar si la nueva comprensión es correcta
  • /reflect - Sintetizar aprendizajes después de la investigación

Por Qué Funciona: La habilidad de investigación se ajusta naturalmente al bucle inicial-sensible: estás cuestionando suposiciones, no solo corrigiendo la ejecución.

Consulta Arquitectura del Proceso de Pensamiento - Bucles de Retroalimentación para una visión estructural.


Principios Básicos de Investigación

Principio 1: Investigar Antes de Iterar

De CLAUDE.md:

"Cuando el mismo error persiste después de 2 intentos de corrección, DEJA DE ITERAR y EMPIEZA A INVESTIGAR. Invierte 30-60 minutos en comprender la causa raíz en lugar de implementar más suposiciones."

Por Qué Es Importante:

  • ❌ Iteración: Retroalimentación rápida, pero derrochadora después de 2+ intentos fallidos
  • ✅ Investigación: Costo inicial, previene 3+ ciclos de implementación fallidos

Patrón:

Intento 1: Hipótesis + Implementación (8 minutos)
  ↓ Falló
Intento 2: Hipótesis diferente + Implementación (8 minutos)
  ↓ Falló
Intento 3: ❌ DETENER - No implementes otra suposición

CAMBIAR A MODO DE INVESTIGACIÓN:
  - Leer especificaciones/documentación (15 minutos)
  - Inspeccionar datos reales (10 minutos)
  - Reproducir localmente (20 minutos)
  - Identificar causa raíz (15 minutos)
  ↓ Total: 60 minutos de investigación

Intento 3 (con causa raíz): Implementar corrección (8 minutos)
  ✅ Éxito

Tiempo total: 76 minutos (vs 120+ minutos con iteración ciega)

Principio 2: Leer Fuentes Primarias

Jerarquía de Calidad de la Información:

Tipo de FuenteFiabilidadCuándo Usar
Documentación OficialMás AltaPrimer paso para comportamiento de API, requisitos de tipo
Código FuenteMuy AltaCuando la documentación no es clara o está incompleta
Issues de GitHubAltaPara errores conocidos, casos límite, soluciones alternativas
Stack OverflowMediaPara problemas comunes, después de leer la documentación
Publicaciones de BlogBajaPara conceptos generales, no detalles de implementación
ChatGPT/IAMás BajaSolo punto de partida, siempre verificar

Ejemplo: Integración del Sistema de Tipos

# ❌ NO HAGAS: Preguntar a ChatGPT "¿Acepta PyMySQL diccionarios para columnas JSON?"
# ChatGPT podría alucinar o dar una respuesta desactualizada

# ✅ HAZ: Leer la documentación de PyMySQL
open https://pymysql.readthedocs.io/en/latest/

# ✅ HAZ: Probar con un ejemplo mínimo
python3 << 'EOF'
import pymysql
import json

# Prueba: ¿Acepta PyMySQL un dict para columna JSON?
data = {'key': 'value'}

try:
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    print("✅ Dict aceptado")
except TypeError as e:
    print(f"❌ Dict rechazado: {e}")
    # Probar con cadena JSON en su lugar
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("✅ Cadena JSON aceptada")
EOF

Principio 3: Reproducir Localmente

Antes de implementar correcciones, reproduce el problema localmente.

Beneficios:

  • ✅ Iteración rápida (segundos vs minutos)
  • ✅ Se puede depurar con puntos de interrupción
  • ✅ Sin costos en la nube
  • ✅ Se pueden probar casos límite fácilmente

Patrón:

# Paso 1: Extraer el caso mínimo de fallo
# En lugar de probar toda la función Lambda...

# ❌ MALO: Implementar en AWS, revisar registros, repetir
aws lambda invoke --function-name worker --payload '{}' /tmp/response.json
# Esperar 30 segundos por los registros de CloudWatch...

# ✅ BUENO: Reproducir localmente
python3 << 'EOF'
from src.data.news_fetcher import NewsFetcher

# Mismo código exacto que Lambda
fetcher = NewsFetcher()
result = fetcher.fetch_news('NVDA19')
print(result)  # Retroalimentación inmediata
EOF

Principio 4: Inspeccionar Datos Reales

No asumas la forma de los datos; verifica con ejemplos reales.

Errores Comunes:

  • Asumir que la API devuelve un dict (podría devolver una lista)
  • Asumir que el campo existe (podría ser nulo/estar ausente)
  • Asumir el tipo (podría ser string, no int)

Patrón:

# ❌ NO HAGAS: Asumir
# "La API devuelve una lista de tickers"

# ✅ HAZ: Verificar
curl -s https://api.example.com/tickers | jq . > sample_response.json
cat sample_response.json

# Inspeccionar estructura:
# - ¿Es una lista o un dict?
# - ¿Qué campos están presentes?
# - ¿Qué tipos tienen?
# - ¿Hay valores nulos?
# - ¿Hay estructuras anidadas?

Ejemplo: Investigación de Esquema de Aurora

# Conectarse a Aurora a través del túnel SSM
aws ssm start-session \
  --target i-1234567890abcdef0 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["aurora-endpoint"],"portNumber":["3306"],"localPortNumber":["3307"]}'

# Inspeccionar el esquema real (no asumir)
mysql -h 127.0.0.1 -P 3307 -u admin -p << 'SQL'
DESCRIBE precomputed_reports;

-- Verificar tipos de datos reales
SELECT
  symbol,
  report_json,
  typeof(report_json) as json_type
FROM precomputed_reports
LIMIT 1 \G

-- Verificar valores nulos
SELECT COUNT(*) as total,
       SUM(CASE WHEN report_json IS NULL THEN 1 ELSE 0 END) as null_count
FROM precomputed_reports;
SQL

Flujo de Trabajo de Investigación

Consulta WORKFLOW.md para un proceso de investigación detallado paso a paso.


Lista de Verificación de Investigación

Consulta INVESTIGATION-CHECKLIST.md para una lista de verificación sistemática de depuración.


Verificación de Límites

Cuándo: Al investigar sistemas distribuidos (Lambda, Aurora, S3, SQS, Step Functions)

Problema: El código parece correcto pero falla en producción debido a límites de ejecución no verificados

Preguntas críticas:

  • ¿DÓNDE se ejecuta este código? (¿Lambda, EC2, local?)
  • ¿QUÉ entorno requiere? (¿variables de entorno, red, permisos?)
  • ¿QUÉ sistemas externos llama? (¿esquema de Aurora, bucket de S3, formato de API?)
  • ¿CUÁLES son las propiedades de la entidad? (¿tiempo de espera/memoria de Lambda, límites de conexión de Aurora, uso previsto?)
  • ¿CÓMO verifico el contrato? (¿configuración de Terraform, SHOW COLUMNS, prueba de acceso?)

Cinco capas de corrección:

  1. Sintáctica: El código compila (sintaxis de Python válida)
  2. Semántica: El código hace lo que afirma (lógica correcta)
  3. Límite: El código puede alcanzar lo que necesita (red, permisos)
  4. Configuración: La configuración de la entidad coincide con los requisitos del código (tiempo de espera, memoria)
  5. Intencional: El uso coincide con el propósito diseñado (Lambda síncrona no para trabajo asíncrono)

Cuándo aplicar:

  • Errores de "el código parece correcto pero no funciona"
  • Flujos de trabajo de múltiples servicios (Lambda → Aurora → S3)
  • Después de 2 intentos de implementación fallidos (problemas de infraestructura)
  • Antes de concluir que "el código es correcto" (verificar el contexto de ejecución)

Flujo de trabajo de verificación:

1. Identificar límites de ejecución (código → tiempo de ejecución, código → base de datos, servicio → servicio)
2. Identificar entidades físicas (QUÉ Lambda, QUÉ Aurora, QUÉ bucket de S3)
3. Verificar que la configuración coincida con los requisitos (tiempo de espera, memoria, concurrencia)
4. Verificar que la intención coincida con el uso (Lambda asíncrona no para API síncrona)
5. Avanzar a través de las capas de evidencia (código → configuración → tiempo de ejecución → verdad fundamental)

Integración con el flujo de trabajo de investigación:

  • Fase 1 (Observar): Notar fallas relacionadas con límites (tiempo de espera, permiso denegado, discrepancia de esquema)
  • Fase 2 (Hipótesis): Identificar qué límite podría estar siendo violado
  • Fase 3 (Investigación): Aplicar la lista de verificación de verificación de límites sistemáticamente
  • Fase 4 (Validar): Verificar el contrato a través de la verdad fundamental (probar la ejecución real)

Ver: Lista de Verificación de Límites de Ejecución para un flujo de trabajo de verificación completo

Principios relacionados:

  • Principio #20 (Disciplina de Límites de Ejecución) - CLAUDE.md
  • Principio #2 (Fortalecimiento Progresivo de la Evidencia) - Verificar a través de todas las capas
  • Principio #15 (Contrato Infraestructura-Aplicación) - Sincronizar código e infraestructura

Investigaciones Arquitectónicas

Cuándo: Al elegir entre tecnologías, patrones o enfoques arquitectónicos

Problema: Las comparaciones "X vs Y" obtienen respuestas vagas de "depende" sin un análisis estructurado

Solución: Aplicar un marco de análisis de relaciones basado en OWL para una comparación sistemática

Pasos:

  1. Definir los conceptos a comparar

    • ¿Qué es X? (definición, ubicación, propósito, ejemplos)
    • ¿Qué es Y? (definición, ubicación, propósito, ejemplos)
  2. Aplicar los 4 tipos de relación:

    • Parte-Todo: ¿Es uno parte del otro, o son pares?
    • Complemento: ¿Manejan preocupaciones no superpuestas que funcionan juntas?
    • Sustitución: ¿Puede uno reemplazar al otro? ¿Bajo qué condiciones?
    • Composición: ¿Pueden ser estratificados/compuestos en un sistema de múltiples capas?
  3. Documentar con ejemplos concretos

    • Proporcionar escenarios reales, no teoría abstracta
    • Incluir análisis de compensaciones (qué se gana vs qué se pierde)
  4. Hacer recomendación basada en el análisis

    • Fundamentada en el análisis de relaciones, no en la intuición
    • Incluir antipatrones a evitar

Ver: Guía de Análisis de Relaciones para una metodología completa

Ejemplos de Casos de Uso:

  • "¿Debería usar Redis o DynamoDB para almacenamiento en caché?" → Aplicar análisis de sustitución y composición
  • "¿Cómo se relacionan la CDN y el almacenamiento en caché de la aplicación?" → Aplicar análisis de complemento y composición
  • "¿Microservicios vs Monolito?" → Aplicar análisis de parte-todo y compensaciones

Escenarios Comunes de Investigación

Escenario 1: Discrepancia del Sistema de Tipos

Síntoma: Mismo error después de 2 intentos, fallo silencioso

Pasos de Investigación:

  1. Leer la Documentación del Sistema Objetivo

    # Documentación de PyMySQL
    open https://pymysql.readthedocs.io/en/latest/modules/cursors.html
    
    # Buscar: ¿Qué tipos acepta execute()?
    
  2. Probar Ejemplo Mínimo

    import pymysql
    import json
    
    # Probar hipótesis: Dict vs cadena JSON
    data = {'key': 'value'}
    
    # Prueba 1: Dict
    try:
        cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    except TypeError as e:
        print(f"Dict falló: {e}")
    
    # Prueba 2: Cadena JSON
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("Cadena JSON exitosa")
    
  3. Aplicar Corrección con Confianza

    # Ahora SABEMOS que json.dumps() es necesario
    def store_report(symbol: str, report_json: dict):
        cursor.execute(
            "INSERT INTO reports (symbol, report_json) VALUES (%s, %s)",
            (symbol, json.dumps(report_json))  # Convertir a cadena
        )
    

Escenario 2: Incidente de Producción

Síntoma: Usuarios reportando errores, el panel muestra un pico

Pasos de Investigación:

  1. Triaje (< 5 minutos)

    # Verificar recuento de errores
    aws logs filter-log-events \
      --log-group-name /aws/lambda/worker \
      --start-time $(($(date +%s) - 600))000 \
      --filter-pattern "ERROR" \
      --query 'length(events)'
    
    # Verificar cuándo comenzó
    aws cloudwatch get-metric-statistics \
      --namespace AWS/Lambda \
      --metric-name Errors \
      --dimensions Name=FunctionName,Value=worker \
      --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%S) \
      --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \
      --period 60 \
      --statistics Sum
    
  2. Mitigación Inmediata (< 10 minutos)

    # Revertir a la versión anterior
    CURRENT=$(aws lambda get-alias --function-name worker --name live \
      --query 'FunctionVersion' --output text)
    
    PREVIOUS=$((CURRENT - 1))
    
    aws lambda update-alias \
      --function-name worker \
      --name live \
      --function-version $PREVIOUS
    
    echo "Reversión de v$CURRENT a v$PREVIOUS completada"
    
  3. Análisis Posterior al Incidente (30-60 minutos)

    # Recopilar evidencia
    mkdir incident-$(date +%Y%m%d-%H%M%S)
    cd incident-*
    
    # Exportar registros de errores
    aws logs filter-log-events \
      --log-group-name /aws/lambda/worker \
      --start-time $INCIDENT_START \
      --end-time $INCIDENT_END \
      --filter-pattern "ERROR" > errors.json
    
    # Exportar métricas
    aws cloudwatch get-metric-statistics ... > metrics.json
    
    # Obtener diff de implementación
    git diff v$PREVIOUS v$CURRENT > deployment.diff
    
    # Analizar (análisis de causa raíz)
    # - ¿Qué cambió?
    # - ¿Qué falló?
    # - ¿Por qué falló?
    # - ¿Cómo prevenir?
    

Escenario 3: Base de Código Desconocida

Tarea: Agregar funcionalidad a un módulo que nunca has visto

Pasos de Investigación:

  1. Encontrar el Punto de Entrada

    # Buscar función principal
    rg "def main"
    rg "if __name__ == '__main__'"
    
    # Seguir las importaciones para mapear dependencias
    rg "from src" --type py
    
  2. Leer el Código Fuente

    # Leer el archivo principal
    cat src/data/news_fetcher.py
    
    # Buscar tipos/clases clave
    rg "class Fetch" --type py
    
  3. Comprender las Pruebas

    # Buscar archivos de prueba para el módulo
    rg "news_fetcher" tests/ -l
    cat tests/test_news_fetcher.py | head -50
    
  4. Revisar el Historial de Git

    # Ver cambios recientes
    git log --oneline -10 src/data/news_fetcher.py
    
    # Ver cómo cambió con el tiempo
    git log -p --follow src/data/news_fetcher.py | head -100
    
  5. Ejecutar el Código con Depuración

    # Agregar declaraciones de impresión para rastrear el flujo
    python3 -c "
    from src.data.news_fetcher import NewsFetcher
    fetcher = NewsFetcher()
    import pdb; pdb.set_trace()  # Punto de interrupción
    result = fetcher.fetch_news('AAPL')
    print(result)
    "
    

Ejemplos de Llamadas a la API de Claude

{
  "name": "majiayu000/skill-registro-datos-claude",
  "description": "Investigación sistemática y análisis de causa raíz.",
  "aiSummary": "Habilidad para realizar investigaciones sistemáticas y análisis de causa raíz en sistemas complejos."
}

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

Skills relacionados