rainearcher/quiver

Perplexity Deep Research

Appelez l'API Perplexity Agent (POST /v1/agent) pour effectuer des recherches approfondies en plusieurs étapes avec citations. Avant d'appeler l'API, cette compétence nécessite une boucle structurée de collecte d'informations et d'approbation du plan, afin que l'agent utilise les bonnes sources, dispose du contexte approprié et renvoie un rapport dans un format facile à parcourir.

Méthodologie

Cette compétence est une mise en œuvre programmatique du playbook de recherche approfondie pour le GTM de Growth Unhinged : https://www.growthunhinged.com/p/deep-research-for-gtm. Les cinq recommandations de l'article correspondent directement aux étapes ci-dessous :

Recommandation de l'article	Mise en œuvre par
Fournir un contexte complet (objectif, GTM/produit, contraintes, sources préférées)	Étape 1 — collecte sur cinq dimensions
Demander d'abord un plan de recherche, approuver avant d'exécuter	Étape 2 — validation du plan (pas de dépense API sans approbation)
Pointer vers des sources de haute qualité ; préférer les sources primaires aux secondaires ; citer tout	Bloc de format — tableau des sources, priorité aux sources primaires, citations en ligne obligatoires
Spécifier le format du rapport ; résumés et tableaux plutôt que prose (principe de la pyramide)	Bloc de format — TL;DR en premier, tableaux comparatifs, conclusions avant le contexte
Structurer la requête (<goal>, <context>, <sources>, <instructions>)	Disposition du bloc --instructions

La vérification du budget de sortie par appel (Étape 2.5) et le séquencement multi-appels (Étape 2.6) sont des ajouts à l'article, pour éviter le mode de défaillance par troncature silencieuse que les grands plans GTM (bibliothèques de hooks, calendriers de 30 jours, matrices de fournisseurs) rencontrent régulièrement.

Prérequis

• PERPLEXITY_API_KEY disponible dans l'environnement (obtenez-en une sur https://www.perplexity.ai/account/api)
• curl et jq installés

Exécutez la vérification préalable une fois lors de la première utilisation pour confirmer que tout est en place :

bash ./scripts/check-setup.sh

Cela affiche ✓/✗ pour chaque exigence et une correction copier-coller pour tout ce qui manque. Se termine par 0 lorsque tout est prêt. Si une vérification échoue, affichez la sortie à l'utilisateur et arrêtez-vous — n'essayez pas d'exécuter le script API tant que la vérification préalable n'est pas réussie.

Quand utiliser

• L'utilisateur demande explicitement une « recherche approfondie », « recherche avancée » ou « recherche Perplexity »
• L'utilisateur a besoin d'un briefing sourcé (entreprise, personne, événement, technologie, réglementation)
• Questions nécessitant une navigation en plusieurs étapes et une synthèse de nombreuses sources
• Questions nécessitant des informations très récentes avec citations en ligne

Ne PAS utiliser pour :

