vibn-frontend/BROKEN_FLOW_ANALYSIS.md

BROKEN FLOW - ROOT CAUSE ANALYSIS

Problem Summary

User uploads document → Checklist shows 0 documents → Project immediately in extraction_review mode

The 3 Issues

Issue 1: Document Upload May Be Failing Silently

Upload Endpoint: /api/projects/[projectId]/knowledge/upload-document

What Should Happen:

1. File uploaded to Firebase Storage
2. knowledge_item created with sourceType: 'imported_document'
3. contextSources subcollection updated
4. Returns success with chunk count

What's Probably Broken:

• Upload endpoint may be throwing an error
• knowledge_item not being created
• User sees toast success but backend failed

Check:

Browser Console → Network tab → upload-document request → Status code?
Server logs → Any errors during upload?

---

Issue 2: Checklist Query Returns 0 Even If Documents Exist

Checklist Query:

collection(db, 'knowledge_items')
  .where('projectId', '==', projectId)
  .where('sourceType', '==', 'imported_document')

Possible Causes:

1. Firestore Index Missing - Composite index for (projectId, sourceType) may still be building

   • Just deployed 5 minutes ago
   • Can take 5-15 minutes to build
   • Check: Firebase Console → Firestore → Indexes

2. Security Rules Block Client Query - Rules were deployed but may have error

   • Check browser console for permission errors
   • Check: Firestore rules allow read where projectId matches user's project

3. Documents Don't Exist - Upload actually failed

   • Check: Firebase Console → Firestore → knowledge_items collection

4. Wrong Collection/Field Names - Mismatch between write and read

   • Backend writes to: knowledge_items with sourceType: 'imported_document'
   • Frontend reads from: knowledge_items where sourceType == 'imported_document'
   • Should match ✓

---

Issue 3: Project Immediately in extraction_review Phase

Current State:

currentPhase: 'extraction_review'
readyForNextPhase: undefined

Why This Happened:

1. User said "I connected github" → AI detected "that's everything"
2. Fallback phrase detection triggered: 'perfect! let me analyze'
3. Backend extraction ran with 0 documents
4. Created empty extraction handoff
5. Transitioned to extraction_review phase

The Flow:

User: "I connected github"
  ↓
AI: "Perfect, I can see your GitHub repo..."
  ↓
Fallback detection: reply contains "Perfect!"
  ↓
readyForExtraction = true
  ↓
Backend extraction triggered
  ↓
No documents found → empty handoff
  ↓
currentPhase = 'extraction_review'

Root Cause: The fallback phrase detection is TOO aggressive:

const confirmPhrases = [
  'perfect! let me analyze',  // ← TOO BROAD
  'perfect! i\'m starting',
  //...
];

The AI said "Perfect, I can see your GitHub repo" which matches 'perfect!' prefix, triggering the handoff prematurely.

---

Fixes Needed

Fix 1: Check Upload Endpoint Errors

Add better error handling and logging:

try {
  const knowledgeItem = await createKnowledgeItem({...});
  console.log('[upload-document] SUCCESS:', knowledgeItem.id);
} catch (error) {
  console.error('[upload-document] FAILED:', error);
  throw error; // Don't swallow
}

Fix 2: Wait for Firestore Index

The index was just deployed. Give it 10-15 minutes to build.

OR: Change checklist to use simpler query without sourceType filter:

// Simple query (no index needed)
collection(db, 'knowledge_items')
  .where('projectId', '==', projectId)

// Then filter in memory:
const docs = snapshot.docs.filter(d => d.data().sourceType === 'imported_document');

Fix 3: Make Fallback Detection More Specific

Change from:

'perfect! let me analyze',  // Too broad

To:

'perfect! let me analyze what you',  // More specific
'i\'ll start digging into',
'i\'m starting the analysis',

And check for EXACT phrases, not prefixes:

const replyLower = reply.reply.toLowerCase();
const exactMatch = confirmPhrases.some(phrase => 
  replyLower.includes(phrase) &&  // Contains phrase
  replyLower.includes('analyze') || replyLower.includes('digging')  // AND mentions analysis
);

---

Immediate Actions

1. Check Browser Network Tab

   • Did /api/projects/.../knowledge/upload-document return 200 or 500?
   • Check response body for errors

2. Check Firestore Console

   • Go to Firebase Console → Firestore
   • Look at knowledge_items collection
   • Are there ANY documents for projectId Rcj5OY2xpQFHAzqUyMim?

3. Wait for Index

   • Firestore indexes take 5-15 minutes to build
   • Check: Firebase Console → Firestore → Indexes tab
   • Look for knowledge_items (projectId, sourceType) status

4. Fix Aggressive Fallback

   • Update phrase detection to be more specific
   • Require both "perfect/okay" AND "analyze/digging/start"

---

Test Plan

1. Reset the project phase to collector:

   // Firebase Console or API call
   projects/Rcj5OY2xpQFHAzqUyMim
   {
     currentPhase: 'collector',
     'phaseData.phaseHandoffs.collector': null
   }
   

2. Upload a document

   • Watch Network tab
   • Check for 200 response
   • Verify console log: [upload-document] SUCCESS: xxx

3. Wait 30 seconds

   • Firestore listener should update
   • Checklist should show "1 of 3 complete"

4. Send "that's everything to analyze" (explicit phrase)

   • Should trigger handoff
   • Should NOT trigger on "Perfect!" alone

---

Date

November 17, 2025