karthikselvarjn/lead-signal-scout

Lead Signal Scout

Transformez une URL de produit en une shortlist où chaque entrée repose sur une page que l'agent a ouverte, lue et datée, et qui appartient à une personne réellement acheteuse. Les prospects non vérifiés, obsolètes ou non qualifiés n'atteignent jamais la shortlist.

Six portes sont obligatoires. En sauter une invalide l'exécution ; dites-le plutôt que de livrer le résultat.

1. Intake (étape 1) – ne pas faire de recherche tant que le brief ne peut pas rejeter une correspondance faible.
2. Vérification (étape 4) – ne pas rédiger un prospect dont la page n'a pas été récupérée.
3. Screening (étape 4) – ne pas abandonner une requête qui a produit des résultats sans en avoir ouvert un et noté pourquoi.
4. Récence (étape 5) – ne pas shortlister un signal non daté ou dépassant le seuil.
5. Qualification (étape 6) – ne pas shortlister un prospect sans problème propre attesté, sans capacité d'achat, sans voie de contact utilisable, ou sans entreprise identifiée en mode centré sur l'entreprise.
6. Audit (étape 8) – ne pas présenter de résultats avant que validate_run.py ne retourne PASS.

Rédigez chaque champ en prose en vous référant à references/writing-rules.md. Un rapport qui semble généré est ignoré, quelle que soit la recherche derrière.

Workflow

1. Intake

Lisez references/intake.md. Construisez le brief produit, puis demandez une fois, en un seul message groupé, les quatre choses qu'une page d'accueil ne peut pas vous dire : la zone géographique, la fourchette de prix et la dynamique d'achat, les exclusions, et toute donnée sur les clients existants ou les victoires passées. Procédez avec des hypothèses étiquetées si l'utilisateur ne répond pas.

Enregistrez icp.price_band_source comme user ou assumed. C'est important : une fourchette que vous inventez ne peut exclure personne. Avec assumed, ne notez pas commercial_fit en dessous de 3 pour des raisons de prix. Un nombre que personne n'a confirmé n'a pas à décider quelles vraies entreprises sont exclues.

Définissez max_age_days ici. La valeur par défaut est 120. Utilisez 60 quand les signaux seront des offres d'emploi ou des recherches de fournisseurs, où une demande vieille de quatre mois est presque toujours pourvue.

2. Définir le mode et la profondeur

Le mode détermine ce qui est optimisé. La profondeur détermine le nombre. Ils sont indépendants.

Mode	Optimise pour	Pondérations (pain / fit / commercial / timing / reach / evidence)
discovery (par défaut)	Douleur non satisfaite, pré-product-market-fit	28 / 22 / 10 / 14 / 13 / 13
pipeline	Flux de leads reproductible pour une entreprise vendeuse	22 / 20 / 20 / 14 / 12 / 12
design-partners	Personnes susceptibles de tester et de donner leur avis	24 / 18 / 6 / 10 / 24 / 18
b2b	Entreprises avec un déclencheur commercial actuel	14 / 20 / 26 / 18 / 11 / 11
community	Demandes publiques explicites et discussions	28 / 18 / 8 / 14 / 22 / 10

Les modes b2b et pipeline refusent également de shortlister un prospect dont l'entreprise n'est pas identifiée.

Profondeur	Plafond de shortlist	Requêtes minimales	Pages ouvertes minimales	Couverture minimale par bucket x famille
quick	5	10	12	4 buckets x 3 familles
standard (par défaut)	10	18	20	5 buckets x 4 familles
deep	20	35	35	7 buckets x 6 familles

Les requêtes mesurent la frappe, les pages mesurent la lecture, et une seule d'entre elles trouve des clients. Enregistrez le nombre dans coverage.pages_opened, y compris les pages qui ne sont jamais devenues candidates.

Copiez le profil du mode choisi dans le run JSON textuellement. L'auditeur recalcule chaque score par rapport à ce profil et échoue si les pondérations déclarées s'écartent du profil du mode.

3. Planifier et exécuter la recherche

Lisez references/search-playbook.md. Rédigez le plan de requêtes avant la recherche : quels buckets, quelles familles de sources, quelles formulations dans les mots du public. Enregistrez chaque requête et son nombre de résultats, y compris celles sans résultat. Collectez les URL candidates ; n'écrivez pas encore les fiches prospects.

4. Vérifier avant d'écrire

Lisez references/verification.md. Récupérez chaque URL candidate, puis décidez :

• signal_confirmed – page récupérée, signal présent sur celle-ci, attribuable au prospect nommé. Seule cette catégorie peut être shortlistée.
• url_ok – récupérée, mais le signal est nuancé, l'attribution est inférée, ou la date manque. Niveau de révision.
• unverified – non récupérée, morte, ou protégée. Ajoutez à dropped avec la raison et arrêtez-vous. Ne rédigez pas de fiche.

Rédiger une fiche prospect complète puis la jeter parce que la page est en 404 gaspille la majeure partie d'une exécution. Récupérez d'abord, écrivez ensuite.

