feat(hands): complete i18n fixes, SKILL.md enhancements, and README overhaul

- Fix French accent characters (é/è/ê/ç/â/ô) across all 14 HAND.toml files - Fix German special characters (ä/ö/ü/ß) across all 14 HAND.toml files - Add category translations to all 6 i18n language blocks in all 14 hands - Enhance SKILL.md content for 9 hands with practical examples and workflows - Trim bloated SKILL.md files (apitester 1400→892, devops 1301→870) - Rewrite root README.md with accurate stats, complete hand/integration tables - Update hands/README.md with full 14-hand listing and i18n documentation
2026-03-23 00:18:18 +09:00
1 parent 315f955ce2
commit 33d279889c
@@ -380,6 +380,265 @@ token_consumption = "medium"
 default_active = false
 activation_warning = "Lead hand runs continuously and generates leads on schedule, consuming tokens."

+# ─── Internationalization (optional) ─────────────────────────────────────────
+# All i18n sections are optional. Without them, the English values above are used.
+# To localize, add [i18n.LANG] sections (e.g. zh, ja, ko, es, fr, de).
+# Settings translations are also optional — omit to keep English labels.
+
+# ─── Chinese (简体中文) ────────────────────────────────────────────────────
+
 [i18n.zh]
 name = "线索生成 Hand"
 description = "自主线索生成——按计划发现、充实并交付合格的潜在客户"