• Recherches factuelles simples (« quel est le prix actuel de X ») — utilisez WebSearch / WebFetch à la place (moins cher, plus rapide)
• Comparaisons binaires simples (« l'outil A ou B est-il meilleur ») — un seul tour de WebSearch suffit généralement
• Contenu authentifié ou payant (Perplexity ne peut pas se connecter)
• Modifications de code rapides ou questions pouvant être résolues à partir de la base de code — en ligne est plus rapide
• Vérifier un fait spécifique dont vous avez déjà le contexte — WebFetch est assez précis

Workflow (OBLIGATOIRE — ne sautez pas les étapes)

Les recherches approfondies coûtent de l'argent réel et prennent 2 à 5 minutes. Une mauvaise exécution gaspille les deux. Suivez toujours cette boucle :

Étape 0 — Vérifier la configuration (première exécution uniquement)

S'il s'agit de la première invocation dans le projet, exécutez bash ./scripts/check-setup.sh et ne continuez que s'il se termine par 0. S'il signale un outil manquant ou une clé non définie, affichez la correction et arrêtez-vous. Ignorez cette étape lors des exécutions suivantes dans la même session.

Étape 1 — Auditer la requête initiale, puis ne demander QUE ce qui manque

Tout d'abord, lisez la requête initiale de l'utilisateur et déterminez lesquelles des cinq dimensions de contexte ci-dessous sont déjà répondues, partiellement répondues ou totalement absentes. Ne posez pas de questions sur des éléments que l'utilisateur vous a déjà fournis.

Les cinq dimensions :

1. Objectif et motivation — ce qu'il essaie d'atteindre, comment la sortie sera utilisée (décision, document, argumentaire, stratégie), travail préalable déjà effectué.
2. Contexte du produit / de la situation — l'entreprise/produit/rôle, comment il fonctionne, détails pertinents (taille, stade, GTM, audience).
3. Contraintes — budget, délais, effectifs, aspects juridiques/conformité, options exclues, éléments non négociables.
4. Sources préférées — experts/créateurs nommés, types de publications (académiques, données primaires/gouvernementales, forums, analystes, dépôts SEC, GitHub, etc.), domaines autorisés vs. bloqués, fenêtre de récence.
5. Limites du périmètre — ce qui est explicitement hors du champ, hypothèses que l'agent ne doit PAS faire.

Décidez de poser des questions :

• Si les cinq dimensions sont suffisamment répondues → sautez la clarification et passez directement à l'Étape 2 (rédiger le plan). Ne posez pas de questions juste pour confirmer ce que vous savez déjà.
• Si une ou plusieurs dimensions sont manquantes ou ambiguës → utilisez AskUserQuestion pour ne demander que les lacunes, dans un bloc consolidé unique. Listez explicitement ce que vous avez déjà compris (afin que l'utilisateur puisse vous corriger) et ce dont vous avez encore besoin.
• Si l'utilisateur dit « vas-y » / « utilise ton jugement » → passez à l'Étape 2 et listez vos hypothèses pour chaque dimension manquante dans le plan afin que l'utilisateur puisse toujours les corriger à ce stade.

Tendez à poser moins de questions. Une requête bien spécifiée d'un paragraphe n'a souvent besoin d'aucune clarification — allez directement au plan.

Étape 2 — Rédiger un plan de recherche et obtenir l'approbation

Avant d'appeler l'API, rédigez un plan de recherche dans votre réponse et demandez à l'utilisateur de l'approuver ou de le modifier. Le plan doit inclure :

• Questions de recherche — les sous-questions spécifiques auxquelles l'agent répondra
• Méthodologie — comment il évaluera/comparez les options, quel cadre il utilisera
• Stratégie de sources — quels types de sources il priorisera, lesquels il évitera, tout filtre de domaine ou fenêtre de récence
• Structure du rapport — titres des sections que le rapport final utilisera
• Livrables — au-delà de la prose, y aura-t-il des tableaux, matrices de comparaison, modèles, listes de contrôle, extraits de code ?
• Hypothèses ouvertes — tout ce que vous supposez et que l'utilisateur devrait corriger

Attendez l'approbation explicite (« ça a l'air bien », « vas-y », « exécute », des modifications au plan, etc.) avant de continuer. Si l'utilisateur modifie le plan, reconfirmez avant d'exécuter.

Étape 2.5 — Vérification du budget de sortie (OBLIGATOIRE — évite la troncature)

Le préréglage advanced-deep-research a un plafond de sortie pratique d'environ ~16k tokens / ~10k mots par réponse. Les plans qui dépassent cette limite sont tronqués silencieusement — les sections listées dans la table des matières n'apparaissent tout simplement pas, et les livrables volumineux (bibliothèques de hooks, calendriers N jours, catalogues d'anti-patrons) sont coupés au milieu d'un tableau. Vous devez budgétiser par rapport à ce plafond AVANT d'exécuter.

Budget de sortie par appel (limites strictes) :

Élément	Max par appel
Sections principales (H2)	8
Grands tableaux (6+ lignes, 4+ colonnes)	4
Bibliothèques/catalogues détaillés (hooks, modèles, exemples, idées)	10 éléments au total pour toutes les bibliothèques
Livrables longs (calendriers N jours, scripts plan par plan, playbooks complets)	1
Prose totale (hors tableaux)	~4 000 mots

Drapeaux rouges indiquant que votre plan est trop volumineux pour un seul appel :

• La TdC a >8 sections
• Le plan promet « 25+ hooks » / « calendrier de 30 jours » / « 20 modèles » ainsi que plusieurs matrices
• Le plan demande plusieurs livrables volumineux dans le même appel (par ex. bibliothèque de hooks ET calendrier de contenu ET modèle plan par plan ET catalogue d'anti-patrons)
• Le plan couvre >1 segment d'audience distinct ou >1 objectif distinct en profondeur

Si le plan respecte le budget → passez à l'Étape 3.

Si le plan dépasse le budget → divisez-le en un plan multi-appels séquentiel (voir « Séquençage multi-appels » ci-dessous) et présentez-le à l'utilisateur pour approbation à la place.

Étape 2.6 — Séquençage multi-appels (pour les grands périmètres OU les recherches dépendantes)

Il y a deux raisons distinctes de diviser en plusieurs appels séquentiels, et les deux utilisent les mêmes mécanismes :

(A) Division basée sur le budget — le plan dépasse le plafond de sortie par appel de l'Étape 2.5. Divisez en appels ciblés, chacun avec UN livrable principal.

(B) Division basée sur la dépendance — le périmètre de l'appel N dépend des résultats de l'appel N-1. Exemple : une étude de paysage des fournisseurs (appel 1) informe quels 3 fournisseurs bénéficient d'analyses approfondies (appels 2–4). Il ne s'agit pas de taille — il s'agit de permettre aux appels ultérieurs de réagir à ce que les appels antérieurs ont révélé. N'essayez pas de tout préplanifier à l'avance lorsque vous ne connaissez pas vraiment la réponse tant que vous n'avez pas exécuté l'appel 1.

Règles pour toute division multi-appels :

1. Exécutez les appels séquentiellement, pas en parallèle — chaque appel doit pouvoir citer ou s'appuyer sur les sorties précédentes.
2. Chaque appel doit avoir UN seul livrable principal comme objectif.
3. Chaque appel doit rester dans le budget par appel de l'Étape 2.5.
4. Chaque appel doit avoir une valeur individuelle — ne créez pas d'appels qui n'ont de sens qu'en combinaison.
5. Dans les --instructions de chaque appel suivant, collez les résultats clés des appels précédents (pas le rapport complet — seulement les conclusions importantes, ~200–400 mots) sous un en-tête PRIOR FINDINGS (do not re-research) afin que l'agent ne gaspille pas d'étapes à refaire le terrain.
6. Après chaque appel, Read la sortie, vérifiez que rien n'a été tronqué (vérifiez que chaque section de la TdC de l'appel est présente et qu'aucun tableau ne se termine au milieu d'une ligne), et résumez-la brièvement à l'utilisateur avant de lancer l'appel suivant.

Présentez la division comme suit :

Ce plan nécessite N appels séquentiels car <raison budget / dépendance> :
  Appel 1 — <objectif>  (~$X, ~3 min)
  Appel 2 — <objectif>  (~$X, ~3 min)
  ...
Coût total estimé : $X. Approuvez la division, ou dites-moi quoi couper.

Attendez l'approbation explicite de la division avant d'exécuter un appel. Si l'utilisateur modifie la division, reconfirmez.

Étape 3 — Exécuter la recherche

Une fois approuvé, appelez le script. Passez le plan + contexte + exigences de format approuvés via --instructions. Utilisez les indicateurs --domains et --recency lorsque l'utilisateur les a spécifiés.

Passez toujours --topic <slug> afin que la sortie atterrisse dans un sous-répertoire de rubrique sous ./docs/research/. Avant d'invoquer, inspectez les sous-répertoires existants (ls docs/research/) et soit réutilisez un slug existant correspondant au domaine de recherche, soit créez un nouveau slug court en kebab-case. Si vous créez une nouvelle rubrique, choisissez quelque chose de durable — un slug que vous utiliseriez encore pour les 3 à 5 prochains rapports dans le même domaine, pas une phrase unique de la question actuelle. Bons slugs : vendor-comparison, competitor-analysis, regulation-update, <product-area>. Mauvais slugs : doppler-vs-vault-2026 (trop spécifique et lié à une date).

Le script se trouve à ./scripts/research.sh (relatif à ce SKILL.md). Lorsqu'il est invoqué par un agent, utilisez ce chemin relatif à la compétence — il se résout correctement dans les installations npx skills et les installations Claude Code /plugin.

bash ./scripts/research.sh \
  --preset advanced-deep-research \
  --output ./docs/research \
  --topic <topic-slug> \
  --instructions "$(cat <<'EOF'
<collez le plan, le contexte et les exigences de format approuvés ici>
EOF
)" \
  "<la question de recherche, affinée à partir du plan approuvé>"

Étape 4 — Lire le rapport et résumer

Le script imprime le chemin du markdown. Lisez toujours ce fichier avant de faire rapport.

Vérification de troncature (obligatoire) :

1. Confirmez que chaque section listée dans la TdC du rapport est effectivement présente dans le corps.
2. Confirmez qu'aucun tableau ne se termine au milieu d'une ligne et qu'aucune liste détaillée ne se termine au milieu d'un élément.
3. Confirmez que les sections « Sources », « Désaccords entre sources » et « Confiance et lacunes » à la fin sont présentes.

Workflow de récupération après troncature. Si l'un de ces éléments manque → la sortie a été tronquée. Faites ceci :

1. Identifiez exactement ce qui manque. Comparez la TdC du rapport à son corps. Listez les sections manquantes, les tableaux incomplets (notez la dernière ligne complète) et les éléments de liste coupés (notez le dernier élément complet).
2. Quantifiez le travail restant. « X sections, Y éléments, Z lignes encore nécessaires. »
3. Proposez un appel de suivi ciblé avec un périmètre qui respecte le budget par appel. Ne réessayez pas le même périmètre — il sera à nouveau tronqué.
4. Incluez PRIOR FINDINGS dans les --instructions du suivi — collez un résumé de ~200–400 mots des sections terminées afin que l'agent ne les recherche pas à nouveau. Dites explicitement « ne refaites pas X, Y, Z ; concentrez-vous uniquement sur A, B, C. »
5. Informez l'utilisateur de ce qui a été tronqué et montrez le plan de suivi avant d'exécuter.

Mettez en avant : les informations clés, le coût en USD du rapport, tout désaccord notable entre les sources, et un indicateur de troncature si applicable.

Modèles avancés

Ces modèles améliorent systématiquement la qualité de la sortie. Utilisez-les à l'Étape 2 lors de la rédaction du plan.

Citer des experts ou des cadres spécifiques dans votre requête

Nommer 3 à 6 experts, auteurs, créateurs ou cadres nommés pertinents dans la requête donne à l'agent des sources concrètes à rechercher et à comparer. Le rapport devient une comparaison de points de vue connus plutôt qu'une synthèse anonyme.

Exemples de fragments de requête :

• « Comparez les cadres utilisés par , et pour... »
• « Selon la méthodologie <Cadre nommé>, évaluez... »
• « Conciliez les approches recommandées par (dans <livre/blog>) vs ... »

Fonctionne mieux lorsque les experts publient régulièrement (articles, vidéos, posts, conférences) — l'agent peut récupérer leur matériel primaire.

Spécifier des livrables quantifiés

Au lieu de demander « un bon nombre d'exemples », indiquez le nombre exact et la forme. Cela verrouille le périmètre, empêche la dérive et signale lorsque vous dépassez le budget (référence croisée à l'Étape 2.5).