Ouvrez ce que vous êtes sur le point d'abandonner. Toute requête qui a produit trois résultats ou plus et n'en a conservé aucun nécessite une note sur son entrée de couverture, rédigée après avoir ouvert un de ces résultats. L'auditeur échoue une exécution où la plupart des requêtes abandonnées ne portent pas de note.

C'est l'étape qui décide qui est sur la shortlist, et elle est invisible sauf si vous l'écrivez. Une exécution qui enregistre 16 requêtes et couvre tous les seuils peut quand même avoir remonté 75 résultats, en avoir ouvert 10, et avoir tiré toute sa shortlist de trois requêtes en forme d'annonces, pendant qu'une page d'avis concurrents et trois appels d'offres publics restaient non lus. La ligne d'audit appellera cela une couverture complète. Vérifiez également la voie de contact en plus de la source ; verification.md couvre ce qu'il faut enregistrer.

Limites de recherche : uniquement des informations professionnelles et commerciales publiques ; pas de contournement des connexions, paywalls, contrôles d'accès, limites de débit ou restrictions robots ; pas d'intermédiaires de données, de jeux de données fuités, de groupes privés, de découverte d'emails personnels ou d'enrichissement téléphonique ; ne jamais inférer ou cibler sur des traits protégés, la santé, les difficultés financières, la politique, la religion ou la sexualité.

5. Dater chaque signal

Le timing est évalué à partir de l'âge, donc un signal non daté ne peut pas être shortlisté. Parcourez cette liste et arrêtez-vous à la première qui donne une réponse : une date de publication visible, un timestamp relatif sur la page converti en signal_age_days, ou un timestamp encodé dans l'URL. Enregistrez celui que vous avez utilisé dans date_basis. verification.md donne la méthode pour chacun.

N'estimez jamais un âge. Les dates partielles comme 2026-08 sont rejetées, de même que les dates futures. Une entrée de shortlist reposant sur une date supposée est exactement l'échec que ce skill existe pour empêcher.

Enregistrez fetched_at et final_url pour chaque prospect confirmé. L'auditeur ne peut pas vous voir récupérer une page ; ces informations rendent une affirmation non étayée plus difficile que de le faire correctement.

6. Noter, filtrer et dédoublonner

Lisez references/scoring.md. Notez six dimensions de 0 à 5 par rapport aux ancres écrites. Le timing vient de l'âge, plafonné par palier ; un déclencheur actuel nommé élève le plafond d'un point.

pain_strength note le problème propre du prospect, dans le travail que fait le produit, dans ses mots. Un problème de leurs clients, un problème dont ils vendent la solution, ou une tendance de marché qu'ils ont commentée notent tous 0. Chaque marque grand public lance des campagnes ; ce n'est pas un signal.

commercial_fit demande si ce vendeur peut conclure cet acheteur via la dynamique que ce vendeur a. Pas si l'entreprise est grande. Un chiffre d'affaires de plusieurs milliards, cent pays et un portail fournisseur publié sont des preuves d'une file d'approvisionnement, et pour un vendeur en libre-service ou fondateur, cela note 2, pas 4.

Éliminez tout ce qui est en dessous de 50. Acheminez vers le niveau de révision tout élément non daté, plus vieux que max_age_days sans les trois champs still_open, notant 0 ou 1 sur pain_strength sans trigger nommé, notant 0 ou 1 sur commercial_fit par rapport à une fourchette fournie par l'utilisateur, dont la seule voie de contact est inappropriate, ou dont l'entreprise n'est pas identifiée en mode b2b ou pipeline. Rien n'est supprimé ; le niveau de révision montre chacun avec sa raison.

Enregistrez signal_type et purchase_readiness plutôt qu'une seule étiquette d'intention. Quelqu'un qui recrute un designer a une intention réelle et aucune intention d'acheter un logiciel. Les deux étiquettes ont des plafonds liés aux dimensions en dessous : hiring ne peut pas dépasser adjacent, un signal basé sur la douleur nécessite pain_strength de 3 pour strong, strong nécessite commercial_fit de 3, et direct nécessite 4. L'auditeur les applique tous, car des champs de texte libre qui dérivent vers le haut ensemble transforment une annonce de lancement en acheteur à forte intention.

Une page qui recrute un freelance, un contractuel ou un employé est hiring, quelle que soit la correspondance exacte du travail avec le produit. Ils sélectionnent une personne, pas un service, et hiring plafonne la maturité à adjacent. Classer une annonce d'emploi comme direct_request contourne ce plafond, ce qui a permis à un brief freelance à quinze dollars de l'heure de dominer une shortlist. L'indice est dans ce que la voie demande : un portfolio, CV, CV ou grille tarifaire signifie embauche ; périmètre, prix, délai ou essai signifie achat.

Dédoublonnez sur dedupe_key. Chargez ledger.json des exécutions précédentes dans le même répertoire de sortie et excluez ce qu'il a déjà remonté, ainsi que tout élément de la liste d'exclusion de l'utilisateur.

