iterative-retrieval

Aperçu de la compétence iterative-retrieval

La compétence iterative-retrieval est un schéma de travail pour résoudre le « problème de contexte » dans les workflows agentiques : un sous-agent commence avec trop peu d’informations pour savoir ce qu’il lui faut, puis affine progressivement sa recherche jusqu’aux bons fichiers, aux bons termes et aux bons motifs. Elle convient particulièrement aux concepteurs de workflows, aux explorateurs de bases de code et à toute personne qui construit iterative-retrieval for Workflow Automation, lorsque la première passe de récupération est généralement incomplète.

Ce qui compte vraiment pour les utilisateurs, ce n’est pas la théorie, mais de savoir si la compétence aide un agent à éviter deux écueils fréquents : envoyer trop de contexte et exploser le budget, ou en envoyer trop peu et se retrouver bloqué. La valeur principale de iterative-retrieval est de transformer la découverte en boucle plutôt qu’en pari unique.

Ce que iterative-retrieval résout

Utilisez cette compétence quand la tâche dépend d’un contexte propre à la base de code, impossible à connaître à l’avance : repérer des schémas d’implémentation, identifier les fichiers pertinents ou affiner les termes de recherche après un premier sondage. Elle est particulièrement utile lorsqu’un agent doit raisonner sur un gros repo sans guidage humain direct.

Pourquoi cette compétence est différente

Contrairement à un prompt générique du type « regarde autour de toi puis décide », iterative-retrieval fournit une boucle de récupération concrète : envoyer, évaluer, affiner, répéter. Cela facilite l’orchestration de sous-agents, surtout quand votre processus a besoin d’une croissance de contexte prévisible plutôt que de gros vidages bruyants.

Cas d’usage les plus adaptés

Cette compétence convient à la découverte d’architecture, à l’exploration de code de type RAG et aux workflows multi-agents où la première passe de récupération est volontairement incomplète. Elle est moins utile lorsque la réponse est déjà locale, que le repo est minuscule ou que vous pouvez fournir d’emblée la liste exacte des fichiers.

Comment utiliser la compétence iterative-retrieval

Installez-la et activez-la

Utilisez le chemin d’installation de la compétence fourni par votre gestionnaire de compétences, puis pointez votre workflow agentique vers skills/iterative-retrieval/SKILL.md. Un schéma d’installation typique de iterative-retrieval dans ce dépôt est :

npx skills add affaan-m/everything-claude-code --skill iterative-retrieval

Pour de meilleurs résultats, lancez-la lorsque la tâche dépend de la découverte du contexte, pas après avoir déjà trié manuellement tous les fichiers pertinents.

Transformez un objectif flou en prompt exploitable

La compétence donne les meilleurs résultats quand votre prompt fournit à l’agent une cible, une limite et une règle d’arrêt. Un bon input ressemble à ceci :

• Objectif : « Trouve le flux d’authentification et explique où le rafraîchissement du jeton est géré. »
• Limite : « Recherche uniquement dans le code de production, pas dans les tests. »
• Contrainte : « Garde chaque passe de récupération à quelques fichiers maximum. »
• Condition de réussite : « Retourne l’ensemble minimal de fichiers permettant de répondre avec confiance. »

C’est important, parce que iterative-retrieval usage consiste à affiner le contexte, pas à demander au modèle de déduire tout le repo à partir d’une requête vague.

Lisez d’abord ces fichiers

Commencez par SKILL.md, puis examinez les documents d’accompagnement fournis par le dépôt. Dans ce repo, le point d’entrée pratique reste SKILL.md ; si votre installation ne copie que le corps de la compétence, c’est la source de vérité. Ensuite, consultez les documents de workflow proches s’ils existent dans votre environnement, afin d’aligner la boucle avec vos propres règles d’orchestration.

Faites fonctionner la boucle de récupération

Un bon workflow consiste à lancer une recherche ciblée, à vérifier si le contexte renvoyé suffit, à affiner la recherche suivante en fonction de ce qui manquait, puis à boucler jusqu’à ce que l’agent dispose de suffisamment d’éléments pour agir. L’essentiel est de réutiliser les nouveaux termes découverts à chaque passe, plutôt que de répéter la même requête avec des formulations différentes.

FAQ sur la compétence iterative-retrieval

iterative-retrieval est-elle réservée aux grandes bases de code ?

Non. La taille compte, mais le vrai déclencheur est l’incertitude. Si l’agent ne peut pas prévoir quels fichiers importent avant de les lire, iterative-retrieval peut aider même dans un repo de taille moyenne.

Quand ne faut-il pas l’utiliser ?

N’utilisez pas iterative-retrieval lorsque la tâche est déjà bien cadrée, que les fichiers pertinents sont connus ou qu’un prompt direct avec des entrées fixes suffit. Dans ces cas-là, la boucle ajoute de la surcharge sans améliorer la réponse.

Est-ce mieux qu’un prompt classique ?

Pour les tâches de découverte, oui. Un prompt classique suppose souvent que le modèle peut deviner le bon contexte dès le départ. Le guide iterative-retrieval est meilleur lorsque le prompt doit s’adapter après lecture de résultats partiels et que la réponse finale dépend de cette adaptation.

Est-ce adapté aux débutants ?

Oui, si vous suivez la boucle à la lettre. La principale difficulté n’est pas la syntaxe ; c’est de choisir une première récupération suffisamment petite pour être utile, mais assez large pour faire émerger la bonne terminologie.

Comment améliorer la compétence iterative-retrieval

Donnez une cible plus précise à la première passe

Le plus grand gain de qualité vient d’un meilleur cadrage initial. Au lieu de demander « trouve le code pertinent », demandez un comportement, un sous-système ou un point de décision précis. Indiquez ce que vous savez déjà, ce que vous soupçonnez et ce qui constituerait une piste utile. Cela rend iterative-retrieval usage nettement plus efficace.

Surveillez les modes d’échec courants

L’échec le plus fréquent est la sur-récupération : l’agent extrait trop de fichiers et cesse d’apprendre des résultats. L’autre échec est la sous-récupération : trop peu de contexte pour identifier le terme de recherche suivant. Si la première passe renvoie des fichiers génériques, affinez en demandant la terminologie, les points d’appel ou les points d’entrée plutôt qu’en élargissant la recherche.

Itérez avec des preuves, pas avec des suppositions

Après la première sortie, ne renvoyez que les éléments les plus informatifs : noms de fichiers, noms de fonctions, messages d’erreur ou termes inconnus. Évitez de demander à l’agent de « regarder encore » sans ajouter de nouvelles preuves. Pour iterative-retrieval for Workflow Automation, la meilleure amélioration consiste à intégrer cette boucle de preuves dans votre orchestration afin que chaque passe modifie l’espace de recherche.

Adaptez-la aux règles de votre dépôt

Si votre environnement impose des conventions de nommage, des limites de dossiers ou des règles de passation entre agents, intégrez-les au prompt avant la première récupération. La compétence est plus efficace lorsqu’elle respecte la structure réelle de votre dépôt, au lieu de traiter chaque base de code comme un simple problème de recherche générique.