rainearcher/quiver

Perplexity Deep Research

Llama a la API de Perplexity Agent (POST /v1/agent) para realizar investigaciones multi-paso con citas. Antes de llamar a la API, este skill requiere un bucle estructurado de ingesta y aprobación del plan para que el agente utilice las fuentes correctas, tenga el contexto adecuado y devuelva un informe en un formato fácil de escanear.

Metodología

Este skill es una aplicación programática del playbook de investigación profunda de Growth Unhinged para GTM: https://www.growthunhinged.com/p/deep-research-for-gtm. Las cinco recomendaciones del artículo se corresponden 1:1 con los pasos a continuación:

Recomendación del artículo	Aplicada por
Proporcionar contexto completo (objetivo, GTM/producto, restricciones, fuentes preferidas)	Paso 1 — ingesta de cinco dimensiones
Solicitar un plan de investigación primero, aprobar antes de ejecutar	Paso 2 — puerta de aprobación del plan (sin gasto de API sin aprobación)
Apuntar a fuentes de alta calidad; preferir fuentes primarias sobre secundarias; citar todo	Bloque de formato — tabla de fuentes, prioridad de fuentes primarias, citas en línea requeridas
Especificar el formato del informe; resúmenes y tablas sobre prosa (Principio de la Pirámide)	Bloque de formato — TL;DR primero, tablas comparativas, conclusiones antes de antecedentes
Estructurar el prompt (<goal>, <context>, <sources>, <instructions>)	Diseño del bloque --instructions

La verificación del presupuesto de salida por llamada (Paso 2.5) y la secuenciación de múltiples llamadas (Paso 2.6) son adiciones al artículo, para prevenir el modo de fallo de truncación silenciosa que los planes grandes de GTM (bibliotecas de hooks, calendarios de 30 días, matrices de proveedores) suelen encontrar.

Requisitos previos