+category = "数据"
+
+[i18n.zh.settings.target_industry]
+label = "目标行业"
+description = "重点关注的行业垂直领域（例如 SaaS、金融科技、医疗健康、电子商务）"
+
+[i18n.zh.settings.target_role]
+label = "目标职位"
+description = "要触达的决策者头衔（例如 CTO、工程副总裁、产品负责人）"
+
+[i18n.zh.settings.company_size]
+label = "公司规模"
+description = "按公司规模筛选线索"
+
+[i18n.zh.settings.lead_source]
+label = "线索来源"
+description = "发现线索的主要方式"
+
+[i18n.zh.settings.output_format]
+label = "输出格式"
+description = "报告交付格式"
+
+[i18n.zh.settings.leads_per_report]
+label = "每份报告线索数"
+description = "每份报告中包含的线索数量"
+
+[i18n.zh.settings.delivery_schedule]
+label = "交付计划"
+description = "生成和交付线索报告的时间安排"
+
+[i18n.zh.settings.geo_focus]
+label = "地域重点"
+description = "优先关注的地理区域（例如美国、欧洲、亚太、全球）"
+
+[i18n.zh.settings.enrichment_depth]
+label = "信息丰富度"
+description = "对每条线索收集多少上下文信息"
+
+# ─── Korean (한국어) ────────────────────────────────────────────────────
+
+[i18n.ko]
+name = "리드 생성 Hand"
+description = "자율 리드 생성 — 일정에 따라 적격 리드를 탐색, 보강 및 전달"
+category = "데이터"
+
+[i18n.ko.settings.target_industry]
+label = "대상 산업"
+description = "집중할 산업 분야 (예: SaaS, 핀테크, 헬스케어, 이커머스)"
+
+[i18n.ko.settings.target_role]
+label = "대상 직책"
+description = "타겟할 의사결정자 직함 (예: CTO, 엔지니어링 VP, 프로덕트 총괄)"
+
+[i18n.ko.settings.company_size]
+label = "회사 규모"
+description = "회사 규모별 리드 필터링"
+
+[i18n.ko.settings.lead_source]
+label = "리드 소스"
+description = "리드를 발굴하는 주요 방법"
+
+[i18n.ko.settings.output_format]
+label = "출력 형식"
+description = "보고서 전달 형식"
+
+[i18n.ko.settings.leads_per_report]
+label = "보고서당 리드 수"
+description = "각 보고서에 포함할 리드 수"
+
+[i18n.ko.settings.delivery_schedule]
+label = "전달 일정"
+description = "리드 보고서 생성 및 전달 시간"
+
+[i18n.ko.settings.geo_focus]
+label = "지역 중점"
+description = "우선적으로 집중할 지역 (예: 미국, 유럽, 아시아 태평양, 글로벌)"
+
+[i18n.ko.settings.enrichment_depth]
+label = "보강 깊이"
+description = "리드당 수집할 컨텍스트 정보의 수준"
+
+# ─── Japanese (日本語) ────────────────────────────────────────────────────
+
+[i18n.ja]
+name = "リード生成 Hand"
+description = "自律型リード生成エージェント——スケジュールに基づき見込み客を発見・情報付加・配信"
+category = "データ"
+
+[i18n.ja.settings.target_industry]
+label = "ターゲット業界"
+description = "注力する業界バーティカル（例: SaaS、フィンテック、ヘルスケア、EC）"
+
+[i18n.ja.settings.target_role]
+label = "ターゲット職種"
+description = "アプローチする意思決定者の肩書き（例: CTO、VP Engineering、プロダクト責任者）"
+
+[i18n.ja.settings.company_size]
+label = "企業規模"
+description = "企業規模でリードをフィルタリング"
+
+[i18n.ja.settings.lead_source]
+label = "リードソース"
+description = "リードを発見する主な方法"
+
+[i18n.ja.settings.output_format]
+label = "出力形式"
+description = "レポートの配信形式"
+
+[i18n.ja.settings.leads_per_report]
+label = "レポートあたりのリード数"
+description = "各レポートに含めるリードの数"
+
+[i18n.ja.settings.delivery_schedule]
+label = "配信スケジュール"
+description = "リードレポートの生成・配信タイミング"
+
+[i18n.ja.settings.geo_focus]
+label = "地域フォーカス"
+description = "優先する地理的リージョン（例: 米国、欧州、APAC、グローバル）"
+
+[i18n.ja.settings.enrichment_depth]
+label = "情報付加の深さ"
+description = "リードごとに収集するコンテキスト情報の量"
+
+# ─── Spanish (Español) ────────────────────────────────────────────────────
+
+[i18n.es]
+name = "Hand de Generación de Leads"
+description = "Generación autónoma de leads — descubre, enriquece y entrega leads cualificados según un calendario"
+category = "Datos"
+
+[i18n.es.settings.target_industry]
+label = "Industria objetivo"
+description = "Vertical de industria en la que enfocarse (ej. SaaS, fintech, salud, e-commerce)"
+
+[i18n.es.settings.target_role]
+label = "Rol objetivo"
+description = "Títulos de tomadores de decisiones a los que dirigirse (ej. CTO, VP de Ingeniería, Director de Producto)"
+
+[i18n.es.settings.company_size]
+label = "Tamaño de empresa"
+description = "Filtrar leads por tamaño de empresa"
+
+[i18n.es.settings.lead_source]
+label = "Fuente de leads"
+description = "Método principal para descubrir leads"
+
+[i18n.es.settings.output_format]
+label = "Formato de salida"
+description = "Formato de entrega del informe"
+
+[i18n.es.settings.leads_per_report]
+label = "Leads por informe"
+description = "Número de leads a incluir en cada informe"
+
+[i18n.es.settings.delivery_schedule]
+label = "Calendario de entrega"
+description = "Cuándo generar y entregar los informes de leads"
+
+[i18n.es.settings.geo_focus]
+label = "Enfoque geográfico"
+description = "Región geográfica a priorizar (ej. EE.UU., Europa, Asia-Pacífico, global)"
+
+[i18n.es.settings.enrichment_depth]
+label = "Profundidad de enriquecimiento"
+description = "Cuánto contexto recopilar por cada lead"
+
+# ─── French (Français) ────────────────────────────────────────────────────
+
+[i18n.fr]
+name = "Hand Génération de Prospects"
+description = "Génération autonome de prospects — découvre, enrichit et livre des prospects qualifiés selon un calendrier"
+category = "Données"
+
+[i18n.fr.settings.target_industry]
+label = "Secteur cible"
+description = "Secteur d'activité cible (ex. SaaS, fintech, santé, e-commerce)"
+
+[i18n.fr.settings.target_role]
+label = "Poste cible"
+description = "Titres de décideurs à cibler (ex. CTO, VP Engineering, Directeur Produit)"
+
+[i18n.fr.settings.company_size]
+label = "Taille d'entreprise"
+description = "Filtrer les prospects par taille d'entreprise"
+
+[i18n.fr.settings.lead_source]
+label = "Source de prospects"
+description = "Méthode principale de découverte des prospects"
+
+[i18n.fr.settings.output_format]
+label = "Format de sortie"
+description = "Format de livraison des rapports"
+
+[i18n.fr.settings.leads_per_report]
+label = "Prospects par rapport"
+description = "Nombre de prospects à inclure dans chaque rapport"
+
+[i18n.fr.settings.delivery_schedule]
+label = "Calendrier de livraison"
+description = "Quand générer et livrer les rapports de prospects"
+
+[i18n.fr.settings.geo_focus]
+label = "Focus géographique"
+description = "Région géographique prioritaire (ex. USA, Europe, Asie-Pacifique, Mondial)"
+
+[i18n.fr.settings.enrichment_depth]
+label = "Profondeur d'enrichissement"
+description = "Niveau d'informations contextuelles à collecter par prospect"
+
+# ─── German (Deutsch) ────────────────────────────────────────────────────
+
+[i18n.de]
+name = "Lead-Generierungs-Hand"
+description = "Autonome Lead-Generierung — entdeckt, bereichert und liefert qualifizierte Leads nach Zeitplan"
+category = "Daten"
+
+[i18n.de.settings.target_industry]
+label = "Zielbranche"
+description = "Branchenvertikale für den Fokus (z.B. SaaS, Fintech, Gesundheitswesen, E-Commerce)"
+
+[i18n.de.settings.target_role]
+label = "Zielposition"
+description = "Titel der Entscheidungsträger (z.B. CTO, VP Engineering, Produktleiter)"
+
+[i18n.de.settings.company_size]
+label = "Unternehmensgröße"
+description = "Leads nach Unternehmensgröße filtern"
+
+[i18n.de.settings.lead_source]
+label = "Lead-Quelle"
+description = "Primäre Methode zur Lead-Entdeckung"
+
+[i18n.de.settings.output_format]
+label = "Ausgabeformat"
+description = "Berichtslieferformat"
+
+[i18n.de.settings.leads_per_report]
+label = "Leads pro Bericht"
+description = "Anzahl der Leads pro Bericht"
+
+[i18n.de.settings.delivery_schedule]
+label = "Lieferzeitplan"
+description = "Wann Lead-Berichte generiert und geliefert werden"
+
+[i18n.de.settings.geo_focus]
+label = "Geografischer Fokus"
+description = "Priorisierte geografische Region (z.B. USA, Europa, Asien-Pazifik, Global)"
+
+[i18n.de.settings.enrichment_depth]
+label = "Anreicherungstiefe"
+description = "Umfang der pro Lead gesammelten Kontextinformationen"
@@ -62,6 +62,88 @@ site:builtwith.com "[company]"
 7. **News articles** — recent activity, reputation
 8. **Social media** — engagement, company culture

