# Context Flow Analysis: Chat, Planning, and Writing Modes

**Date:** January 25, 2026  
**Version:** 0.1.3+  
**Purpose:** Comprehensive analysis of context preservation across different user interaction flows

---

## 🎯 Executive Summary

This document analyzes how context (chat history, post configuration, language detection, and plan data) is preserved or lost across different user interaction flows in the WP Agentic Writer plugin. It identifies **12 distinct user flows**, maps their context behavior, and provides recommendations for improvements.

**Key Finding:** Context preservation varies significantly depending on the flow path, with some flows maintaining full context while others may lose critical information.

---

## 📊 Context Storage Mechanisms

### **1. Post Meta Storage**

The plugin stores context in WordPress post meta:

| Meta Key | Content | Updated By | Used By |
|----------|---------|------------|---------|
| `_wpaw_chat_history` | Array of user/assistant messages | `update_post_chat_history()` | Chat mode, Plan generation |
| `_wpaw_plan` | JSON outline structure | `stream_generate_plan()` | Article execution |
| `_wpaw_detected_language` | Language code (e.g., 'Indonesian') | `stream_generate_plan()` | All modes |
| `_wpaw_post_config` | Post configuration (tone, audience, SEO) | `update_post_config()` | All modes |
| `_wpaw_memory` | Last prompt/intent tracking | `update_post_memory()` | Internal tracking |

### **2. Frontend State (React)**

| State Variable | Scope | Persistence |
|----------------|-------|-------------|
| `messages` | Component state | Session only (lost on refresh) |
| `agentMode` | localStorage | Persists across sessions |
| `postConfig` | Component state | Session only |
| `currentPlan` | useRef | Session only |

### **3. Request Parameters**

Context is passed via REST API requests:
- `chatHistory` - Array of messages from frontend
- `postConfig` - Current configuration
- `detectedLanguage` - Language from clarity quiz
- `clarificationAnswers` - Answers from clarity quiz

---

## 🔄 User Interaction Flows

### **Flow 1: Standard Flow (Chat → Planning → Writing)**

**Path:** Chat mode → Ask for outline → Planning mode generates plan → Click "Start Writing" → Writing mode executes

**Context Behavior:**

```
1. User types in Chat mode
   ├─ Messages stored in frontend state
   ├─ Chat history saved to post meta (_wpaw_chat_history)
   └─ Language detected and stored (_wpaw_detected_language)

2. Planning mode generates outline
   ├─ Receives: chatHistory from frontend
   ├─ Builds: chat_history_context from chatHistory array
   ├─ Stores: Plan in _wpaw_plan
   ├─ Stores: Language in _wpaw_detected_language
   └─ Keywords auto-suggested (if SEO enabled)

3. Click "Start Writing"
   ├─ Reads: _wpaw_plan (required)
   ├─ Reads: _wpaw_detected_language
   ├─ Reads: postConfig from frontend
   └─ Generates article with full context
```

**Context Preservation:** ✅ **EXCELLENT**
- Chat history: ✅ Available via chatHistory parameter
- Plan: ✅ Stored in post meta
- Language: ✅ Stored in post meta
- Post config: ✅ Passed from frontend

**Potential Issues:** None - This is the ideal flow.

---

### **Flow 2: Direct Writing Mode (No Chat, No Planning)**

**Path:** Switch to Writing mode → Type instruction → Send

**Context Behavior:**

```
1. User switches to Writing mode
   ├─ Frontend: agentMode = 'writing'
   └─ No chat history built

2. User types instruction
   ├─ Frontend sends to /chat endpoint with type='writing'
   ├─ Backend: handle_chat_request()
   ├─ No plan required for chat endpoint
   └─ Response returned

3. If user wants to generate article
   ├─ Must have a plan (_wpaw_plan)
   └─ ERROR: "No plan found. Please generate a plan first."
```

