debrief

Debrief

Session status and end procedures — loads system state, summarizes progress, and persists session data.

Data directory: ~/.talent-scout/

Critical rules:

• Commit to git after every session — data is local JSON, if lost it's gone.
• Dashboard is a command center — verdicts and queued requests flow from it; debrief reflects state but does not mutate it (mutations happen via verdicts in the dashboard or via skills invoked from chat).

Modes

Standalone Mode

Triggered by "what's the status" or "debrief." Runs full state loading below. Presents summary. Does NOT execute pipeline work.

Session-End Mode

Called by orchestrator at session close. Receives action log. Writes session log and commits to git. (Dashboard v2 reads data live — no regeneration step needed.)

---

Session Start Procedure (Standalone Mode)

Step 1: Load Pending Actions and Journal

Call in parallel:

• read_meta with name "session_log.json" — extract pending_actions and latest_session
• read_journal — cross-session observations, vector notes, candidate threads, session reflections

The journal provides analytical context beyond the structured session log — pattern observations, vector yield notes, and evolving candidate narratives that inform the status summary.

Step 2: Load API Budget

Call get_usage.

Step 3: Load Search Vector Coverage

Call read_meta with name "searches.json" → vectors.

Step 4: Load Candidates Index

Call read_meta with name "candidates_index.json". Extract tier/stage breakdowns and candidate count.

Step 5: Load Dashboard Queue

Call read_meta with name "dashboard_queue.json". Filter to items with status: "pending" or status: "in_progress". These are user requests submitted from the dashboard that haven't been picked up yet — surface them in the summary so the user can see what's in flight without starting a session. If read_meta returns no file or the filtered list is empty, skip this section entirely (don't render an empty header).

Step 6: Cross-session pattern analysis

Use the session_log data loaded in Step 1 and the journal observations/vector-notes. Only run structured session_log analysis if the log contains 3+ sessions, but always surface relevant journal observations regardless of session count — the journal captures qualitative insights that the structured log misses.

Compute and surface max 3 findings:

1. Vector yield: candidates_added / sessions_run per vector. Yield > 1.5 = high-signal. Yield < 0.5 across 3+ sessions = candidate for disabling.

2. Tier concentration: Last 10 sessions — are T1s clustering around a specific company, vector, or archetype? 60%+ from one source = either a rich seam or a blind spot.

3. Deep-dive conversion rate: Of T1/T2 candidates assessed in the last 5 sessions, what % were actually deep-dived? Rate < 50% suggests T1/T2 threshold may be too loose.

4. Timing window aging: T1/T2 candidates with a why_now signal older than 60 days without outreach. Name them — windows may be closing.

Format: "Pattern: [finding]. Implication: [what to do about it]."

Step 7: Check Rubric Staleness

Call read_meta with name "rubric.md" → extract version from YAML frontmatter. Find stale candidates.

Inbox Check

If candidates in contacted stage exist:

1. Check LinkedIn inbox via Playwright (see docs/linkdapi-reference.md for interaction patterns).
2. Cross-reference replies against contacted candidates.
3. For replies: update stage contacted → replied, add to outreach array. Surface immediately.

Present Summary

"Last session we [actions]. Pending: [pending_actions].
We have [N] candidates ([T1] Tier 1, [T2] Tier 2, [T3] Tier 3).
API credits: [N] spent lifetime, [N] today.

Pending requests from dashboard:
  - Deep-dive: <candidate_name> (queued <date>)
  - Expand: <candidate_name>'s network (queued <date>)
  - Scout: <free-text instruction> (queued <date>)

[Staleness flags, inbox replies, index discrepancies]."

The "Pending requests from dashboard" block renders only when Step 5 returned one or more pending/in_progress items. Format each item by kind: deep_dive → "Deep-dive: <candidate_name>", expand → "Expand: <candidate_name>'s network", scout → "Scout: ". Append (queued <date>) from the item's created_at (date only, no time). If there are no pending items, omit the entire block including the header — never render an empty section. These are forward-looking ("what's about to run") and belong before staleness/reply flags ("what already happened").

---

Session End Procedure

Step 1: Write Session Summary

Call save_session with the session id, type, budget, actions, candidates_added, tier_breakdown, and pending_actions.

Note: The candidates index is auto-maintained on every candidate write — no rebuild_index call needed. The index is already current by session end.

Step 2: Git Commit

cd ~/.talent-scout && git add -A && git commit -m "session: [brief summary]"

Step 3: Start Dashboard

Start the dashboard server so the user can review results visually.

bash ${CLAUDE_PLUGIN_ROOT}/dashboard/start-dashboard.sh

The script is idempotent — it skips if the server is already running.

Step 4: Surface Next-Session Notes

• Pending actions requiring user input
• Candidates approaching outreach staleness (14+ days contacted, no reply)
• Budget observations
• Search vector recommendations

---

Stage Reference

Stages:
- new        — ingested, not yet assessed (transient)
- reviewed   — assessed and tiered (T1/T2/T3 filter by tier)
- researched — deep-dive completed
- contacted  — outreach sent
- replied    — candidate responded
- archived   — not pursuing

Typical progression: new → reviewed → researched → contacted → replied. Reviewed-to-contacted is allowed (outreach without a deep-dive). Any stage can transition to archived. Tier 1 and Tier 2 are deep-dive-eligible by default; Tier 3 stays at reviewed unless explicitly promoted. Draft outreach is tracked in outreach_status, not as its own stage.