• PERPLEXITY_API_KEY disponible en el entorno (obtén una en https://www.perplexity.ai/account/api)
• curl y jq instalados

Ejecuta la verificación previa una vez en el primer uso para confirmar que todo está configurado:

bash ./scripts/check-setup.sh

Imprime ✓/✗ para cada requisito y una corrección para copiar y pegar si falta algo. Sale con 0 cuando está listo. Si alguna verificación falla, muestra la salida al usuario y detente — no intentes ejecutar el script de la API hasta que la verificación previa pase.

Cuándo Usar

• El usuario solicita explícitamente "investigación profunda", "investigación avanzada" o "investigación de Perplexity"
• El usuario necesita un resumen con fuentes (empresa, persona, evento, tecnología, regulación)
• Preguntas que requieren navegación multi-paso y síntesis de muchas fuentes
• Preguntas que requieren información muy reciente con citas en línea

NO usar para:

• Consultas fácticas simples ("cuál es el precio actual de X") — usa WebSearch / WebFetch (más barato, más rápido)
• Comparaciones binarias simples ("es la herramienta A o B mejor") — una sola ronda de WebSearch suele resolverlo
• Contenido autenticado o protegido por muros de pago (Perplexity no puede iniciar sesión)
• Ediciones rápidas de código o preguntas que se puedan responder desde el código base — en línea es más rápido
• Verificar un hecho específico del que ya tienes contexto — WebFetch es lo suficientemente preciso

Flujo de trabajo (OBLIGATORIO — no omitir pasos)

Las ejecuciones de investigación profunda cuestan dinero real y toman de 2 a 5 minutos. Una mala ejecución desperdicia ambos. Siempre sigue este bucle:

Paso 0 — Verificar configuración (solo la primera ejecución)

Si esta es la primera invocación en el proyecto, ejecuta bash ./scripts/check-setup.sh y solo continúa si sale con 0. Si informa una herramienta faltante o una clave no configurada, muestra la corrección y detente. Omite este paso en ejecuciones posteriores en la misma sesión.

Paso 1 — Auditar la consulta inicial, luego preguntar SOLO lo que falta

Primero, lee la consulta inicial del usuario y determina cuáles de las cinco dimensiones de contexto a continuación ya están respondidas, cuáles están parcialmente respondidas y cuáles faltan por completo. No vuelvas a preguntar cosas que el usuario ya te ha dicho.

Las cinco dimensiones:

1. Objetivo y motivación — qué está tratando de lograr, cómo se usará el resultado (decisión, documento, presentación, estrategia), trabajo previo ya realizado.
2. Contexto del producto / situación — la empresa/producto/rol, cómo opera, detalles de configuración relevantes (tamaño, etapa, GTM, audiencia).
3. Restricciones — presupuesto, plazos, número de personas, legal/cumplimiento, opciones descartadas, puntos no negociables.
4. Fuentes preferidas — expertos/creadores nombrados, tipos de publicaciones (académicas, datos primarios/gobierno, foros, analistas, presentaciones ante la SEC, GitHub, etc.), dominios permitidos vs. bloqueados, ventana de actualidad.
5. Límites del alcance — qué está explícitamente fuera del alcance, suposiciones que el agente NO debe hacer.

Decide si preguntar:

• Si las cinco dimensiones están suficientemente respondidas → omite la aclaración por completo y ve directamente al Paso 2 (redactar el plan). No hagas preguntas solo para confirmar lo que ya sabes.
• Si una o más dimensiones faltan o son ambiguas → usa AskUserQuestion para preguntar solo sobre las lagunas, en un solo bloque consolidado. Enumera explícitamente lo que ya entendiste (para que el usuario pueda corregirte) y lo que aún necesitas.
• Si el usuario dice "solo hazlo" / "usa tu criterio" → salta al Paso 2 y enumera tus suposiciones para cada dimensión faltante en el plan para que el usuario aún pueda corregirlas allí.

Tiende a hacer menos preguntas. Una consulta bien especificada de un párrafo a menudo no necesita aclaración — ve directamente al plan.

Paso 2 — Redactar un plan de investigación y obtener aprobación

Antes de llamar a la API, redacta un plan de investigación en tu respuesta y pídele al usuario que lo apruebe o lo edite. El plan debe incluir:

• Preguntas de investigación — las subpreguntas específicas que el agente responderá
• Metodología — cómo evaluará/comparará opciones, qué marco usará
• Estrategia de fuentes — qué tipos de fuentes priorizará, cuáles evitará, filtros de dominio o ventana de actualidad
• Estructura del informe — encabezados de sección que usará el informe final
• Entregables — además de prosa, ¿habrá tablas, matrices de comparación, plantillas, listas de verificación, fragmentos de código?
• Suposiciones abiertas — cualquier cosa que estés adivinando y que el usuario deba corregir

Espera la aprobación explícita ("se ve bien", "adelante", "ejecútalo", ediciones al plan, etc.) antes de proceder. Si el usuario edita el plan, vuelve a confirmar antes de ejecutar.

Paso 2.5 — Verificación del presupuesto de salida (OBLIGATORIO — evita la truncación)

El preset advanced-deep-research tiene un límite práctico de salida de alrededor de ~16k tokens / ~10k palabras por respuesta. Los planes que exceden esto se truncan silenciosamente — las secciones listadas en el índice simplemente no aparecerán, y los entregables grandes (bibliotecas de hooks, calendarios de N días, catálogos de antipatrones) se cortan a mitad de tabla. Debes presupuestar contra este límite ANTES de ejecutar.

Presupuesto de salida por llamada (límites estrictos):

Elemento	Máx. por llamada
Secciones principales (H2)	8
Tablas grandes (6+ filas, 4+ columnas)	4
Bibliotecas/catálogos detallados (hooks, plantillas, ejemplos, ideas)	10 elementos en total en todas las bibliotecas
Entregables de formato largo (calendarios de N días, guiones paso a paso, playbooks completos)	1
Prosa total (excluyendo tablas)	~4.000 palabras

Señales de alerta que indican que tu plan es demasiado grande para una llamada:

• El TDC tiene >8 secciones
• El plan promete "25+ hooks" / "calendario de 30 días" / "20 plantillas" junto con múltiples matrices
• El plan solicita múltiples entregables grandes en la misma llamada (ej. biblioteca de hooks Y calendario de contenido Y plantilla paso a paso Y catálogo de antipatrones)
• El plan cubre >1 segmento de audiencia distinto o >1 objetivo distinto en profundidad

Si el plan cabe en el presupuesto → procede al Paso 3.

Si el plan excede el presupuesto → divídelo en un plan de múltiples llamadas secuenciales (ver "Secuenciación de múltiples llamadas" a continuación) y preséntalo al usuario para su aprobación en su lugar.

Paso 2.6 — Secuenciación de múltiples llamadas (para alcances grandes O investigación dependiente)

Hay dos razones separadas para dividir en múltiples llamadas secuenciales, y ambas usan la misma mecánica:

(A) División por presupuesto — el plan excede el límite de salida por llamada del Paso 2.5. Divide en llamadas enfocadas, cada una con UN entregable principal.

(B) División por dependencia — el alcance de la llamada N depende de los hallazgos de la llamada N-1. Ejemplo: un estudio de paisaje de proveedores (llamada 1) informa qué 3 proveedores reciben análisis profundos (llamadas 2–4). Esto no se trata del tamaño — se trata de permitir que las llamadas posteriores reaccionen a lo que las llamadas anteriores descubren. No intentes planificar todo de antemano cuando realmente no sabes la respuesta hasta que hayas ejecutado la llamada 1.

Reglas para cualquier división de múltiples llamadas:

1. Ejecuta las llamadas secuencialmente, no en paralelo — cada llamada debe poder citar o basarse en los resultados anteriores.
2. Cada llamada debe tener UN enfoque de entregable principal.
3. Cada llamada debe mantenerse dentro del presupuesto por llamada del Paso 2.5.
4. Cada llamada debe ser valiosa individualmente — no crees llamadas que solo tengan sentido en combinación.
5. En las --instructions de cada llamada posterior, pega los hallazgos clave de las llamadas anteriores (no el informe completo, solo las conclusiones importantes, ~200–400 palabras) bajo un encabezado PRIOR FINDINGS (do not re-research) para que el agente no pierda pasos volviendo a cubrir terreno.
6. Después de que cada llamada se complete, Read la salida, verifica que nada se haya truncado (comprueba que cada sección en el TDC de la llamada esté presente y que ninguna tabla termine a mitad de fila), y resúmela brevemente al usuario antes de iniciar la siguiente llamada.

Presenta la división así:

Este plan necesita N llamadas secuenciales porque <razón de presupuesto / dependencia>:
  Llamada 1 — <enfoque>  (~$X, ~3 min)
  Llamada 2 — <enfoque>  (~$X, ~3 min)
  ...
Costo total estimado: $X. Aprueba la división, o dime qué recortar.

Espera la aprobación explícita de la división antes de ejecutar cualquier llamada. Si el usuario edita la división, vuelve a confirmar.

Paso 3 — Ejecutar la investigación

Una vez aprobado, invoca el script. Pasa el plan + contexto + requisitos de formato aprobados a través de --instructions. Usa las banderas --domains y --recency cuando el usuario las haya especificado.

Siempre pasa --topic <slug> para que la salida aterrice en un subdirectorio de tema bajo ./docs/research/. Antes de invocar, inspecciona los subdirectorios existentes (ls docs/research/) y reutiliza un slug existente que coincida con el área de investigación o crea un nuevo slug corto en kebab-case. Si estás creando un nuevo tema, elige algo duradero — un slug que seguirías usando para los próximos 3–5 informes en la misma área, no una frase única de la pregunta actual. Buenos formatos de slug: vendor-comparison, competitor-analysis, regulation-update, <product-area>. Malos formatos de slug: doppler-vs-vault-2026 (demasiado específico y ligado a una fecha).

El script se encuentra en ./scripts/research.sh (relativo a este SKILL.md). Cuando es invocado por un agente, usa esa ruta relativa al skill — se resuelve correctamente tanto en instalaciones de npx skills como en instalaciones de Claude Code /plugin.

bash ./scripts/research.sh \
  --preset advanced-deep-research \
  --output ./docs/research \
  --topic <topic-slug> \
  --instructions "$(cat <<'EOF'
<paste the approved plan + context + format requirements here>
EOF
)" \
  "<the research question, refined from the approved plan>"