**Context Preservation:** ⚠️ **LIMITED**
- Chat history: ✅ Can be built from messages
- Plan: ❌ **NOT AVAILABLE** - Cannot execute article
- Language: ⚠️ May not be detected
- Post config: ✅ Available from frontend

**Issues:**
1. **Cannot execute article without plan** - Writing mode chat doesn't create a plan
2. **User confusion** - Writing mode suggests article generation but can't deliver
3. **No outline context** - AI has no structure to follow

**Recommendation:** 
- Writing mode should either:
  - A) Auto-generate a minimal plan from the instruction, OR
  - B) Show clear error: "Please create an outline first (switch to Planning mode)"

---

### **Flow 3: Chat → Direct Writing (Skip Planning)**

**Path:** Chat mode → Build context → Switch to Writing mode → Type instruction → Send

**Context Behavior:**

```
1. User chats in Chat mode
   ├─ Chat history built in frontend state
   ├─ Saved to _wpaw_chat_history
   └─ Language may be detected

2. User switches to Writing mode
   ├─ Frontend: agentMode = 'writing'
   └─ Chat history still in frontend state

3. User types instruction in Writing mode
   ├─ Sends to /chat endpoint with type='writing'
   ├─ chatHistory parameter: ⚠️ NOT SENT (only sent to /generate-plan)
   ├─ Backend has no access to previous chat
   └─ Response generated without chat context

4. If user tries to execute article
   └─ ERROR: "No plan found"
```

**Context Preservation:** ❌ **POOR**
- Chat history: ❌ **LOST** - Not sent to /chat endpoint in writing mode
- Plan: ❌ Not available
- Language: ⚠️ May be stored from earlier chat
- Post config: ✅ Available

**Issues:**
1. **Chat context lost** - Previous conversation not available to AI
2. **No plan** - Cannot execute article
3. **Inconsistent behavior** - User expects context to carry over

**Recommendation:**
- Send `chatHistory` parameter to `/chat` endpoint for all modes
- OR retrieve `_wpaw_chat_history` from post meta in backend

---

### **Flow 4: Planning → Manual Mode Switch → Writing**

**Path:** Planning mode → Generate outline → Manually switch to Writing → Add note → Send

**Context Behavior:**

```
1. Planning mode generates outline
   ├─ Plan stored in _wpaw_plan
   ├─ Language stored
   └─ Chat history stored

2. User manually switches to Writing mode
   ├─ Frontend: agentMode = 'writing'
   └─ Plan still in post meta

3. User adds additional note
   ├─ Sends to /chat endpoint with type='writing'
   ├─ chatHistory: ⚠️ NOT SENT
   ├─ AI responds without knowing about the plan
   └─ User's note not incorporated into plan

4. User tries to execute article
   ├─ Reads _wpaw_plan (original plan, unchanged)
   ├─ User's additional note: ❌ NOT INCLUDED
   └─ Article generated from original plan only
```

**Context Preservation:** ⚠️ **PARTIAL**
- Chat history: ❌ Not sent to writing mode chat
- Plan: ✅ Available but not updated
- Language: ✅ Available
- Post config: ✅ Available
- **User's additional note:** ❌ **LOST**

**Issues:**
1. **Additional instructions ignored** - User's note in writing mode doesn't update plan
2. **Confusing UX** - User expects their note to be incorporated
3. **No plan revision** - Writing mode chat doesn't trigger plan update

**Recommendation:**
- Writing mode should either:
  - A) Update the plan with user's additional instructions, OR
  - B) Store the note and append it to execution prompt, OR
  - C) Show warning: "To modify the outline, switch back to Planning mode"

---

### **Flow 5: Direct Planning Mode (No Chat)**

**Path:** Switch to Planning mode → Type topic → Generate outline

**Context Behavior:**

```
1. User switches to Planning mode
   └─ No prior chat history

2. User types topic
   ├─ Sends to /generate-plan endpoint
   ├─ chatHistory: [] (empty)
   ├─ chat_history_context: "" (empty)
   └─ Plan generated from topic only

3. Plan generation
   ├─ Stores plan in _wpaw_plan
   ├─ Detects and stores language
   └─ No chat history to reference
```

