Outreach Pipeline — Design Spec (Step 9)

Source: plans/pipeline-9-outreach-design.md · synced 2026-06-12

Date: 2026-06-11 Covers steps: 9.1 (Personalisation engine) · 9.2 (Email send) · 9.3 (LinkedIn sequencing) · 9.4 (Response handling) Status: Draft — awaiting greenlight. Depends on: ✅ Step 8.1 verdict synthesis (Strong yes + Soft yes flow here). ⏳ Step 5.0 candidate-merge (CandidateRecord carries the email + LinkedIn URL this pipeline writes to). ⏳ Calibre brand-voice / tone guide reference for prompt templates. Grant mapping: Annex 3 Deliverable AD3 — “AI-Driven Candidate Outreach”. See grant/scope.md §“AI-Driven Candidate Outreach”.

1. Context

Step 8.1 emits a shortlist verdict per (JD, candidate) pair. Strong yes + Soft yes flow downstream to outreach. Step 9 turns each shortlisted candidate into a personalised, multi-channel message sequence and captures responses back into the candidate database.

Four sub-steps:

• 9.1 Personalisation — LLM generates per-candidate email subject + body + LinkedIn message body grounded in (NormalisedJD, CandidateRecord, MatchRecord) evidence.
• 9.2 Email send — Outbound delivery via Instantly or Smartlead (deliverability + tracking).
• 9.3 LinkedIn sequencing — Connection request → wait → InMail → follow-up. Tool TBD (LinkedHelper / Phantombuster / manual queue).
• 9.4 Response handling — Webhook listeners auto-tag candidate records on signal (opened, replied, deferred, declined, unreachable). Feeds re-pool logic for parked candidates.

2. Architectural Decisions

3. End-to-End Flow

Step 8.1 Shortlist (Strong yes + Soft yes)
   │
   ▼
9.1 Personalise ─→ EmailDraft + LinkedInDraft (per candidate)
   │
   ▼ (recruiter approve / edit / skip)
   ▼
9.2 Email send via Instantly|Smartlead ─→ delivered, opened, clicked
   │
   ▼ (48h gap if no response)
   ▼
9.3 LinkedIn — connect → InMail → follow-up
   │
   ▼
9.4 Response handler — webhook → signal taxonomy → CandidateRecord enrichment
   │
   ▼
Re-pool decision (deferred → 90d wait; declined → permanent)

4. Sub-step Specs

9.1 — Personalisation engine

Input: (NormalisedJD, CandidateRecord, MatchRecord) per shortlisted candidate. MatchRecord carries Step 7.2 evidence quotes (which CV passages won which rubric dimension).

Output:

interface OutreachDraft {
  candidate_id: string;
  jd_id: string;
  email_subject: string;       // ≤ 60 chars
  email_body: string;          // ≤ 180 words, evidence-cited
  linkedin_connect_note: string; // ≤ 300 chars, LinkedIn's limit
  linkedin_inmail_body: string;  // ≤ 1900 chars
  template_version: string;    // for audit replay
  llm_prompt_hash: string;     // SHA256 of the prompt that generated this draft
  evidence_anchors: string[];  // verbatim CV quotes the email references
  generated_at: string;
  status: "drafted" | "approved" | "edited" | "skipped" | "sent";
}

LLM: Claude tool-use call per shortlisted candidate.

Code target: calibre-app/src/lib/outreach/personalisation.ts.

9.2 — Email send

Input: OutreachDraft[] with status: "approved" or "edited".

Tool decision pending — Instantly vs Smartlead. Both support webhook-style delivery callbacks.

Output: EmailSendRecord[] — one per dispatched email with (message_id, delivered, opened, clicked, bounced, replied) state stream.

Code target: calibre-app/src/lib/outreach/email-send.ts.

Warm-up + domain rotation: per-tenant config. Calibre’s existing domain is already warm.

9.3 — LinkedIn sequencing

Input: OutreachDraft[] where the candidate hasn’t replied to email within 48h.

Tool decision pending — LinkedHelper / Phantombuster / Calibre-managed manual queue.

Cadence:

1. Send linkedin_connect_note (connection request).
2. Wait 72h for accept.
3. If accepted: send linkedin_inmail_body.
4. Wait 7d for response.
5. If no response: one follow-up (50-word, short).
6. Stop.

Output: LinkedInTouchRecord[] — (touch_number, sent_at, response_received_at, response_kind).

Code target: calibre-app/src/lib/outreach/linkedin-sequence.ts.

9.4 — Response handling

Input: Webhook callbacks from email tool + LinkedIn tool.

Signal taxonomy:

Code target: calibre-app/src/lib/outreach/response-handler.ts.

LLM classifier: light tool-use call per inbound reply — (reply_text) → signal.

5. Implementation Plan (separate file pending greenlight)

plans/pipeline-outreach-impl.md. Outline:

6. Cost + Risk

Risk: LinkedIn ToS. All third-party LinkedIn automation tools violate ToS. Mitigation: per-tenant warm-up + low daily caps + fallback to Calibre-managed manual queue if account flagged.

Risk: Deliverability. Cold-email open rates depend on domain warm-up. Mitigation: use Calibre’s warm domain for tenant 1; new tenants get warm-up guidance + cost transparency.

7. Dependencies

• Step 8.1 must ship before Step 9 has shortlists to consume.
• Step 5.0 ships CandidateRecord.primary_email + linkedin_url — the addressing fields.
• Step 7.2 ships verbatim CV quotes — the evidence anchors for personalisation.
• reference/verticals/ §“Outreach tone notes” — domain content Daniel + Jon need to ratify.

8. Greenlight Checklist for Ben

• Approve email-first / LinkedIn-second cadence (48h gap)
• Decide: Instantly vs Smartlead for 9.2
• Decide: LinkedHelper / Phantombuster / manual queue for 9.3
• Approve 5-signal response taxonomy + re-pool logic
• Authorise impl plan draft (pipeline-outreach-impl.md)
• Schedule Calibre team session to populate per-vertical tone-guide content