Paso 4 — Leer el informe y resumir

El script imprime la ruta del markdown. Siempre Read ese archivo antes de informar.

Verificación de truncación (obligatoria):

1. Confirma que cada sección listada en el TDC del informe esté realmente presente en el cuerpo.
2. Confirma que ninguna tabla termine a mitad de fila y que ninguna lista detallada termine a mitad de elemento.
3. Confirma que las secciones "Fuentes", "Dónde las fuentes discrepan" y "Confianza y lagunas" al final estén presentes.

Flujo de trabajo de recuperación de truncación. Si falta alguno de estos → la salida fue truncada. Haz lo siguiente:

1. Identifica exactamente qué falta. Compara el TDC del informe con su cuerpo. Enumera las secciones faltantes, las tablas incompletas (nota la última fila completa) y los elementos de lista cortados (nota el último elemento completo).
2. Cuantifica el trabajo restante. "X secciones, Y elementos, Z filas aún necesarias."
3. Propón una llamada de seguimiento enfocada con un alcance que quepa en el presupuesto por llamada. NO intentes el mismo alcance de nuevo — se truncará otra vez.
4. Incluye PRIOR FINDINGS en las --instructions de la llamada de seguimiento — pega un resumen de ~200–400 palabras de las secciones completadas para que el agente no las investigue de nuevo. Di explícitamente "no volver a cubrir X, Y, Z; enfócate solo en A, B, C."
5. Informa al usuario qué se truncó y muestra el plan de seguimiento antes de ejecutar.