**Context Preservation:** ✅ **GOOD**
- Chat history: N/A (none exists)
- Plan: ✅ Generated and stored
- Language: ✅ Detected and stored
- Post config: ✅ Available

**Issues:** None - This is a valid flow for quick outline generation.

---

### **Flow 6: Chat → Planning with Clarity Quiz**

**Path:** Chat mode → Build context → Planning mode → Clarity quiz appears → Answer questions → Generate

**Context Behavior:**

```
1. User chats in Chat mode
   ├─ Chat history built
   └─ Language detected

2. Planning mode triggers clarity quiz
   ├─ Frontend: setInClarification(true)
   └─ Quiz questions shown

3. User answers quiz
   ├─ Answers stored in frontend state
   └─ postConfig updated with answers

4. Submit quiz
   ├─ Sends to /generate-plan with:
   │  ├─ clarificationAnswers
   │  ├─ chatHistory ✅
   │  ├─ postConfig ✅
   │  └─ detectedLanguage ✅
   └─ Plan generated with full context
```

**Context Preservation:** ✅ **EXCELLENT**
- Chat history: ✅ Sent via chatHistory
- Clarity answers: ✅ Sent via clarificationAnswers
- Language: ✅ Sent via detectedLanguage
- Post config: ✅ Updated with quiz answers

**Issues:** None - This is the ideal flow with maximum context.

---

### **Flow 7: Writing Mode → @block Refinement**

**Path:** Article generated → Switch to Writing mode → Use @block mention → Refine specific block

**Context Behavior:**

```
1. Article already generated
   ├─ Content in Gutenberg blocks
   └─ Plan in _wpaw_plan

2. User types "@block-id refine this section"
   ├─ Frontend detects @mention
   ├─ Sends to /refine-block endpoint
   └─ NOT to /chat endpoint

3. Block refinement
   ├─ Receives: block content, refinement request
   ├─ Receives: articleContext (surrounding blocks)
   ├─ Receives: postConfig
   ├─ chatHistory: ❌ NOT SENT
   └─ Refinement done without chat context
```

**Context Preservation:** ⚠️ **PARTIAL**
- Block content: ✅ Available
- Article context: ✅ Sent (surrounding blocks)
- Post config: ✅ Available
- Chat history: ❌ Not sent
- Original plan: ⚠️ Not explicitly sent

**Issues:**
1. **Chat context lost** - Previous conversation not available
2. **Original intent unclear** - AI doesn't know user's original goals

**Recommendation:**
- Include `chatHistory` or at least last few messages in refinement requests
- Include original plan section for context

---

### **Flow 8: Multiple Chat Sessions (Page Refresh)**

**Path:** Chat → Build context → Refresh page → Continue chatting

**Context Behavior:**

```
1. First session
   ├─ Chat history in frontend state
   └─ Saved to _wpaw_chat_history post meta

2. Page refresh
   ├─ Frontend state: ❌ CLEARED
   ├─ Post meta: ✅ PERSISTS
   └─ agentMode: ✅ Restored from localStorage

3. Continue chatting
   ├─ Frontend loads chat history from post meta
   ├─ Displays previous messages
   ├─ New messages appended
   └─ Context maintained
```

**Context Preservation:** ✅ **GOOD**
- Chat history: ✅ Restored from post meta
- Plan: ✅ Persists in post meta
- Language: ✅ Persists in post meta
- Post config: ⚠️ May need to be re-fetched

**Issues:**
1. **Initial load delay** - Need to fetch chat history from backend
2. **Post config sync** - May not reflect latest changes immediately

**Recommendation:**
- Ensure chat history is loaded on component mount
- Fetch post config from backend on load

---

### **Flow 9: Plan Revision in Planning Mode**

**Path:** Planning mode → Generate outline → User asks for changes → Plan revised

**Context Behavior:**