+### Industry-Specific Search Patterns
+
+#### SaaS / Technology
+```
+# Company directories
+site:g2.com/products "[category]"
+site:capterra.com "[category] software"
+site:producthunt.com "[product type]" "[year]"
+"[category] software" site:crunchbase.com/organization
+
+# Tech stack signals
+site:stackshare.io "[technology]" decisions
+site:builtwith.com/websites/[technology]
+
+# Growth signals
+"[company] SOC 2" OR "[company] ISO 27001"        — enterprise readiness
+"[company] API" OR "[company] integration"          — platform maturity
+"[company] case study" OR "[company] customer story" — traction evidence
+```
+
+#### Healthcare
+```
+# Directories & registries
+site:healthcareittoday.com "[company]"
+"digital health companies" site:crunchbase.com
+"health tech" "[city/state]" site:angellist.co
+"HIPAA compliant" "[category] software"
+
+# Regulatory signals
+"[company] FDA clearance" OR "[company] 510(k)"
+"[company] HIPAA" OR "[company] HITRUST"
+"[company] clinical trial" site:clinicaltrials.gov
+```
+
+#### Financial Services
+```
+# Directories & databases
+site:fintechmagazine.com "top" "[category]"
+"fintech companies" "[region]" site:crunchbase.com
+"banking technology" OR "insurtech" site:cbinsights.com
+
+# Compliance signals
+"[company] SOX compliance" OR "[company] PCI DSS"
+"[company] banking license" OR "[company] money transmitter"
+"[company] Series [A/B/C]" "fintech"
+```
+
+#### E-commerce
+```
+# Directories & tools
+site:apps.shopify.com "[category]"
+site:store.bigcommerce.com "[category]"
+"ecommerce brands" "[niche]" site:2pm.com OR site:modernretail.co
+
+# Revenue signals
+"[company] GMV" OR "[company] ARR"
+"[company] warehouse" OR "[company] fulfillment center"
+"[brand] DTC" OR "[brand] direct to consumer"
+```
+
+#### Manufacturing
+```
+# Directories
+site:thomasnet.com "[product category]"
+"manufacturing companies" "[city/state]" site:mfg.com
+"industrial [category]" site:dnb.com
+
+# Modernization signals
+"[company] Industry 4.0" OR "[company] smart factory"
+"[company] ERP" OR "[company] digital transformation"
+"[company] ISO 9001" OR "[company] ISO 14001"
+```
+
+#### Industry Source Quick Reference
+| Vertical | Primary Directories | Key Signal Keywords |
+|----------|-------------------|---------------------|
+| SaaS/Tech | G2, Capterra, ProductHunt, Crunchbase | "API launch", "SOC 2", "Series X" |
+| Healthcare | HealthcareIT, ClinicalTrials.gov | "HIPAA", "FDA", "clinical trial" |
+| Financial Services | CBInsights, Crunchbase | "PCI DSS", "banking license", "Series X" |
+| E-commerce | Shopify App Store, ModernRetail | "GMV", "DTC", "fulfillment" |
+| Manufacturing | ThomasNet, MFG.com | "Industry 4.0", "ISO 9001", "ERP" |
+
 ---

 ## Lead Enrichment Patterns