Maintenez la shortlist répartie entre les sources : pas plus de la moitié provenant d'une seule famille de sources ou d'un seul domaine. Le site qui récupère le plus fiablement prendrait autrement le contrôle de l'exécution, et une shortlist mono-source hérite du biais de ce site.

Si plus de 60 pour cent de la shortlist obtient un score de 80+, les ancres ont été appliquées de manière lâche. Re-notez.

7. Enregistrer qui, où et comment les joindre

Séparez company, person et handle. L'entreprise est celle qui achèterait ; la personne est celle qui a posté ; le handle est son nom d'utilisateur sur la plateforme. Quand aucune entreprise n'est visible, définissez company sur not identified et mettez le handle dans handle, écrit comme la plateforme l'écrit (u/nom). Les sorties commencent par le handle dans ce cas. Cherchez d'abord l'entreprise : les affiches la nomment souvent dans le fil, leur profil ou un lien.

Donnez à chaque prospect un channel_url : la page que l'utilisateur ouvre réellement pour prendre contact. Souvent le fil source, parfois un formulaire de contact ou un profil. Ouvrez-le, et enregistrez channel_evidence : une courte citation ou le titre de la page montrant à qui la voie est destinée. Un prospect shortlisté prétendant avoir channel_fit: valid sans cela échoue à l'audit.

Les portails de fournisseurs et d'enregistrement de vendeurs sont au mieux questionable, une file d'attente plutôt qu'une conversation. Les voies de candidature, presse et support client sont inappropriate. Quand la première voie que vous trouvez est de la mauvaise forme, passez une récupération supplémentaire à chercher la bonne avant de radier le prospect ; les grands sites enterrent la page de contact commercial et classent la page carrières.

L'auditeur lit channel_evidence, pas seulement l'URL. Une offre d'emploi sur Reddit ou LinkedIn a une URL parfaitement propre et ne se trahit que dans les mots : "partagez votre portfolio et CV à jour" est une voie de candidature où qu'elle soit hébergée.

Laissez additional_source_urls vide sauf si une autre page montre le même signal. Cela s'affiche comme "Également vu sur", donc y mettre la page de contact revendique une corroboration qui n'existe pas.

Rédigez un message d'ouverture par prospect shortlisté, moins de 90 mots, basé uniquement sur la page récupérée. N'envoyez pas, ne soumettez pas, ne vous connectez pas, ne suivez pas, ne commentez pas et n'écrivez pas dans un CRM sauf si l'utilisateur l'autorise séparément dans un tour ultérieur.

8. Construire les sorties et auditer

Lisez references/output-schema.md, écrivez run.json, puis :

python3 <skill-dir>/scripts/validate_run.py run.json
python3 <skill-dir>/scripts/build_outputs.py run.json outputs/

<skill-dir> est le répertoire propre de ce skill, celui d'où ce SKILL.md a été chargé. Construisez un chemin absolu à partir de celui-ci. N'utilisez pas un chemin relatif au répertoire de travail : le répertoire de travail est le projet de l'utilisateur, pas le skill. Si l'hôte substitue ${CLAUDE_SKILL_DIR}, cette variable est exactement ce répertoire.

Corrigez chaque ERREUR et relancez jusqu'à ce qu'il affiche PASS. Rapportez la ligne d'audit textuellement dans la réponse finale. build_outputs.py écrit leads.csv (la liste opérationnelle), leads-full.csv (tous les champs), report.html, brief.md et un ledger.json mis à jour. Conservez run.json à côté comme source de vérité.

Sans Python : écrivez brief.md et leads.csv manuellement à partir du schéma et effectuez les vérifications de l'auditeur manuellement.

9. Rapporter

Retournez la ligne d'audit textuellement dans votre réponse et dans brief.md. Elle n'apparaît pas dans report.html lors d'une exécution réussie, car une bannière verte disant "ok" n'est pas ce que quelqu'un ouvre un rapport de prospects pour lire.

Ensuite, le verdict, le meilleur prospect, et les chemins absolus vers les artefacts. Commencez par ce qui est vérifié et daté. Rendez les lacunes visibles.

Barre de qualité

• Un prospect sans source récupérée n'est pas un prospect. Un prospect sans date n'est pas un lead. Un prospect qui ne peut pas acheter est une interview de recherche. Un prospect qui n'a énoncé aucun problème propre est un segment de marché.
• Les résultats remontés et jamais ouverts sont le véritable résultat de l'exécution. Comptez-les, et ouvrez ceux que vous étiez sur le point de sauter.
• Une exécution qui a examiné trente candidats et n'en a shortlisté aucun est un résultat valide. Rapportez-le clairement plutôt que de gonfler.
• Dix correspondances vérifiées et actuelles valent mieux que cinquante génériques.
• Rapportez ce qui a été cherché et n'a rien donné, pas seulement ce qui a été trouvé.
• Personnalisez à partir de la source, jamais de l'invention.
• Étiquetez tout comme une hypothèse. Un signal public n'est pas un consentement, un intérêt ou une intention d'achat.