Bear's Onboarding Package

01The mission

Frame this before you write a line of code.

You own the Deals page. The mission is bigger than your first feature. The Deals page today is a working tool. Mark uses it. John checks it. Ewing references it. It functions.

Where it goes from here: a B2B CRM automation engine that lets Mark, Ewing, and John each cover 5x as many deals at the same quality. That is the goal. Five times the deal coverage with no drop in close rate, no drop in seller satisfaction, no drop in buyer trust.

That goal does not happen with one feature. It happens with a system of features that talk to each other. Each one a loop. Each one feeding the next. The Pipeline Health Snapshot is the first loop you will build. It is the entry point, not the finish line.

02What you're building

The Pipeline Health Snapshot. Concrete spec.

A daily computed view at /deals/health. Read only. No admin tier needed. No paid API calls. Lives entirely on data we already have. The page surfaces what needs attention so Mark does not have to scan the whole pipeline manually every morning.

Five metrics, each one a card on the page:

That is the whole feature. Five cards. One page. No mutations. No external API calls. No new tables.

03The data you'll touch

Read these tables. Memorize the columns you'll use. Don't guess.

Tables in play

Stage names you need to know

Read src/lib/deals.ts for the canonical list. The ones that matter for this build:

• prospect, qualified, diligence, loi_submitted, under_loi, closed_won, closed_lost, dead
• Terminal stages (don't count as stalled): closed_won, closed_lost, dead
• "Past qualified" for the missing EBITDA check means stage is anything except prospect or qualified itself. So diligence and beyond.
• "Past loi_submitted" for the missing EV check means loi_submitted, under_loi, or beyond.

04The feature def

No code gets written before this is registered.

Add this to src/lib/features/defs/deals.ts:

{
  key: 'deals.health-snapshot',
  page: 'deals',
  tier: 'intern',
  status: 'design',
  title: 'Pipeline Health Snapshot',
  description: 'Daily computed view of stalled deals, missing financials, warm leads awaiting review, weighted forecast change WoW, and top 3 deals by weighted value.',
  owner: 'bear',
  consumes: ['deals', 'deal_stage_history', 'meeting_notes'],
  produces: ['feature_metrics:deals.health-snapshot.viewed'],
  paidApis: [],
}

Status flow: design while you're planning, build the moment you write the first file, test when the page renders end to end on your machine, live after Mark and Ewing have each clicked through it once and you've shipped any feedback.

Do NOT skip the design stage. Even if the build takes 90 minutes total, the registration is part of the build. The feature registry is how the system knows what exists.

05The API route

All data goes through API routes. Never query Supabase from the page directly.

Path: src/app/api/deals/health/route.ts. Method: GET. The shape:

import { NextResponse } from 'next/server';
import { getIdentity } from '@/lib/identity';
import { canUseKey } from '@/lib/features/permissions';
import { recordMetric } from '@/lib/features/metrics';
import { supabaseAdmin } from '@/lib/supabase';

export async function GET() {
  const actor = await getIdentity();
  if (!canUseKey('deals.health-snapshot', actor)) {
    return NextResponse.json({ error: 'forbidden' }, { status: 403 });
  }

  const fourteenDaysAgo = new Date(Date.now() - 14 * 86400 * 1000).toISOString();

  const [stalled, missingEbitda, missingEv, warmLeads, liveDeals] = await Promise.all([
    supabaseAdmin
      .from('deals')
      .select('id, company_id, stage, stage_entered_at, ev, fee_pct, win_prob_pct')
      .lt('stage_entered_at', fourteenDaysAgo)
      .not('stage', 'in', '(closed_won,closed_lost,dead)'),
    supabaseAdmin
      .from('deals')
      .select('id, company_id, stage, ebitda')
      .is('ebitda', null)
      .not('stage', 'in', '(prospect,qualified,closed_won,closed_lost,dead)'),
    supabaseAdmin
      .from('deals')
      .select('id, company_id, stage, ev')
      .is('ev', null)
      .in('stage', ['loi_submitted', 'under_loi']),
    supabaseAdmin
      .from('meeting_notes')
      .select('id, company_id, classification, created_at')
      .eq('classification', 'deal')
      .is('promoted_to_deal_id', null)
      .order('created_at', { ascending: false }),
    supabaseAdmin
      .from('deals')
      .select('id, company_id, ev, fee_pct, win_prob_pct, updated_at')
      .not('stage', 'in', '(closed_won,closed_lost,dead)'),
  ]);

  // weighted forecast computation goes here
  // top 3 by weighted value goes here
  // WoW delta computed from updated_at history or a snapshot table

  await recordMetric('deals.health-snapshot.viewed', actor);

  return NextResponse.json({
    stalled: stalled.data ?? [],
    missingEbitda: missingEbitda.data ?? [],
    missingEv: missingEv.data ?? [],
    warmLeads: warmLeads.data ?? [],
    weightedForecast: { thisWeek: 0, lastWeek: 0, deltaUsd: 0, deltaPct: 0 },
    topThree: [],
  });
}

The pattern: identity, gate, parallel queries, compute, record metric, return JSON. Every API route on the deals page follows this shape. Read three or four existing ones in src/app/api/deals/ before you write yours so the style matches.

06The page

Server component. Renders five cards. That's it.

Path: src/app/deals/health/page.tsx. Server component. Fetches from your API or calls the same logic directly. Renders five cards with the metrics from above.

Layout sketch:

• Top: page header with the timestamp of the snapshot ("as of 7:14 AM, May 6")
• Row 1: Weighted forecast WoW (big number, delta in green or red)
• Row 2: Two cards side by side: Stalled deals count + Warm leads awaiting review count. Click either to see the list.
• Row 3: Missing financials card. Two subgroups: missing EBITDA past qualified, missing EV at LOI.
• Row 4: Top 3 by weighted value. Each one shows company, stage, EV, weighted dollar number.
• Bottom: FeedbackBox component. Mark and Ewing leave one liner notes here. You read them tomorrow.

Match the visual style of the existing deals pages. Look at src/app/deals/page.tsx and copy the card patterns. Don't invent new components. Use the ones already there.

07Definition of done

Concrete checklist. Don't say done before all six pass.

1. npx tsc --noEmit passes with zero errors.
2. npm run build completes without warnings related to your files.
3. Hit /deals/health in dev. Page renders. No console errors. No empty page on missing data, no crash on null fields.
4. All five metrics visible. Numbers match what you can verify with a manual SQL query.
5. FeedbackBox component is present and posts to the existing feedback endpoint when you type into it.
6. Query feature_metrics after viewing the page. There should be a row with action = 'deals.health-snapshot.viewed' and the right actor.

If any one of these fails, you are not done. Fix it. Don't ship a half feature and call it 80% done.

08How to demo it

Show, don't tell.

When the page works, do not write Mark a paragraph about what you built. Do one of these:

1. Send a 90 second Loom. Open the page. Walk through each card. Say what each one means in your own words. Tell Mark what you want him to look for.
2. Pull it up live in your next 1:1. Share screen. Click around. Watch where his eyes go. Watch where he hesitates. Note both.

Do not send a screenshot with no context. Do not send "let me know what you think." Send something specific:

09Skills for this build

Five skills you'll lean on. Invoke them by typing /skill-name.

10What ships next

The Health Snapshot is the foundation. Five features build on it. Each one is its own loop.

1. Deal scoring. A computed score per deal: weighted forecast, stage velocity, financial completeness, days since last activity. The Health Snapshot becomes a leaderboard, not a list.
2. Weekly digest emails to experts. Every Monday morning, John and Mark get an email summarizing what the Health Snapshot says: stalled deals they own, weighted forecast delta, top 3 to focus on this week. Built from the same API.
3. Stage skip alerts. If a deal jumps from prospect to loi_submitted without passing through diligence, that's worth a flag. Watch deal_stage_history and ping Slack.
4. Salesfinity contact sync. Every contact tied to an active deal gets pushed into a Salesfinity list automatically. When the deal advances, the list assignment updates. Less manual list building for Mark.
5. Stage advancement gates. Promote to diligence requires EBITDA. Promote to loi_submitted requires EV. The system blocks the bad transition and creates a task instead. The Health Snapshot then becomes redundant for missing financials, because they cannot exist anymore.

Notice the pattern: each feature consumes data the previous one created. Each one tightens the system. By the time you ship feature 5, Mark and John are not scanning the pipeline at all. The pipeline tells them what to do.

That is the 5x deal coverage path. Not magic. Not AI hype. A series of small loops where each one removes one thing humans had to track in their head.

Goal of this session

Understand what discipline looks like across years of running a pipeline that works. John has seen pipelines that close deals and pipelines that die. You want his pattern recognition.

What to verify before the call

• Read src/lib/deals.ts end to end. Know every stage and transition.
• Open the current Deals page. Click into 3 active deals. Understand what fields are populated.
• Read the most recent 5 entries in deal_stage_history for one closed deal. See the rhythm.
• Skim the /buyside-hunt skill. John built that discipline.
• Have your Health Snapshot pulled up live so you can show it.

Question bank

1. "When you look at the pipeline first thing in the morning, what do you look at FIRST? What's the first number, the first list, the first deal you open?"
2. "What does an amazing pipeline page look like to you? Walk me through the page we have for 5 minutes and give rapid feedback on what's missing or what's noise."
3. "What do you want to know about a deal that has already happened in the past? How do you want it summarized and displayed when you go back to it?"
4. "How should I prioritize which deals get worked on in which order? Is there a measurement system that should auto prioritize, with manual override for situational focus?"
5. "How do you want to search and interact with a deal: on this page, in Slack, in your inbox, somewhere else, or all of the above?"
6. "What kinds of questions would you ask about a deal that's currently in flight? Walk me through the questions you ask Mark in a sync."
7. "Tell me about a deal that died because of bad data, bad timing, or a bad handoff. What was the signal we missed?"
8. "Tell me about a deal that closed because something worked perfectly. What made the difference?"
9. "Where would you never trust software to make the call? What part of this job is irreducibly human?"
10. "If you were running this pipeline ten years ago with paper and a phone, what would you have wanted to know that I could surface on this page now?"
11. "What's a stage transition that's actually two transitions in one? Where does the system flatten something that has nuance?"
12. "If I built one thing for you in the next two weeks, what would you want it to be?"

Goal of this session

Understand the operational reality of touching deals daily. Mark knows where the friction is because he hits it every hour. Your job is to find the friction he has stopped noticing.

What to verify before the call

• Look at Mark's last 7 days of deal_stage_history entries. What's he actually moving?
• Check his recent activity in feature_metrics. Which features does he use the most?
• Read the most recent 5 of his feedback box entries if any exist on the deals page.
• Have your Health Snapshot pulled up live.

Question bank

1. "Walk me through 7am, 10am, 3pm. What do you actually DO with deals at each point? What's open on your screen?"
2. "When financials change on a deal (EV moves, EBITDA gets revised), what does that signal to you? What do you do next?"
3. "What deal stage is the most dangerous? Where do deals get stuck or die quietly?"
4. "When do you decide a deal is dead? What's the signal that tips you from 'stalled' to 'gone'?"
5. "What do you wish the deals page did that it doesn't? Specific. Not 'it should be smarter.' What button is missing?"
6. "If I built one feature for you in the next two weeks, what would it be? If you say 'I don't know,' what would you build to save yourself 30 minutes a day?"
7. "How do you remember what a deal needs next? Is it on the page, in your head, in your inbox, in a sticky note?"
8. "What's the worst kind of busywork you do every day around deals? Where are you copying data from one place to another?"
9. "When you open a deal you haven't looked at in a week, what's the first thing you want to see? Is it on the page now?"
10. "How do you know when Mark needs to call John or Ewing about a deal? What's the threshold?"
11. "What's a notification you would actually want to get versus the ones you would mute immediately?"

Goal of this session

Understand the vision. Where does the deals page go? What does Ewing dream of having on it? What's the 12 month picture you're building toward?

What to verify before the call

• Read this entire onboarding doc and the shared briefing. Don't ask anything that's already answered there.
• Read CLAUDE.md and the Intern Rules section.
• Have your Health Snapshot pulled up live AND have the "what ships next" list from section 10 ready to discuss.
• Know which paid APIs are gated by circuit-breaker.ts and what the daily caps are.

Question bank

1. "If you had to cover 5x as many deals next year at the same quality, what would the deals page have to do that it doesn't today?"
2. "Would you rather have 800 leads to call that cost $0.01 each in total but 250 are wasted, OR 131 leads at $0.30 each where every one answers their cell phone with company fit 80%+ verified in advance?"
3. "How should I think about getting the most out of Clay's capabilities for this project? What about Exa or Hermes? Where does each one shine?"
4. "What's a feature you've wanted on the deals page for months but haven't built? What's stopped it?"
5. "Where is human judgment irreducible on a deal? What should never be automated, even if I could?"
6. "How do you want me to learn from Mark and John without bothering them every day? What's the rhythm you want me on?"
7. "What does mastery on this page look like in 3 months? In 6 months? What would I be doing differently?"
8. "What's a metric that would tell you the deals page is actually working as a system, not just as a UI?"
9. "When a feature I build is wrong, how do you want me to find out? Slack ping, ticket, weekly review, all three?"
10. "If I asked you in a year 'what was the single best thing Bear shipped on the deals page,' what would you want the answer to be?"

14Writeup template

Within 24 hours of every session, fill this out and save it. Same format for all three.

Session: Bear : <expert>
Date: <date>
Goal stated: <what I told them at the start>

Three themes that came up:
1.
2.
3.

One thing that surprised me:

One thing they want but didn't say (my interpretation):

Three feature ideas that came out of this:
1.
2.
3.

What I'm doing in the next 7 days based on this:

Save each writeup as a file in your notebook directory or paste it into a Slack canvas thread for the deals workstream. Ewing reads these. They are how he knows what you heard versus what was actually said.

15Your requirements (live)

Pulled from your Fireflies transcripts of the John, Mark, and Ewing sessions, then consolidated into a build queue. Click any field to edit. Edits save on blur.

Calendar invite title pattern: Bear & John discuss Deals Page for System Requirements Gathering. Match this exactly so the auto-extractor knows to pull from the transcript.

15Quick reference

Pin this tab.

Files for the build

Tables for the build

Skills for the build

/deal-awareness-protocol, /data-architect, /audit-quality, /architect, /auto-fix

Sessions checklist

• Bear : John, goal stated, system open, writeup within 24 hours
• Bear : Mark, goal stated, system open, writeup within 24 hours
• Bear : Ewing, goal stated, Health Snapshot demoed live, writeup within 24 hours

Now go build.