@@ -145,6 +227,63 @@ Accessibility (15 points max):

 ---

+## Lead Qualification Frameworks
+
+### BANT Framework
+
+Use BANT to quickly qualify leads during or after enrichment. Each dimension maps to data you can discover through web research.
+
+| Dimension | Question | Research Signals |
+|-----------|----------|-----------------|
+| **Budget** | Can they afford the solution? | Funding rounds, revenue estimates, job postings for related roles, pricing tier of current tools |
+| **Authority** | Is this person a decision-maker? | Title seniority (VP+, C-level, Director), reports to CEO/CTO, listed on "Leadership" page |
+| **Need** | Do they have the problem you solve? | Job postings mentioning the pain point, tech stack gaps, competitor tool usage, complaints on forums |
+| **Timeline** | Is there urgency to buy? | Contract renewals, compliance deadlines, product launches, recent leadership changes |
+
+#### BANT Scoring Overlay
+Apply these modifiers on top of the base lead score:
+```
+Budget confirmed (funding, revenue signal):   +5
+Authority confirmed (VP+ or C-level):         +5
+Need confirmed (pain point evidence):         +5
+Timeline confirmed (urgency signal):          +5
+                                     Max bonus: +20
+```
+
+### MEDDIC Framework
+
+Use MEDDIC for complex / enterprise sales qualification where longer deal cycles demand deeper research.
+
+| Dimension | Definition | What to Look For |
+|-----------|-----------|-----------------|
+| **Metrics** | Quantifiable outcomes the buyer cares about | Case studies they publish, KPIs in job postings, analyst reports, earnings calls |
+| **Economic Buyer** | Person with budget authority to sign | CFO, CEO, VP Finance, or "Head of Procurement" listed on team pages |
+| **Decision Criteria** | Factors they use to evaluate vendors | RFP documents, vendor comparison blog posts, compliance requirements, review site feedback |
+| **Decision Process** | Steps from evaluation to purchase | Procurement team presence, legal/compliance review cycles, pilot program mentions |
+| **Identify Pain** | Specific problems driving the purchase | Support forums, Glassdoor reviews, social media complaints, analyst reports on industry challenges |
+| **Champion** | Internal advocate for your solution | Conference speakers, blog authors, open-source contributors, people who engage with your content |
+
+#### MEDDIC Research Checklist
+```
+For each enterprise lead, attempt to discover:
+[ ] At least one quantifiable metric they care about
+[ ] The economic buyer's name and title
+[ ] 2+ decision criteria (compliance, performance, price, integration)
+[ ] Whether they run formal procurement (RFP, committee)
+[ ] 1+ specific pain point with evidence
+[ ] A potential internal champion (engaged user, tech advocate)
+```
+
+### Choosing Between BANT and MEDDIC
+| Scenario | Recommended Framework |
+|----------|----------------------|
+| SMB / startup targets, short sales cycle | BANT |
+| Enterprise targets, $100K+ deal size | MEDDIC |
+| Mixed list with varied company sizes | BANT first pass, MEDDIC for A-grade enterprise leads |
+| Time-constrained research | BANT (faster to assess) |
+
+---
+
 ## Deduplication Strategies

 ### Matching Algorithm
