Sales CRM & RFP

What progress is a construction sales team trying to make when they open their CRM at 7am?

Pitch-Prompt Deck​

Five cards. Five headlines. Five pictures. The meme layer — 80 cents in the dollar.

Demand-Side Jobs​

Every feature exists because someone is struggling to make progress. No struggle, no feature. These are the jobs — verified by watching what construction sales teams actually do, not what they say they want.

Job 1: Know Who I'm Dealing With​

Situation: A BD manager prepares for a meeting tomorrow with a client they haven't spoken to in 3 months. They need to know: who else from their company is involved, what deals are active, what the last conversation was about.

Features that serve this job:

• Contact CRUD with company linking
• Contact detail page showing all linked entities (deals, ventures, activities)
• Activity timeline per contact (calls, emails, meetings, site visits)
• Company page showing all contacts and all deals
• Search by name, email, company, or tag
• CSV import for bulk onboarding
• Contact status (active/inactive) and tagging

Job 2: See Where Every Deal Stands​

Situation: Monday morning. A sales director needs to know: which deals are moving, which are stalled, which need action this week, and what the pipeline is worth.

Features that serve this job:

• Deal pipeline with visual kanban (drag-drop between stages)
• Deal stages: Lead, Qualified, Proposal, Negotiation, Won, Lost
• Deal value, probability, expected close date
• Cards/Table/Kanban view toggle
• Pipeline summary (total value, weighted value, deal count per stage)
• Dashboard with pipeline health, overdue activities, upcoming deadlines
• Monthly goals tracking (pipeline value, won revenue)

Job 3: Win More Bids, Waste Less Time​

Situation: An RFP lands. The team has 3 weeks to respond. Half the questions have been answered before in previous bids, but nobody can find those answers.

Features that serve this job:

• RFP venture creation with description, tags, industry
• Venture kanban: Discovery, Qualification, Preparation, Review, Submitted
• Document upload (PDF, DOCX, TXT — max 16MB)
• AI-powered answer auto-fill from approved library
• Answer Library with confidence scoring
• Review Queue for SME approval workflow
• My Queue for personal review assignments
• Analytics dashboard (auto-fill rate, time saved, cost saved per RFP)

Job 4: Never Let a Follow-Up Fall Through​

Situation: A site visit happened last Tuesday. Three action items came out of it. By Friday, one has been forgotten, one is assigned to someone who doesn't know about it, and one is waiting on a document nobody has sent.

Features that serve this job:

• Task creation with title, description, due date, priority
• Task linking to contacts, deals, ventures
• Task status: Not Started, In Progress, Completed
• Overdue task highlighting
• Calendar view for deadlines and follow-ups

Job 5: Link People, Places, and Projects​

Situation: A solar installation project involves a property owner, an EPC contractor, two subcontractors, and a financier. The project ties to a specific warehouse address. Three separate bids have been submitted over 18 months as the scope changed.

Features that serve this job:

• Venture entity linking property + companies + deals + contacts
• Multi-company deals with roles (Client, JV Partner, Subcontractor, Consultant)
• Property registry with address, GPS, site type, status
• Venture-to-deal relationship (multiple bids per project)
• Activity logging against any entity (contact, deal, venture, property)

Awareness Levels​

Where the buyer sits determines what we build next.

Validation Stack​

Kill signal: If users create contacts but never create deals, the CRM is a rolodex, not a sales tool. Deal creation is the activation metric.

Domain Model​

CONTACTS ←→ COMPANIES
    ↕            ↕
VENTURES ←→ DEALS (Bids)
    ↕            ↕
PROPERTIES   DOCUMENTS

Relationships​

RFP Workflow​

The tender cycle is the heartbeat of construction sales.

TENDER NOTICE
    ↓
GO/NO-GO DECISION (scored checklist)
    ↓
BID PREPARATION (document assembly, pricing, team allocation)
    ↓
SUBMISSION (version-locked, timestamped)
    ↓
EVALUATION PERIOD (track questions, site visits, presentations)
    ↓
AWARD / LOSS (win/loss analysis, feedback capture)
    ↓
