Communitygithub.com

majiayu000/claude-skill-registry

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

¿Qué es claude-skill-registry?

Esta habilidad, extraída de los principios de investigación y patrones de depuración de CLAUDE.md, está diseñada para ingenieros que trabajan con la AWS CLI, Git, ripgrep, jq, curl y las DevTools del navegador. Su propósito es guiar a desarrolladores y agentes de IA en la realización de investigaciones profundas cuando las soluciones intuitivas fallan, ayudando a evitar ciclos de iteración sin sentido. La habilidad se activa principalmente cuando un mismo error persiste tras dos intentos de corrección, o cuando se necesita entender un código base desconocido, investigar incidentes de producción, tomar decisiones arquitectónicas o aprender nuevas tecnologías. El flujo de trabajo se estructura en torno a un patrón de bucle Meta-Loop → Initial-Sensitive, donde se fomenta la reflexión y la generación de hipótesis antes de continuar iterando. Los principios fundamentales incluyen investigar antes de iterar, leer fuentes primarias (documentación oficial y código fuente) en lugar de depender de respuestas generadas por IA, reproducir problemas localmente para acelerar la depuración, e inspeccionar datos reales para verificar suposiciones. También aborda la verificación de fronteras en sistemas distribuidos y proporciona un marco para investigaciones arquitectónicas basadas en el análisis de relaciones OWL.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/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 o más intentos de corrección
  • ✓ Necesitas entender un código base desconocido
  • ✓ Investigas incidentes de producción
  • ✓ Tomas decisiones arquitectónicas
  • ✓ Depuras interacciones complejas del sistema
  • ✓ Aprendes una nueva tecnología o 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 (primero corrige, luego investiga)

Árbol de Decisión Rápido de Investigación

¿Cuál es el problema?
├─ ¿Es la primera vez que ves este problema?
│  ├─ SÍ → Prueba la solución obvia (iteración)
│  └─ NO → ¿Mismo error después de 2 intentos? → INVESTIGAR
│
├─ ¿Incidente de producción?
│  ├─ ¿Afecta a usuarios AHORA? → Reversión/corrección urgente primero, investiga después
│  └─ ¿Análisis post-incidente? → Investigación profunda
│
├─ ¿Necesitas entender el código base?
│  ├─ ¿Función/módulo específico? → Lee código + pruebas
│  ├─ ¿Arquitectura del sistema? → Traza el flujo de solicitudes
│  └─ ¿Contexto histórico? → Git blame + historial de commits
│
├─ ¿Decisión tecnológica?
│  ├─ Lee la documentación oficial (no publicaciones de blog)
│  ├─ Compara alternativas (compensaciones)
│  ├─ Crea un prototipo con un caso de uso real
│  └─ Documenta la decisión (ADR)
│
└─ ¿Integración de API/biblioteca?
   ├─ Lee los requisitos de tipo (no supongas)
   ├─ Verifica la compatibilidad de versiones
   ├─ Prueba un ejemplo mínimo
   └─ Verifica con datos reales

Patrón de Bucle: Meta-Loop → Initial-Sensitive

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 reintentos (la ejecución cambia, el resultado no)
  • Acción: Usa /hypothesis para cuestionar suposiciones (cambia a initial-sensitive)

Herramientas Utilizadas:

  • /observe - Observa el comportamiento del sistema (qué está fallando)
  • /hypothesis - Genera explicaciones alternativas (¿por qué podría fallar de manera diferente a lo que creo?)
  • /research - Prueba hipótesis sistemáticamente
  • /validate - Verifica si el nuevo entendimiento es correcto
  • /reflect - Sintetiza lo aprendido después de la investigación

Por Qué Funciona: La habilidad de investigación encaja naturalmente con el bucle initial-sensitive—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 Fundamentales de Investigación

Principio 1: Investiga 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 entender 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 + Implementar (8 minutos)
  ↓ Falló
Intento 2: Hipótesis diferente + Implementar (8 minutos)
  ↓ Falló
Intento 3: ❌ DETENTE - No implementes otra suposición

CAMBIA A MODO DE INVESTIGACIÓN:
  - Lee especificaciones/documentación (15 minutos)
  - Inspecciona datos reales (10 minutos)
  - Reproduce localmente (20 minutos)
  - Identifica la causa raíz (15 minutos)
  ↓ Total: 60 minutos de investigación

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

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

Principio 2: Lee Fuentes Primarias

Jerarquía de Calidad de la Información:

Tipo de FuenteFiabilidadCuándo Usar
Documentación OficialMás AltaPrimera parada 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 como punto de partida, siempre verifica