Bonnes spécifications de livrables :

• « Une matrice de comparaison : 8 lignes (une par fournisseur), 5 colonnes (prix, latence, authentification, SDKs, conformité) »
• « Une bibliothèque d'exactement 10 modèles, regroupés en 3 catégories »
• « Une séquence de 14 jours avec un élément par jour »

À éviter : « une bibliothèque complète », « plusieurs exemples », « de nombreuses options » — ce sont des invitations à la troncature ou à l'incertitude.

Pré-charger le contexte dans --instructions, pas dans la requête

La requête doit rester concise en 1 à 2 phrases. Tout ce qui concerne la situation de l'utilisateur, les contraintes, les décisions antérieures ou les préférences de source va dans --instructions. Cela maintient les requêtes de recherche de l'agent ciblées tandis que la synthèse reste ancrée dans votre contexte.

Instructions de format requises (toujours incluses dans --instructions)

Chaque exécution doit intégrer ces exigences de format dans la chaîne --instructions afin que le rapport soit facile à parcourir et digne de confiance :

CONTRAINTE DE TAILLE ET PÉRIMÈTRE (à lire en premier — détermine la profondeur et l'exhaustivité) :

Ce rapport doit tenir dans un plafond de ~10 000 mots. Hiérarchisez impitoyablement. Si les sections détaillées dépassent l'espace disponible, tronquez en profondeur (moins de détails par section) plutôt qu'en largeur (moins de sections). Ne sautez JAMAIS une section listée dans la TdC — compressez son contenu si nécessaire, mais aucune section ne doit être absente.

STRUCTURE OBLIGATOITÉ DU RAPPORT :

1.  **TL;DR (3 à 5 puces)** — en haut. C'est ce que la plupart des lecteurs liront.
2.  **Tableau comparatif s'il y a plusieurs entités** — première section substantielle.
3.  **Analyse / résultats** — par ordre de conclusion d'abord, contexte ensuite.
4.  **Sources** — une section dédiée. Chaque citation en ligne doit avoir une source anonyme qui renvoie ici.
5.  **Là où les sources divergent** — toute controverse ou contradiction. Ne l'éludez pas.
6.  **Confiance et lacunes** — ce que vous ne savez pas, ce qui est spéculatif, ce qui devrait être vérifié manuellement.

RÈGLES DE CITATION :

- Chaque fait, chiffre, affirmation ou attribution doit avoir une citation en ligne avec un numéro de source, par ex. [1], [2a], [3b].
- Si la source est un site Web, incluez l'URL. Si c'est un document, incluez le titre et la date.
- Si l'agent n'a pas de source directe pour une affirmation, marquez-la comme `[source manquante — hypothèse de l'agent]`.
- Ne synthétisez pas des sources disparates comme une seule déclaration à moins que TOUTES les sources citées ne soient d'accord.

FORMAT :

- Utilisez des tableaux Markdown pour les comparaisons, les listes de caractéristiques, les dimensions d'évaluation. Chaque tableau doit avoir un en-tête de colonne et des lignes délimitées.
- Le rapport doit pouvoir être publié tel quel. Pas de commentaires métier, pas d'instructions adressées à l'éditeur.