1. Error en runtime
2. Copy stack trace
3. Paste en Google (o stackoverflow)
4. Abrir 10+ tabs de SO
5. Leer respuestas (muchas obsoletas)
6. Encontrar una prometedora
7. Abrir archivo en VS Code
8. Buscar función/variable
9. Analizar contexto
10. Proponer fix
11. Probar fix
12. Volver a 1 si falló

Tú: [Pegas stack trace]

Pi: [Lee el stack trace]
    [Encuentra el archivo en tu repo]
    [Lee la función que causó el error]
    [Analiza el contexto]
    → "El error está en src/auth/service.ts:45"

Tú: "¿Por qué falla esto?"

Pi: [Analiza todo el call stack]
    [Ve dependencias entre funciones]
    [Identifica el patrón de error]
    → "La función validate() retorna undefined cuando el input está vacío,
       pero la función login() asume que siempre retorna un string.
       Esto causa el TypeError en el siguiente paso."

Tú: "Propón un fix"

Pi: [Genera patch]
    [Añade tests que cubren el bug]
    [Explica por qué funciona]

Patch:
    + const result = validate(input);
    + if (!result) return null; // Handle empty input

# Correr el comando que falla
npm test

# Output:
TypeError: Cannot read properties of undefined (reading 'token')
    at AuthService.login (src/auth/service.ts:45)
    at UserController.postLogin (src/controllers/user.ts:12)
    at Router.handle (src/router/index.ts:89)

pi

# Tú: [Pegas el stack trace completo]

# Pi genera el patch
# Tú revisas:
- ¿Es correcto?
- ¿Afecta otras partes del código?
- ¿Los tests cubren el caso?

# Si estás de acuerdo:
pi
# Tú: "Aplica el fix"

# [Pi aplica el patch]
# [Pi corre tests]
# [Pi verifica que pasan]

# Pi usa esto internamente cuando ve un stack trace
get_symbol_at_path(
    file_path="src/auth/service.ts",
    line=45,
    column=0
)

# → Ve: async function login(credentials: LoginDTO): Promise<AuthResponse>

get_references(
    symbol_name="login",
    file_path="src/auth/service.ts"
)

# → Lista todos los lugares donde se llama a login()

search_code(
    pattern="Cannot read properties of undefined",
    case_sensitive=False
)

# → Encuentra todos los lugares donde este error podría ocurrir

/skill:debugger src/auth/service.ts:45
# → Analiza línea 45, propone debugging steps

Error: jwt.verify is not a function
    at AuthService.verifyToken (src/auth/service.ts:67)
    at Middleware.authenticate (src/middleware/auth.ts:23)

1. Abrir src/auth/service.ts:67
2. Buscar jwt.verify
3. Ver que jwt viene de 'jsonwebtoken'
4. Abrir package.json
5. Ver versión: "jsonwebtoken": "^8.5.0"
6. Googlear "jwt.verify is not a function jsonwebtoken 8.5.0"
7. Leer que la API cambió en v9
8. Cambiar import
9. Probar
10. Otro error en otro archivo
11. Repetir en 5+ archivos

pi

# Tú: [Pegas el error]

Pi: Analizando...
    → Root cause: el objeto `jwt` llegó con un import incorrecto y no exponía `verify` como se esperaba
    → Afectados: 12 archivos
    → Patch: Actualizar imports en todos los archivos afectados

# Tú: "Aplica el fix y añade tests"

Pi: [Aplica patch en 12 archivos]
    [Añade test para verifyToken()]
    [Corre tests]
    → 24/24 tests pasan ✓

# Pi busca dónde se define la función
get_definition(
    name_path="AuthService.verifyToken",
    file_path="src/auth/service.ts"
)

# → Si no existe: "verifyToken no está definido en AuthService"
# → Si existe pero tiene otro nombre: "¿Quisiste decir verifyTokenAsync?"

# Pi rastrea el valor hacia atrás
get_call_hierarchy(
    name_path="AuthService.login",
    direction="incoming"
)

# → Ve quién llama a login()
# → Ve qué parámetros pasa
# → Identifica dónde se rompe la cadena

# Pi verifica:
search_code(
    pattern="from '@company/package-name'",
    glob="**/*.ts"
)

# → Si existe en otro archivo: "El path es '@company/package-name/index'"
# → Si no existe: "Instala el paquete: npm install @company/package-name"

# Pi usa type hierarchy
get_type_hierarchy(
    name_path="UserDTO",
    file_path="src/types/users.ts"
)

# → Ve qué interfaces implementa UserDTO
# → Ve qué espera la función
# → Propone el tipo correcto o un type assertion seguro

# Pi rastrea el bug a través del call stack completo

# 1. Punto de entrada (error)
src/controllers/user.ts:12
    ↓ llama a
# 2. Servicio
src/auth/service.ts:45
    ↓ llama a
# 3. Validador
src/utils/validator.ts:89
    ↓ llama a
# 4. Schema
src/schemas/auth.ts:23
    ↓ BUG AQUÍ
# 5. Schema tiene propiedad opcional que debería ser requerida

[2026-04-04 10:23:45] ERROR: Payment failed for user 12345
[2026-04-04 10:23:46] ERROR: Transaction rollback
[2026-04-04 10:23:47] ERROR: User notified

pi

# Tú: [Pegas los logs]

Pi: Analizando logs de producción...
    → El error está en el flujo de pagos
    → Buscando código relacionado con "Payment failed"...

# [Pi busca en el código]
search_code(
    pattern="Payment failed",
    context_lines=5
)

# [Encuentra el lugar]
# → src/payments/service.ts:156

Pi: Viendo el código del error...
    → El error ocurre cuando payment_gateway retorna null
    → Pero el código asume que siempre retorna un objeto

# Tú: "Propón fix"

Pi: [Genera patch con null check]
    [Añade logs para debugging futuro]

# 1. Tener el error completo (stack trace, logs, screenshots)
# 2. Tener el estado del repo (git branch, último commit)
# 3. Tener contexto (qué estabas haciendo cuando falló)

# 4. Pi: Analizar error
# 5. Pi: Entender root cause
# 6. Revisar el fix propuesto
# 7. Aplicar solo si estás de acuerdo
# 8. Correr tests
# 9. Verificar que el bug se fue

# 10. Añadir test que cubre el bug (prevenir regresión)
# 11. Verificar que no rompió nada más
# 12. Commit con mensaje claro
# 13. Documentar si es un patrón recurrente