Ejemplo: Integración de Sistema de Tipos

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

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

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

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

try:
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    print("✅ Diccionario aceptado")
except TypeError as e:
    print(f"❌ Diccionario rechazado: {e}")
    # Prueba 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: Reproduce 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 de nube
  • ✅ Se pueden probar casos límite fácilmente

Patrón:

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

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

# ✅ BIEN: Reproduce 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: Inspecciona Datos Reales

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

Errores Comunes:

  • Suponer que la API devuelve un diccionario (podría devolver una lista)
  • Suponer que un campo existe (podría ser nulo/estar ausente)
  • Suponer el tipo (podría ser cadena, no entero)

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

# Inspecciona la estructura:
# - ¿Es una lista o un diccionario?
# - ¿Qué campos están presentes?
# - ¿Qué tipos son?
# - ¿Hay valores nulos?
# - ¿Hay estructuras anidadas?

Ejemplo: Investigación de Esquema de Aurora

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

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

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

-- Verifica si hay 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 detallado paso a paso de investigación.


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 las entidades? (¿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, acceso de prueba?)

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 con 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 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 fallos relacionados con límites (tiempo de espera, permiso denegado, discrepancia de esquema)
  • Fase 2 (Hipótesis): Identificar qué límite podría estar violado
  • Fase 3 (Investigación): Aplicar la lista 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 completo de verificación

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: ¿Uno es 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: ¿Se pueden combinar/componer 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 una recomendación basada en el análisis

    • Basada 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 el almacenamiento en caché?" → Aplicar análisis de sustitución y composición
  • "¿Cómo se relacionan la CDN y el almacenamiento en caché de aplicaciones?" → Aplicar análisis de complemento y composición
  • "¿Microservicios vs Monolito?" → Aplicar análisis parte-todo y de compensaciones

Escenarios Comunes de Investigación

Escenario 1: Discrepancia en el 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 un Ejemplo Mínimo

    import pymysql
    import json
    
    # Probar hipótesis: Diccionario vs cadena JSON
    data = {'key': 'value'}
    
    # Prueba 1: Diccionario
    try:
        cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (data,))
    except TypeError as e:
        print(f"Diccionario falló: {e}")
    
    # Prueba 2: Cadena JSON
    cursor.execute("INSERT INTO test (json_col) VALUES (%s)", (json.dumps(data),))
    print("Cadena JSON tuvo éxito")
    
  3. Aplicar la 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 empezó
    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
    ACTUAL=$(aws lambda get-alias --function-name worker --name live \
      --query 'FunctionVersion' --output text)
    
    ANTERIOR=$((ACTUAL - 1))
    
    aws lambda update-alias \
      --function-name worker \
      --name live \
      --function-version $ANTERIOR
    
    echo "Reversión de v$ACTUAL a v$ANTERIOR completada"
    
  3. Análisis Post-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 $INICIO_INCIDENTE \
      --end-time $FIN_INCIDENTE \
      --filter-pattern "ERROR" > errors.json
    
    # Exportar métricas
    aws cloudwatch get-metric-statistics ... > metrics.json
    
    # Obtener diff de implementación
    git diff v$ANTERIOR v$ACTUAL > deployment.diff
    
    # Analizar (análisis de causa raíz)
    # - ¿Qué cambió?
    # - ¿Qué falló?
    # - ¿Por qué falló?
    # - ¿Cómo prevenirlo?
    

Escenario 3: Código Base Desconocido

Tarea: Agregar una función a un módulo que nunca has visto

Pasos de Investigación:

  1. Encontrar el Punto de Entrada
    # Buscar la función main
    rg "def main"
    

[truncado para traducción]

---

## Aprendizajes Clave

1. **Investiga antes de iterar**: Después de 2 intentos fallidos, cambia al modo de investigación.
2. **Lee fuentes primarias**: Confía en la documentación oficial y el código fuente sobre la información generada por IA.
3. **Reproduce localmente**: Evita implementar en la nube hasta que entiendas el problema.
4. **Inspecciona datos reales**: No asumas la forma de los datos—verifica con ejemplos reales.
5. **Verifica los límites**: En sistemas distribuidos, los errores a menudo provienen de límites de ejecución no verificados, no de la lógica del código.
6. **Usa un análisis estructurado**: Para decisiones arquitectónicas, aplica marcos de análisis de relaciones en lugar de argumentos intuitivos.

Individual skills in this repo

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

majiayu000/claude-skill-registry

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".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

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

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

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

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

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

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

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

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

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

majiayu000/claude-skill-registry

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

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

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

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

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

Skills relacionados