# 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:** 
```typescript
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:
```typescript
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:
```typescript
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:
```typescript
// 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:
```typescript
'perfect! let me analyze',  // Too broad
```

To:
```typescript
'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:
```typescript
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`:**
   ```typescript
   // 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