```
1. Initial plan generated
   ├─ Plan stored in _wpaw_plan
   └─ Displayed in frontend

2. User types revision request
   ├─ Frontend detects existing plan
   ├─ Calls revisePlanFromPrompt()
   ├─ Sends to /revise-plan endpoint
   └─ NOT to /generate-plan

3. Plan revision
   ├─ Receives: instruction, current plan
   ├─ Receives: postConfig
   ├─ chatHistory: ⚠️ NOT EXPLICITLY SENT
   ├─ Generates revised plan
   └─ Updates _wpaw_plan
```

**Context Preservation:** ✅ **GOOD**
- Current plan: ✅ Sent explicitly
- Post config: ✅ Available
- Chat history: ⚠️ Not sent but may not be needed
- Language: ✅ Available from post meta

**Issues:**
1. **Chat context not used** - Previous conversation not considered
2. **Revision-only context** - AI only sees current plan + new instruction

**Recommendation:**
- Consider sending recent chat history for better context
- OR document that plan revision is isolated from chat history

---

### **Flow 10: SEO Keyword Suggestion Flow**

**Path:** Planning mode → Generate outline → Keywords auto-suggested → Clarity quiz pre-filled

**Context Behavior:**

```
1. Outline generated
   ├─ Plan stored
   └─ Frontend receives plan

2. Auto-trigger keyword suggestion
   ├─ Calls /suggest-keywords endpoint
   ├─ Sends: title, sections, language
   ├─ chatHistory: ❌ NOT SENT
   └─ Keywords suggested based on outline only

3. Keywords returned
   ├─ Stored in frontend state
   ├─ Pre-filled in clarity quiz
   └─ User can edit before submission

4. Clarity quiz submitted
   ├─ Keywords saved to postConfig
   └─ Used in article generation
```

**Context Preservation:** ✅ **GOOD**
- Outline: ✅ Sent to keyword suggester
- Language: ✅ Sent
- Chat history: ❌ Not sent (not needed)
- Keywords: ✅ Stored in postConfig

**Issues:** None - Keywords are based on outline, which is sufficient context.

---

### **Flow 11: Web Search Integration**

**Path:** Chat/Planning with web search enabled → AI searches web → Results incorporated

**Context Behavior:**

```
1. User enables web search
   ├─ postConfig.web_search = true
   └─ Passed to backend

2. Chat or plan generation
   ├─ Backend builds web_search_options
   ├─ Passes to OpenRouter API
   └─ AI performs web search

3. Search results
   ├─ Incorporated into AI response
   ├─ NOT stored separately
   └─ Included in chat history as part of response

4. Subsequent requests
   ├─ Search results: ⚠️ Only in chat history
   └─ Not explicitly tracked
```

**Context Preservation:** ⚠️ **PARTIAL**
- Search results: ⚠️ Only in chat history text
- Search metadata: ❌ Not stored
- Search queries: ❌ Not logged

**Issues:**
1. **No search audit trail** - Can't see what was searched
2. **Search results ephemeral** - Lost if chat history cleared

**Recommendation:**
- Consider logging search queries and results
- Store search metadata for debugging/auditing

---

### **Flow 12: Multi-Block Batch Refinement**

**Path:** Article generated → Select multiple blocks → Request batch refinement

**Context Behavior:**

```
1. User selects multiple blocks
   ├─ Frontend: blocksToRefine array
   └─ allBlocks for context

2. Batch refinement request
   ├─ Sends to /refine-blocks endpoint
   ├─ Receives: blocksToRefine, allBlocks, instruction
   ├─ Receives: postConfig
   ├─ chatHistory: ❌ NOT SENT
   ├─ Plan: ❌ NOT SENT
   └─ Refinement based on blocks + instruction only

3. Refinement execution
   ├─ Each block refined individually
   ├─ Context: surrounding blocks
   └─ No cross-block coordination
```