Superficie: ideas clave, el costo en USD del informe, cualquier discrepancia notable entre fuentes y una bandera de truncación si corresponde.

Patrones avanzados

Estos patrones mejoran de manera confiable la calidad de la salida. Úsalos en el Paso 2 al redactar el plan.

Citar expertos o marcos específicos en tu consulta

Nombrar de 3 a 6 expertos, autores, creadores o marcos nombrados relevantes en la consulta le da al agente fuentes concretas para buscar y comparar. El informe se convierte en una comparación de puntos de vista conocidos en lugar de una síntesis anónima.

Fragmentos de consulta de ejemplo:

• "Compara los marcos utilizados por , y para..."
• "Según la metodología , evalúa..."
• "Concilia los enfoques recomendados por (en <libro/blog>) vs ..."

Funciona mejor cuando los expertos publican regularmente (artículos, videos, publicaciones, charlas) — el agente puede obtener su material principal.

Especificar entregables cuantificados

En lugar de pedir "un buen número de ejemplos", indica el conteo exacto y la forma. Esto fija el alcance, evita la desviación y muestra cuándo estás por encima del presupuesto (cruza referencia con el Paso 2.5).

Buenas especificaciones de entregables:

• "Una matriz de comparación: 8 filas (una por proveedor), 5 columnas (precio, latencia, autenticación, SDKs, cumplimiento)"
• "Una biblioteca de exactamente 10 plantillas, agrupadas en 3 categorías"
• "Una secuencia de 14 días con un elemento por día"

Evita: "una biblioteca completa", "varios ejemplos", "muchas opciones" — estos son invitaciones a truncar o dudar.

Precargar contexto en --instructions, no en la consulta

La consulta debe mantenerse como una o dos oraciones concisas. Cualquier cosa sobre la situación del usuario, restricciones, decisiones previas o preferencias de fuentes va en --instructions. Esto mantiene las consultas de búsqueda del agente enfocadas mientras la síntesis se mantiene basada en tu contexto.

Instrucciones de formato requeridas (siempre incluir en --instructions)

Cada ejecución debe incrustar estos requisitos de formato en la cadena --instructions para que el informe sea fácil de escanear y confiable:

SCOPE & SIZE CONSTRAINT (read first — this entire report must stay within the per-call budget from the skill methodology).

FORMAT REQUIREMENTS:
1. Output in Spanish (target locale).
2. Start with a TL;DR header and 2-3 sentence executive summary.
3. Use comparison tables where multiple options exist (limit to 4 large tables max).
4. Present conclusions first, then supporting evidence (Pyramid Principle).
5. Prioritize primary sources over secondary. List all sources in a table at the end.
6. Include a "Where sources disagree" section if applicable.
7. Include a "Confidence & gaps" section noting assumptions and uncertainty.
8. Inline citations required for every factual claim and data point.
9. Keep prose concise — target under 4,000 words total for prose (excluding tables).

OUTPUT STRUCTURE:
- # Title (kebab-case topic slug)
- ## TL;DR
- ## Key Findings
- ## <Major Section 1>
- ## <Major Section 2>
- ... (max 8 H2 sections)
- ## Where sources disagree
- ## Confidence & gaps
- ## Sources

Notas finales

• Siempre verifica el costo en USD en la salida del script e infórmalo al usuario.
• Si el informe se trunca (secciones faltantes, tablas cortadas), sigue el flujo de recuperación en el Paso 4.
• Para investigaciones grandes, usa la secuenciación de múltiples llamadas del Paso 2.6.
• Mantén la consulta de búsqueda enfocada (1–2 oraciones) y todo el contexto en --instructions.