Bear is the intern who owns the Deals page at /deals. His job is to watch the pipeline, keep financials current, spot stale deals, and give feedback to Charlie about lead quality. He does not come from a finance background, so this guide explains every concept he will encounter on the page, then walks through his daily routine grounded in the actual code.
Code grounding: All findings below trace to src/lib/deals.ts, src/app/deals/page.tsx, src/app/deals/DealsDashboard.tsx, src/components/deals/warm-leads-table.tsx, src/components/deals/promote-modal.tsx, src/lib/handoff.ts, and src/lib/features/defs/deals.ts.
S2: Finding 1
How a deal is born Charlie classifies meetings. When a meeting has a revenue signal, an opportunity score of 30 or higher, a linked entity, and at least one optional signal (motivated seller, buyer signal, meeting set, or info requested), the system marks it promotable. If the score is 50 or above, the promotion is automatic. Below 50, it goes into the review queue.
On the Deals page, these promotable meetings show up in the Warm Leads table at the bottom. Bear clicks Promote to open a modal, confirms the deal name and estimated EV, and the system creates the deal at stage worth_chasing.
Evidence: handoff.ts lines 45 to 69 define isPromotable() and promotionDecision(). The handoff payload sets stage: 'worth_chasing' and win_prob_pct at creation. promote-modal.tsx sends a POST to /api/deals/promote-from-meeting.
Stage progression The code defines these stages in order:
#Stage keyDisplay labelWhat happens here 1worth_chasingWorth ChasingDeal created from meeting promotion. Default financials applied (EV estimate, 4% fee). Win probability starts at 65% for active deals in the forecast. 2first_meeting1st MeetingFirst formal meeting with the prospect. Validate the revenue signal. Start refining EBITDA estimate. 3proposal_sentProposal SentEngagement letter delivered. Engagement fee amount should be populated by now. 4signed_contractSigned ContractClient signs. Engagement fee should be paid. Fee percentage confirmed. 5hunt_launchedHunt LaunchedActive buyside or sellside search is running. EBITDA, multiple, and EV should all be populated. Contact count grows. 6aclosed_wonClosed (Won)Deal completed. closed_at timestamp set automatically by transitionStage(). 6bclosed_lostClosed (Lost)Deal died. closed_at timestamp set. Moves to the closed section on the dashboard.
Evidence: deals.ts lines 7 to 15 define DEAL_STAGES. The transitionStage() function (lines 99 to 136) reads the current stage, writes the new stage, sets closed_at for terminal stages, inserts into deal_stage_history, and logs to deal_activity_log.
What data gets set at each stage
FieldWhen to populate EV estimateAt creation (default $3.5M). Refine by first_meeting. EBITDABy first_meeting or proposal_sent when the seller shares financials. Industry multipleBy proposal_sent. Research comparable transactions. Fee %Confirmed at signed_contract. Defaults to 4%. Engagement feePopulated at proposal_sent. Default assumption is $15K. Win probabilityStarts at 65%. Adjust based on evidence as the deal progresses. ContactsShould grow through hunt_launched. Pulled from Fireflies sync or manual add.
Permission note: Bear can view the pipeline and warm leads (tier: intern). He cannot edit financials or change deal stages. Those features require admin tier (Ewing only). See src/lib/features/defs/deals.ts, where deals.edit-financials and deals.change-stage are both tier admin.
S3: Finding 2
Step 1: Open the pipeline Navigate to /deals. The page loads two headline cards at the top:
Active Deal Revenue Forecast (green card): Sum of (EV x fee% + engagement fee) x 65% across all active deals. Warm Leads Revenue Forecast (blue card): Sum of expected revenue from meetings classified as deals but not yet promoted, using 40% win rate and default assumptions ($1M EBITDA, 3.5x multiple, 4% fee, $15K engagement).
Step 2: Review the KPI strip Six numbers across the top of the dashboard:
Weighted Pipeline: sum of weighted_fee_usd across active deals. Total Fee Potential: sum of success_fee_usd. Engagement Fees: paid vs. owed. Active Deals: count of deals not in a closed stage. Buyers Identified: contact count on sell side deals. Contacts: total contacts across all active deals.
Evidence: DealsDashboard.tsx lines 382 to 398 compute these KPIs from the activeDeals array.
Step 3: Check warm leads from Charlie Scroll to the Warm Leads (from Meetings) section. Each row shows a meeting that Charlie classified as deal but that has not been promoted yet. The table shows default financial assumptions. Click Promote to open the modal, confirm the deal name and EV, then submit.
Step 4: Monitor deal health Click into any deal card to enter the war room (/deals/[slug]). Check:
The Activity section: shows stage changes, notes, and system events with timestamps. The Plays card: outreach channels and scripts attached to the deal. The People sub page: contacts linked to the deal. The Meetings strip: recent meetings tied to this project.
Step 5: Flag stale deals A deal with no activity entry for 14 days is stale. The last_activity_at field on DealPipelineRow tracks this.
Gap: There is no automated stale deal detection or visual warning in the current UI. The last_activity_at column exists on the v_deal_pipeline view but the dashboard does not highlight deals older than 14 days. Bear must check manually for now.
Step 6: Log activity On the deal detail page, use the FeedbackBox at the bottom to add notes. These go into deal_activity_log.
S4: Finding 3
What works today
The deal pipeline dashboard is live with inline editing, KPI strip, and card grid. Warm leads flow from Charlie's meeting classification to the Warm Leads table. The promote modal creates deals at worth_chasing through a validated API route. The handoff system (handoff.ts) validates promotion candidates and logs to activity + Slack. Deal detail pages show activity history, plays, contacts, and meeting strips. Financial recalculation (EBITDA x multiple = EV, cascading to fees) works client side.
Gaps to address
GapImpactSuggested fix No stale deal highlightingDeals drift without anyone noticing. Revenue at risk.Add a visual indicator (red border or badge) on deal cards where last_activity_at is older than 14 days. No reject/flag action on warm leadsCharlie gets no feedback on bad leads. Classification does not improve.Add a "Not a deal" button next to Promote that logs a reason and marks the meeting accordingly. Bear cannot edit financials or change stagesHe can monitor but not act. Every financial update requires Ewing.Evaluate whether Bear should get operator tier for specific fields (engagement fee paid, win probability) while keeping EV and stage changes at admin. No automated financial completeness checkDeals advance stages with empty fields. Forecast accuracy degrades.Add a quality gate: warn when advancing past proposal_sent without EBITDA, multiple, and fee% populated.
Bear's permission boundaries (from feature defs)
FeatureTierBear can use? deals.view-pipelineinternYes deals.view-detailinternYes deals.view-warm-leadsinternYes deals.edit-financialsadminNo deals.change-stageadminNo deals.sync-contactsoperatorNo
Bear's effective role today is pipeline observer and lead reviewer. He sees everything but edits nothing. For him to become a full pipeline manager, his tier needs to expand for at least the financial editing and contact sync features.
Generated from 018__deal-awareness-protocol.md — do not edit this HTML directly.