**Context Preservation:** ⚠️ **LIMITED**
- Block content: ✅ Available
- Surrounding context: ✅ Available (allBlocks)
- Post config: ✅ Available
- Chat history: ❌ Not sent
- Original plan: ❌ Not sent
- Cross-block coordination: ❌ Not implemented

**Issues:**
1. **No chat context** - Original conversation lost
2. **No plan context** - Original outline not referenced
3. **Independent refinements** - Blocks refined in isolation

**Recommendation:**
- Send original plan section for each block
- Consider chat history for understanding user intent
- Implement cross-block coordination for consistency

---

## 🔍 Context Loss Scenarios

### **Critical Context Loss Issues**

| Scenario | Lost Context | Impact | Severity |
|----------|--------------|--------|----------|
| Chat → Writing mode switch | Chat history not sent to /chat endpoint | AI doesn't know previous conversation | 🔴 HIGH |
| Writing mode additional notes | Notes not incorporated into plan | User instructions ignored | 🔴 HIGH |
| Block refinement | Chat history not available | Original intent unclear | 🟡 MEDIUM |
| Page refresh | Frontend state cleared | Need to reload from backend | 🟢 LOW |
| Web search results | Search metadata not stored | No audit trail | 🟢 LOW |

---

## 💡 Recommendations

### **Priority 1: Critical Fixes**

1. **Send Chat History to All Modes**
   ```javascript
   // In sidebar.js - sendMessage function
   const payload = {
       messages: messages,
       postId: postId,
       type: agentMode,
       chatHistory: messages, // ✅ Add this
       postConfig: postConfig,
       stream: true
   };
   ```

2. **Handle Writing Mode Notes**
   - Option A: Auto-update plan with additional instructions
   - Option B: Store notes and append to execution prompt
   - Option C: Show clear warning about mode limitations

3. **Improve Block Refinement Context**
   ```php
   // In handle_refine_block
   $chat_history = $this->get_post_chat_history( $post_id );
   $plan = get_post_meta( $post_id, '_wpaw_plan', true );
   // Include in refinement prompt
   ```

### **Priority 2: UX Improvements**

4. **Mode-Specific Guidance**
   - Chat mode: "Building context for your article"
   - Planning mode: "Creating outline - chat history will be used"
   - Writing mode: "Refining content - outline required"

5. **Context Indicators**
   - Show badge: "📝 Outline available"
   - Show badge: "💬 3 messages in context"
   - Show badge: "🔍 Web search enabled"

6. **Error Messages**
   - Writing mode without plan: "Please create an outline first (switch to Planning mode)"
   - Refinement without context: "Loading article context..."

### **Priority 3: Advanced Features**

7. **Context Persistence Layer**
   ```php
   // Store comprehensive context
   update_post_meta( $post_id, '_wpaw_context', array(
       'chat_history' => $chat_history,
       'plan' => $plan,
       'language' => $language,
       'config' => $post_config,
       'search_history' => $search_queries,
       'refinement_history' => $refinements,
   ));
   ```

8. **Context Debugging Tool**
   - Admin panel showing current context state
   - "What does the AI know?" button
   - Context timeline visualization

9. **Smart Context Pruning**
   - Keep last N messages (configurable)
   - Summarize older context
   - Preserve critical information (plan, config)

---

## 📋 Context Flow Matrix