HANDOVER TO DELIVERY (venture transitions to In Progress)

Go/No-Go Checklist​

Every RFP runs through a qualification gate before committing resources.

Score: 70%+ = Go. 50-70% = Review. Below 50% = No-Go.

Competitive Position​

The gap: Generic CRMs can be configured for construction. None are designed for it. Configuration tax compounds — every new hire needs setup, every report needs custom fields, every integration needs mapping.

Feature / Function / Outcome​

Every row maps a feature to the function it performs, the outcome the user experiences, the job it serves, and delivery state. Reviewed 2026-02-18.

Delivery Summary​

Success Criteria​

Functional​

Non-Functional​

Business Dev​

This PRD wins only if it closes the loop from operations pain to recurring revenue.

Pilot Proof Pack​

Each pilot must produce:

1. Before/after bid cycle time.
2. Auto-fill percentage with quality acceptance rate.
3. Deal progression and revenue impact.
4. User quote from sales lead or bid manager.

Commissioning​

Deep review against live app at dreamineering.com on 2026-02-18. Inspected: dashboard, CRM overview, contacts list, contact detail, deals list, deal detail, tasks, RFP overview, ventures list, venture detail, answer detail, answer library, review queue, my queue, analytics.

BLOCKER: Auth Broken — Infinite Redirect Loop (2026-02-24)​

Status: App completely inaccessible. No feature can be commissioned until this is fixed.

Symptom: Navigate to /dashboard → blank page. URL alternates between /dashboard and /sign-in?error=admin_access_required every ~400ms indefinitely.

Root cause from Vercel logs:

1. Clerk auth succeeds — userId user_36MjIJRckjpXRqdOHaZcgMpFjzE authenticates, organisation found, context validated
2. User-Role database query fails — PostgreSQL 22P02 (invalid text representation). A Clerk userId string (user_36MjIJ...) is being cast to a UUID column where it can't fit
3. Feature access denied — dashboard read blocked because role lookup returned an error
4. Redirect to /sign-in?error=admin_access_required — but Clerk sees user IS authenticated → afterSignInUrl: "/dashboard" → redirect back → loop

The fix: The User-Role query (added during multi-tenancy work) is using the Clerk userId (string with user_ prefix) instead of the systemUserId (valid UUID f388dbc7-cb98-41ee-9708-d6f5d2c54fe0). The ClerkAuthAdapter already maps these correctly — the role query downstream is passing the wrong field.

Evidence: Vercel production logs, request ID dx89j-1771901662057-8dbab5d4899c, 2026-02-24 15:54:22 NZST. 789 warnings + 789 errors in 30 minutes from the redirect loop.