@@ -212,6 +351,166 @@ Name,Title,Company,Company URL,LinkedIn,Industry,Size,Score,Discovered,Notes

 ---

+## Worked Examples
+
+### Example 1: Fintech SaaS Series A/B Companies (50-200 Employees)
+
+**Objective**: Find 10 SaaS companies in the fintech space with 50-200 employees that recently raised Series A or B.
+
+#### Step 1 — Define ICP
+```
+Industry:       Fintech / Financial Technology
+Company size:   50-200 employees (SMB)
+Funding stage:  Series A or Series B (raised within last 18 months)
+Geography:      United States (primary), UK/EU (secondary)
+Decision-maker: VP Engineering, CTO, or Head of Product
+Pain points:    Scaling infrastructure, compliance automation, developer tooling
+```
+
+#### Step 2 — Execute Search Queries
+```
+# Primary discovery queries
+"fintech" "series A" OR "series B" site:crunchbase.com/organization
+"fintech startup" "raised" "$" "2025" OR "2024" site:techcrunch.com
+site:news.crunchbase.com "fintech" "series A" OR "series B"
+
+# Employee count validation
+"fintech" "50" OR "100" OR "150" "employees" site:linkedin.com/company
+site:builtin.com/companies/fintech "51-200 employees"
+
+# Growth signals
+"fintech" hiring "senior engineer" OR "staff engineer" site:linkedin.com/jobs
+"fintech startup" "SOC 2" OR "PCI DSS" — compliance-ready = selling to banks
+```
+
+#### Step 3 — Enrich and Score Each Lead
+```
+For each discovered company, gather:
+  1. Company website → About page → leadership team, employee count
+  2. Crunchbase profile → funding amount, date, investors, total raised
+  3. LinkedIn company page → exact employee count, recent hires
+  4. Job boards → open roles (signals growth and tech stack)
+  5. Press releases → product launches, partnerships, customer wins
+
+Scoring example for "PayFlow Inc":
+  ICP Match:         25/30 (fintech ✓, 130 employees ✓, US ✓, CTO found ✓, no geography bonus)
+  Growth Signals:    18/20 (Series B $18M ✓, hiring 8 engineers ✓, product launch ✓)
+  Enrichment:        15/20 (LinkedIn ✓, full company data ✓, tech stack ✓, no direct email)
+  Recency:           15/15 (funding announced 3 weeks ago)
+  Accessibility:     10/15 (company contact form, CTO LinkedIn)
+  TOTAL:             83/100 → Grade A
+```
+
+#### Step 4 — Final Output (top 3 of 10)
+| # | Name | Title | Company | Employees | Funding | Score | Key Signal |
+|---|------|-------|---------|-----------|---------|-------|------------|
+| 1 | Sarah Chen | CTO | PayFlow Inc | 130 | Series B, $18M | 83 | Funded 3 weeks ago, hiring 8 engineers |
+| 2 | Marcus Rivera | VP Engineering | LendStack | 85 | Series A, $12M | 78 | Launched API platform Q4, SOC 2 certified |
+| 3 | Priya Patel | Head of Product | ComplianceAI | 62 | Series A, $8M | 75 | Hiring product + eng, regulatory focus |
+
+---
+
+### Example 2: Enterprise AI/ML Decision-Makers
+
+**Objective**: Identify decision-makers at enterprise companies (500+ employees) that are actively adopting AI/ML tools.
+
+#### Step 1 — Define ICP
+```
+Industry:       Any (cross-industry AI adoption)
+Company size:   500+ employees (Enterprise)
+Signals:        Active AI/ML adoption (hiring, projects, tool procurement)
+Geography:      North America
+Decision-maker: VP/Director of Data Science, Head of AI/ML, CTO, Chief Data Officer
+Pain points:    ML model deployment, data pipeline scaling, AI governance
+```
+
+#### Step 2 — Execute Search Queries
+```
+# Identify companies investing in AI
+"head of AI" OR "VP data science" OR "chief data officer" hiring site:linkedin.com
+"[company] machine learning" "team" OR "department" site:linkedin.com/company
+"AI adoption" OR "ML platform" "enterprise" site:venturebeat.com OR site:techcrunch.com
+
+# Conference and community signals
+"speaker" "machine learning" OR "AI" site:neurips.cc OR site:icml.cc
+"[company] MLOps" OR "[company] AI infrastructure" site:github.com
+
+# Budget and procurement signals
+"AI budget" OR "ML tools" RFP site:gov OR site:rfpdb.com
+"[company] partnership" "AI" OR "machine learning" press release
+```
+
+#### Step 3 — Multi-Source Enrichment
+```
+For enterprise targets, cross-reference at least 3 sources per lead:
+
+  Source 1: LinkedIn
+    → Title confirmation, tenure, reporting structure
+    → Company employee count, growth rate
+    → Recent posts about AI/ML topics (champion signal)
+
+  Source 2: Company website + press
+    → AI/ML team page, published case studies
+    → Press releases about AI initiatives
+    → Open positions on careers page
+
+  Source 3: Community / conferences
+    → Conference talks (NeurIPS, ICML, KDD, MLOps World)
+    → GitHub contributions (open-source ML projects)
+    → Blog posts or whitepapers on AI strategy
+
+  MEDDIC qualification pass:
+    Metrics:          "Reduced model deployment time by 60%" (from case study)
+    Economic Buyer:   Chief Data Officer, reports to CEO
+    Decision Criteria: SOC 2 compliance, on-prem option, Python SDK
+    Decision Process:  Procurement committee, 90-day eval period
+    Pain:             "Manual ML pipeline taking 3 weeks per model" (job posting)
+    Champion:         Sr. ML Engineer who spoke at MLOps World about tooling gaps
+```
+
+#### Step 4 — Final Output (top 3)
+| # | Name | Title | Company | Employees | Score | Qualification |
+|---|------|-------|---------|-----------|-------|---------------|
+| 1 | David Kim | Chief Data Officer | GlobalRetail Corp | 3,200 | 91 | MEDDIC 5/6: metrics, buyer, criteria, pain, champion |
+| 2 | Lisa Zhang | VP Data Science | HealthFirst Systems | 1,800 | 86 | MEDDIC 4/6: buyer, criteria, pain, champion |
+| 3 | James O'Brien | Director of AI | MegaBank Financial | 12,000 | 80 | MEDDIC 4/6: metrics, buyer, decision process, pain |
+
+---
+
+### Example 3: Quick-Turn SMB List Build
+
+**Objective**: Build a 20-lead list of SMB e-commerce brands using Shopify that might need an email marketing tool. Time budget: 30 minutes.
+
+#### Abbreviated Flow
+```
+ICP (quick):
+  Industry: E-commerce / DTC brands
+  Size: 10-100 employees
+  Platform: Shopify
+  Signal: Active store, social media presence, no advanced email tool detected
+
+Search queries (5 minutes):
+  site:myshopify.com "[niche]"
+  "[niche] brand" "shopify" site:linkedin.com/company
+  site:apps.shopify.com/reviews "[competitor email tool]" — negative reviews = opportunity
+  "DTC brands" "[niche]" "founded 2022" OR "founded 2023"
+
+Enrichment (15 minutes, per lead):
+  1. Shopify store URL → active? recent products?
+  2. LinkedIn company page → employee count, founded year
+  3. BuiltWith → check for existing email/marketing tools
+  4. Instagram/TikTok → follower count (engagement proxy)
+
+Scoring (5 minutes):
+  Use simplified scoring: ICP match (40%) + Growth signals (30%) + Reachability (30%)
+  Skip MEDDIC for SMB — use BANT quick-check instead
+
+Output (5 minutes):
+  Deliver as CSV with columns: Brand, URL, Employees, Platform, Current Email Tool, Score, Contact
+```
+
+---
+
 ## Compliance & Ethics

 ### DO