| Flow | Chat History | Plan | Language | Post Config | Notes |
|------|--------------|------|----------|-------------|-------|
| Chat → Planning → Writing | ✅ Full | ✅ Full | ✅ Full | ✅ Full | **Ideal flow** |
| Direct Writing | ⚠️ Limited | ❌ None | ⚠️ Partial | ✅ Full | Cannot execute |
| Chat → Writing (skip plan) | ❌ Lost | ❌ None | ⚠️ Partial | ✅ Full | Context lost |
| Planning → Manual switch → Writing | ❌ Lost | ✅ Full | ✅ Full | ✅ Full | Notes ignored |
| Direct Planning | N/A | ✅ Full | ✅ Full | ✅ Full | Valid flow |
| Chat → Planning + Quiz | ✅ Full | ✅ Full | ✅ Full | ✅ Full | **Best flow** |
| Writing → @block refinement | ❌ Lost | ⚠️ Partial | ✅ Full | ✅ Full | Limited context |
| Page refresh → Continue | ✅ Restored | ✅ Full | ✅ Full | ⚠️ Partial | Need reload |
| Plan revision | ⚠️ Partial | ✅ Full | ✅ Full | ✅ Full | Isolated |
| Keyword suggestion | ❌ None | ✅ Full | ✅ Full | ✅ Full | Outline-based |
| Web search | ✅ In history | ✅ Full | ✅ Full | ✅ Full | No metadata |
| Batch refinement | ❌ Lost | ❌ Lost | ✅ Full | ✅ Full | Isolated blocks |

---

## 🧪 Testing Checklist

### **Test Each Flow**

- [ ] **Flow 1:** Chat → Planning → Writing (baseline)
- [ ] **Flow 2:** Direct Writing mode (expect error)
- [ ] **Flow 3:** Chat → Writing (verify context loss)
- [ ] **Flow 4:** Planning → Manual switch → Writing (verify note loss)
- [ ] **Flow 5:** Direct Planning (verify works)
- [ ] **Flow 6:** Chat → Planning + Quiz (verify full context)
- [ ] **Flow 7:** @block refinement (verify limited context)
- [ ] **Flow 8:** Page refresh (verify restoration)
- [ ] **Flow 9:** Plan revision (verify isolation)
- [ ] **Flow 10:** Keyword suggestion (verify works)
- [ ] **Flow 11:** Web search (verify results)
- [ ] **Flow 12:** Batch refinement (verify isolation)

### **Context Verification**

For each flow, verify:
1. ✅ Chat history available to AI?
2. ✅ Plan available when needed?
3. ✅ Language correctly detected/used?
4. ✅ Post config applied?
5. ✅ User instructions incorporated?

---

## 🎯 Ideal Context Flow (Recommended)

```
┌─────────────────────────────────────────────────────────────┐
│                     USER INTERACTION                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   FRONTEND (React)                           │
│  • Maintains messages[] state                                │
│  • Tracks agentMode (chat/planning/writing)                  │
│  • Stores postConfig                                         │
│  • Holds currentPlan ref                                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  EVERY API REQUEST                           │
│  Should include:                                             │
│  ✅ chatHistory (last N messages)                            │
│  ✅ postConfig (current configuration)                       │
│  ✅ currentPlan (if available)                               │
│  ✅ detectedLanguage (if known)                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 BACKEND (PHP)                                │
│  • Retrieves additional context from post meta               │
│  • Merges frontend + backend context                         │
│  • Builds comprehensive prompt                               │
│  • Stores results back to post meta                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   AI RECEIVES                                │
│  • Full chat history                                         │
│  • Current plan (if exists)                                  │
│  • Post configuration                                        │
│  • Language preference                                       │
│  • User's current instruction                                │
│  = MAXIMUM CONTEXT                                           │
└─────────────────────────────────────────────────────────────┘
```

---

## 📝 Conclusion

**Current State:**
- ✅ Standard flow (Chat → Planning → Writing) works well
- ⚠️ Alternative flows have context loss issues
- ❌ Writing mode without planning is problematic
- ❌ Chat history not sent to all endpoints

**Recommended Actions:**

1. **Immediate:** Send `chatHistory` to all API endpoints
2. **Short-term:** Handle writing mode notes properly
3. **Medium-term:** Add context indicators to UI
4. **Long-term:** Implement comprehensive context persistence layer

**Impact:**
- Better AI responses (more context)
- Fewer user frustrations (instructions not ignored)
- More predictable behavior (consistent across flows)
- Easier debugging (context visibility)

---

**Analysis Date:** January 25, 2026  
**Status:** 🔴 CRITICAL ISSUES IDENTIFIED  
**Next Steps:** Implement Priority 1 fixes
