gideon-autonomous-prospector

Files (1)

• SKILL.md

SKILL.md (first lines)

# Gideon Autonomous Prospector Skill

## Overview
Interact with Gideon's autonomous prospector system for researching and identifying new prospects across target niches for the AI content repurposing business. The system automatically finds potential clients in real estate, dentistry, coaching, consulting, and other service industries via synthetic prospect generation and simulated outreach.

## System Location
- **Main prospector:** `/Users/pharma6/gideon_ai_business/src/autonomous_prospector.py` — synthetic template-based
- **Fresh prospector:** `/Users/pharma6/gideon_ai_business/src/fresh_prospector.py` — timestamp-unique prospects
- **Automated outreach:** `/Users/pharma6/gideon_ai_business/src/automated_outreach.py`
- **Prospects database:** `/Users/pharma6/gideon_ai_business/prospects/prospects.json`
- **Outreach log:** `/Users/pharma6/gideon_ai_business/prospects/outreach_log.json`
- **Business root:** `/Users/pharma6/gideon_ai_business/`
- **Cron preflight:** `scripts/cron_preflight.py` — canonical audit script (use instead of any old `scripts/preflight.py` path)

## When to Use
- Running prospect research cycles for Gideon's AI content repurposing business
- Analyzing current prospect database and research statistics
- Running in automated/cron contexts (system is designed for scheduled execution)
- Integrating prospect data with outreach or marketing systems

## How to Use

### 1. Run Fresh Prospector (always run first)
```bash
cd /Users/pharma6/gideon_ai_business
python3 src/fresh_prospector.py

# Expected output:
# 🔍 Starting FRESH prospect research at [timestamp]
# ✅ Added [X] FRESH prospects to research database
#    • Fresh Realty Expert {timestamp} (Prime Properties Group {timestamp}) - real_estate
#    • Dr. Fresh Smile {timestamp} (Bright Dental Clinic {timestamp}) - dentists
#    • Coach Fresh Start {timestamp} (Fresh Start Coaching {timestamp}) - coaches
#    • Consultant Fresh Insight {timestamp} (Fresh Insight Consulting {timestamp}) - consultants
#    • Course Creator Fresh {timestamp} (Fresh Learning Academy {timestamp}) - course_creators
```

Generates 5 prospects (one per niche) with HHMMSS timestamp-based unique IDs. Each run creates truly unique entries — email-based dedup prevents duplicates from prior runs.

### 2. Run Automated Outreach
```bash
cd /Users/pharma6/gideon_ai_business
python3 src/automated_outreach.py

# Expected output:
# 🚀 Starting outreach cycle at [timestamp]
# 🎯 Found [X] prospects needing contact
# 📧 EMAIL SENT (SIMULATED): [for each prospect]
# ✅ Sent [type] to [Name] ([email])
# ...
# 📊 Outreach cycle complete:
#    Messages sent: [X]
#    Daily total: [Y]/100
#    Next reset: [date]
```

**Critical behavior to understand:**
- The system processes prospects in **database insertion order** (not priority/scored)
- Max **10 prospects per cycle** — if 10+ earlier prospects need follow-ups, fresh prospects at end of DB won't get initial outreach
- Only **2 follow-up touches** (initial → follow_up_1 → follow_up_2), then the prospect is considered "full cycle"
- Daily cap: **100 messages/day**, tracks via `settings.messages_sent_today` in outreach_log.json
- Currently **simulated emails only** — no real SMTP integration

### 3. Verify Prospect Record Updates (REQUIRED)
Console output showing "email sent" does NOT guarantee the prospect's DB record was updated. You MUST verify.

**Known sync edge case:** ~1/10 records can fail to update. The outreach script logs the send in the outreach log (JSON array) but may not sync back to the prospect record's `outreach_sent`, `last_contact`, or `follow_up_count` fields. This is a known ID-matching fragility in `run_outreach_cycle()` — the sync uses email as join key, but if a prospect record has a duplicate or slightly mismatched email string the match silently fails.

```bash
cd /Users/pharma6/gideon_ai_business

# Check which emails were sent this cycle
python3 -c "
import json
with open('prospects/outreach_log.json') as f:
    log = json.load(f)
recent = log['outreach_sent'][-10:]
for r in recent:
    print(f'{r[\"outreach_type\"]:20s} | {r[\"prospect_name\"]:35s} | {r[\"prospect_email\"]:40s} | {r[\"sent_date\"][:19]}')
"

# Verify prospect records were updated
python3 -c "
import json
with open('prospects/prospects.json') as f:
    data = json.load(f)
# Replace EMAIL_1, EMAIL_2 with actual emails from outreach log
target_emails = ['EMAIL_1', 'EMAIL_2']
for p in data['prospects']:
    if p.get('email') in target_emails:
        print(f\"{p['name']:35s} | outreach_sent={p.get('outreach_sent')} | follow_up={p.get('follow_up_count')} | last_contact={str(p.get('last_contact'))[:30]}\")
"
```

**Outreach log schema** (keys to use in queries):
- `outreach_type` — NOT `type` (e.g., "initial_outreach", "follow_up_1", "follow_up_2")
- `sent_date` — NOT `timestamp`
- `prospect_email`, `prospect_name`, `prospect_id`, `prospect_business`, `prospect_niche`
- `template_used`, `subject`, `status`

```python
# WRONG — returns None silently:
r.get("type")
r.get("timestamp")

# RIGHT:
r.get("outreach_type")
r.get("sent_date")
```

### 4. Pipeline Metrics (Run After Verification)
```bash
cd /Users/pharma6/gideon_ai_business && python3 -c "
import json
with open('prospects/prospects.json') as f:
    data = json.load(f)
not_sent = [p for p in data['prospects'] if p.get('outreach_sent') != True]
sent = [p for p in data['prospects'] if p.get('outreach_sent') == True]
follow_ups_due = sum(1 for p in sent if p.get('follow_up_count', 0) < 2 and p.get('last_contact'))

From percymcn/agent-cookbook, MIT.

More from percymcn/agent-cookbook