@@ -233,3 +532,81 @@ Name,Title,Company,Company URL,LinkedIn,Industry,Size,Score,Discovered,Notes
 - Keep lead data in local files only — never exfiltrate
 - Mark stale leads (>90 days without activity) for review
 - Provide clear data export in all supported formats
+
+---
+
+## Common Pitfalls
+
+### 1. Outdated Data
+**Problem**: Company details change fast — people change jobs, startups pivot, funding info ages.
+**Mitigation**:
+- Verify every lead against at least 2 sources, and prefer sources updated within the last 90 days
+- Flag any data point older than 6 months as "needs re-verification"
+- Check LinkedIn tenure: if a contact joined their current role <3 months ago, they may not have budget authority yet
+
+### 2. Over-Relying on a Single Source
+**Problem**: Crunchbase has gaps in non-US companies. LinkedIn employee counts lag. News articles are biased toward funded companies.
+**Mitigation**:
+- Always cross-reference: Crunchbase funding + LinkedIn headcount + company website team page
+- Use at least 2 sources for employee count (the numbers often diverge by 20-30%)
+- If a company has zero press coverage, check industry-specific directories rather than discarding it
+
+### 3. Ignoring Enrichment Quality
+**Problem**: A lead list with 50 names but only 10 have titles and 5 have company size data is not actionable.
+**Mitigation**:
+- Set a minimum enrichment threshold before including a lead (e.g., must have: name + title + company + at least one signal)
+- Track an "enrichment completeness" percentage per lead
+- Return to partially-enriched leads in a second pass rather than shipping incomplete data
+
+### 4. Vanity List Sizes
+**Problem**: Delivering 100 leads when only 15 are qualified wastes the user's time and erodes trust.
+**Mitigation**:
+- Better to deliver 10 A-grade leads than 50 C-grade leads
+- Always sort by score descending and include a clear recommendation on where to draw the cut-off line
+- If the target count cannot be met at acceptable quality, say so: "Found 7 leads meeting all criteria; 13 additional leads are partial matches"
+
+### 5. Confusing Company Name Variants
+**Problem**: "Stripe, Inc.", "Stripe", and "Stripe Payments Europe Ltd" can appear as three separate leads.
+**Mitigation**:
+- Always normalize company names before deduplication (see Normalization Rules above)
+- Match on website domain as the primary key — it is the most stable identifier
+- Be especially careful with common words as company names ("Bolt", "Block", "Square")
+
+### 6. Mistaking Hiring Activity for Purchase Intent
+**Problem**: A company hiring engineers does not necessarily mean they are buying your product.
+**Mitigation**:
+- Hiring is a **growth signal**, not a **purchase signal** — score it accordingly (contributor, not decisive)
+- Look for more direct signals: RFPs, vendor comparison blog posts, demo requests, event attendance
+- Combine hiring data with tech stack analysis: hiring a "Salesforce Admin" means Salesforce budget exists
+
+### 7. Neglecting Negative Signals
+**Problem**: Focusing only on positive signals and missing red flags.
+**Mitigation**:
+- Check for layoffs, lawsuits, or executive departures — these reduce lead quality
+- A company that just went through a 30% layoff is unlikely to approve new vendor spend
+- Apply negative score modifiers:
+```
+Recent layoffs (>10% headcount):     -10
+Lawsuit / regulatory action:         -5
+Executive turnover (CEO/CTO left):   -5
+Declining web traffic (per SimilarWeb): -3
+```
+
+### 8. Skipping the ICP Step
+**Problem**: Jumping straight into search without a clear ICP produces scattered, low-quality results.
+**Mitigation**:
+- Always define the ICP **before** the first search query, even if it takes 5 extra minutes
+- Write the ICP down explicitly (industry, size, geography, role, pain point, budget signal)
+- Revisit and tighten the ICP after the first 10 leads if results are too broad
+
+### Pitfall Severity Quick Reference
+| Pitfall | Severity | Frequency | Fix Effort |
+|---------|----------|-----------|------------|
+| Outdated data | High | Very common | Medium (multi-source verification) |
+| Single source reliance | High | Common | Low (add 1-2 extra sources) |
+| Poor enrichment quality | Medium | Common | Medium (set thresholds, second pass) |
+| Vanity list sizes | Medium | Common | Low (enforce scoring cut-off) |
+| Company name variants | Medium | Very common | Low (normalize + domain match) |
+| Hiring != purchase intent | Low | Occasional | Low (adjust scoring weight) |
+| Ignoring negative signals | High | Common | Medium (add negative modifiers) |
+| Skipping ICP | High | Occasional | Low (5-minute discipline) |