Regression: Auth was previously working (PRD row #32 marked "Live — Clerk auth" on 2026-02-18). Multi-tenancy changes introduced the role check that breaks it.

Quality Assessment​

Gap Analysis​

Shape Up​

Appetite: 6-week cycle. Next cycle: seed the answer library (unlock the AI flywheel), add company entity, make activity logging frictionless. Following cycle: Go/No-Go scoring, property registry.

Next Steps​

1. Seed the answer library — process one real RFP to populate answers and prove the auto-fill loop
2. Add company entity — standalone pages showing all contacts and deals per organisation
3. Make activity logging frictionless — quick-log from deal detail, contact detail, venture detail
4. Pilot with one real construction sales team tracking real deals
5. Validate: do they create deals (activation) and return weekly (retention)?

Smallest move: Process one real RFP through the full cycle — upload document, answer 10 questions, approve answers to library, run a second RFP to see auto-fill work. That proves the flywheel.

Kill signal: If users create contacts but never create deals, the CRM is a rolodex. If they create ventures but never answer questions, the RFP tool is a project board. The activation metric is: first answer approved to library within 7 days.

Engineering Brief​

Cycle focus: Wire intelligence, then prove the flywheel spins.

Three algorithms and a payment flow sit dormant in the agency lib. The UI surfaces exist. The wiring is 1-2 days each. This is the highest-leverage work before the kill date — it turns "we built a CRM" into "our platform predicts and compounds."

Sprint 0: Wire Dormant Algorithms (Critical — kill date 2026-03-24)​

Why: 9 algorithms × 0 UI = 0 value. Three of these algorithms directly serve the Sales CRM product. The pages exist. The algorithms exist. The work is pure wiring — import function, call it with real data, render the result.

What to wire:

1. Sales Forecasting → Forecast Accuracy page (1 day)

   • Algorithm: libs/agency/src/lib/algorithms/sales-forecasting/ — exports calculateSalesForecast(input): SalesForecastResult
   • Target: /insights/forecast/ page — ForecastDashboard component already renders, calls getForecastDataAction
   • Wire: Fetch deals from repo → map to ForecastDeal[] (id, amount, probability, stage, closeDate) → call calculateSalesForecast({ deals, monthRange, config }) → return typed result
   • Outcome: Live monthly forecast with confidence scores, pipeline health assessment, recommendations

2. Compound Rate Tracking → RFP Analytics (1 day)

   • Algorithm: libs/agency/src/lib/algorithms/compound-rate-tracking/ — exports calculateCompoundRate(snapshots): CompoundRateResult
   • Target: /rfp/analytics/ page — already renders analytics?.compoundRate?.formatted placeholder
   • Wire: Fetch snapshots from outcomeMeasurementRepository.findByMetricCode('RFP_AUTO_FILL_RATE') → call calculateCompoundRate(snapshots) → map to existing compoundRate interface
   • Helpers: formatCompoundRate() → "+2.1%/week", getTrendIndicator() → "↑"
   • Outcome: Live compound growth rate, trend indicator, weeks-to-target projection

3. RFP Type Detection → Upload flow (2 days)

   • Algorithm: libs/agency/src/lib/algorithms/rfp-type-detection/ — document type classification
   • Target: Document upload flow on venture detail
   • Wire: After upload, run type detection → auto-tag document type → skip manual classification
   • Outcome: Documents auto-classified on upload

4. Stripe Webhooks → Production payments (2 days)

   • Current: Backend complete (Phase 10.1), webhook handlers pending
   • Wire: payment_intent.succeeded, subscription.created, subscription.updated, subscription.deleted
   • Outcome: End-to-end payment flow works in production

Acceptance test: Open /insights/forecast → see monthly deal predictions from real CRM data. Open /rfp/analytics → see compound rate with trend arrow and weeks-to-target. Upload a document → type auto-detected. Complete a Stripe checkout → subscription active.

Total effort: ~6 days. This is CONNECT work — no new algorithms, no new UI components, no new schemas.

Sprint 1: Seed the Answer Library (High — unlocks everything)​

Why: The RFP module's value proposition is "answer once, auto-fill forever." Until the library has approved answers, auto-fill returns nothing. Every other RFP feature (confidence scoring, compound growth, analytics) is waiting on this.

What to build/fix:

1. AI Loop end-to-end — Currently the "Run AI Loop" button exists on venture detail. Verify it actually generates draft answers for all 10 questions. If it does, the output should appear on each answer detail page (/rfp/answers/{id}) as a reviewable draft. Currently answer pages show "No answers found for this question." Fix the pipeline: AI generates → draft appears → SME reviews → approves → answer enters library.

2. Answer approval flow — On the answer detail page, after an AI-generated or manual answer exists, the SME needs: (a) Edit the answer, (b) Set confidence level, (c) Approve to library. Currently there's a manual write box and Save button but no Approve action that graduates the answer to the library.

3. Library population verification — After approval, the answer should appear in /rfp/library with its confidence score, question category, and source venture. Currently the library page shows "No Approved Answers Yet." Verify the data flow: answer approved → appears in library → available for auto-fill on next venture.

4. Auto-fill proof — Create a second test venture with similar questions. Run AI Loop. Verify it pulls from the approved library and pre-fills answers. This is the moment the flywheel proves itself.

Acceptance test: Create venture A → answer 10 questions → approve all to library → create venture B with overlapping questions → run AI Loop → at least 5 answers auto-filled from library. Library page shows 10 approved answers with confidence scores.

Sprint 2: Company Entity (High — Job 1 + Job 5)​

Why: "Show me everything with ABC Corp" is the most basic CRM question. Currently companies exist only as a text field on contacts. A sales director can't see: all contacts at a company, all deals with that company, all ventures involving them, total pipeline value per company.

What to build:

1. Company table — New entity: companies with fields: name, type (Client, Contractor, Subcontractor, Supplier, Consultant), industry, abn, website, address, phone, created_at.

2. Company detail page (/crm/companies/{id}) — Shows: company info, all linked contacts (with roles), all linked deals (with stage/value), all linked ventures. Summary stats: total pipeline value, active deals count, contact count.

3. Company list page (/crm/companies) — Table with search, filter by type, sort by name/deal count/pipeline value. Add to CRM sidebar nav between Contacts and Deals.

4. Contact-company relationship — Migrate the existing company text field on contacts to a foreign key. Contacts link to company records. A contact can belong to one company (with optional role/title at that company).

5. Deal-company linking — When a contact is added as a stakeholder on a deal, their company is implicitly linked. Company detail page shows all deals where any of its contacts are stakeholders.

Acceptance test: Create company "ABC Corp" (type: Client) → link 3 existing contacts to it → create a deal with one of those contacts as stakeholder → company detail page shows all 3 contacts and the deal with pipeline value.

Sprint 3: Activity Logging (High — Job 1 + Job 4)​

Why: The activity timeline UI exists on deal detail ("Log First Activity") but has zero entries across the entire system. Without activity history, the CRM can't answer "when did we last talk to them?" or "what happened at the site visit?" — which is the core of Job 1.

What to build:

1. Quick-log modal — A lightweight modal (not a full page) triggered from: deal detail, contact detail, venture detail, and the activities list page. Fields: type (Call, Email, Meeting, Site Visit, Note), date (defaults to now), description (free text), linked contacts (multi-select), linked deal (optional), linked venture (optional).

2. Activity creation API — POST /api/activities with: type, date, description, contact_ids[], deal_id, venture_id. All linking fields optional except at least one contact or one deal.

3. Activity timeline rendering — On deal detail: show activities in reverse chronological order with type icon, date, description, linked contacts. On contact detail: show all activities involving that contact. Filter by type.

4. Activity list page (/crm/activities) — Currently shows "No recent activity." Populate from the activities table. Show all activities across all entities, sortable by date, filterable by type.

5. Activity count on overview — The CRM overview shows "Total Activities" card. Wire this to the actual count.

Acceptance test: From deal detail, click "Log First Activity" → modal opens → log a "Site Visit" with date, description, and linked contact → activity appears in deal timeline → same activity appears on contact detail page → CRM overview shows "1" in Total Activities card.

Sprint 4: Data Quality (Medium — all jobs)​

Why: The system has 23 contacts but 1 deal at $0 value, 3 ventures all in Discovery, 0 tasks, 0 activities. The architecture works but the data doesn't tell a story. A pilot user seeing this will think "nobody uses this."

What to do:

1. Populate the Solar deal — The "Commercial Solar Installation - ABC Corp Warehouse" deal has $0 value, no probability, no close date. Set realistic values: $150,000 value, 60% probability, close date 3 months out. This makes the pipeline dashboard meaningful.

2. Move ventures through stages — All 3 ventures sit in Discovery. Move the Solar venture to Preparation (it has 10 questions defined). Move "Test Project Alpha" to Qualification. Leave Dreamineering in Discovery. This makes the kanban board tell a story.

3. Add stakeholders to the deal — The deal has 0 stakeholders even though the venture has 1 linked contact. Add Matt Mischewski as a stakeholder on the deal too, with "Economic Buyer" role. This validates the stakeholder flow from deal side.

4. Log 3-5 activities — Create realistic activities: initial call, site visit, proposal discussion. This populates the activity timeline and proves the logging flow.

5. Create 2-3 tasks — "Send revised proposal by Friday," "Schedule site inspection," "Follow up on financing options." Link to the deal. This populates the task board.

Acceptance test: Dashboard shows: pipeline value > $0, at least 2 deals across different stages, recent activity entries. A new user opening the app sees a system in use, not an empty shell.

Not This Cycle​

These are real gaps but don't block the flywheel:

• Property entity — Address data exists on contacts/ventures. Standalone entity is nice-to-have until there are 10+ properties.
• Go/No-Go scoring — Qualification stage exists in kanban. Scoring checklist adds value at scale, not at 3 ventures.
• Assignments page — Nav link redirects to dashboard. Matters when there are multiple reviewers.
• Calendar — Important for daily use but doesn't prove the core value loop.
• Cross-entity search — Contact search works. Expand when there's enough data to search.
• Insights/Plans/Agents — Stub modules. Don't start until CRM + RFP core is proven with real usage.

Definition of Done (This Cycle)​

1. Answer library has 10+ approved answers with confidence scores
2. Auto-fill works: venture B pulls answers from venture A's approved library
3. Company entity exists with detail pages showing linked contacts/deals
4. Activity timeline has real entries visible from deal + contact detail
5. Pipeline dashboard shows realistic values ($100K+)
6. One real external user can track a deal from lead to proposal using this tool

North Star Metric​

Win Rate > 30% (currently 22%)

This is the ONE metric this PRD exists to move. Everything else — contacts, pipelines, auto-fill rates, answer libraries — is secondary. If win rate doesn't move, the tool is busy work.

Mycelium Capability​

The Sales CRM & RFP is a demand-driven sales capability. Currently built for construction and solar, but the RFP workflow, answer library, and confidence scoring patterns apply to any industry with competitive bidding — real estate, consulting, government contracting.

Currently Growing In: stackmates

Production Audit — 2026-02-24​

Verified against dreamineering.com (authenticated session). The app routes exist, navigation is correct, but the core data pipeline is broken.

Route Status​

Blocking Issues​

1. Convex rfp_answer permissions — Answer Library and Review Queue both fail with the same auth error. This blocks the entire auto-fill pipeline (Job 3). Root cause: table-level read permission not granted to authenticated user role.
2. Ventures query failure — Generic "Operation failed" on ventures list. Blocks creating and managing RFP projects. May be a separate Convex function error or the same permissions issue.
3. Agents fetch failure — Assignments page can't load SMEs. Blocks the review/approval workflow.

Data Issues​

4. Industry dropdown mismatch — Create Venture offers: Technology, Healthcare, Finance, Education, Manufacturing, Retail, Services, Other. Missing: Construction, Infrastructure, Energy, Solar — the verticals this PRD explicitly targets. AI response tailoring won't match the target market.

What Works​

• Dashboard routing and navigation structure is correct
• RFP Overview renders with stats (though likely hardcoded/seed data)
• Analytics page renders metrics and confidence distribution
• My Queue renders empty state with correct links
• Create Venture form is functional (fields, validation, dropdown)
• CRM Overview renders pipeline stages (Lead/Qualified/Proposal/Negotiation) and monthly goals
• Clerk auth is working (user is authenticated, avatar renders)

Against Definition of Done​

Next Actions (Engineering)​

1. Fix Convex table permissions for rfp_answer — unblocks 3 pages
2. Debug ventures list query — separate from permissions, returns generic error
3. Fix agents fetch for assignments page
4. Add Construction, Infrastructure, Energy, Solar to industry dropdown
5. Seed or create real venture data to validate the full loop

Context​

• Jobs To Be Done — Demand-side thinking: what progress, not what features
• Validate Demand — Awareness levels and kill signals
• JTBD Interviews — Extract real jobs from real people
• Shape Up — Fixed time, variable scope
• CRM Software — Generic CRM feature baseline
• Sales Pipeline — Pipeline management patterns
• Sales Support — Sales enablement and intelligence
• Vertical SaaS — The vertical software playbook
• Construction Industry — Domain context
• Solar Industry — Parallel vertical with RFP-driven sales
• Phygital Mycelium — The capability catalogue