Files

dwindown 97426d5ab1 first commit all files

2026-01-28 00:26:00 +07:00

25 KiB

Raw Permalink Blame History

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:

Cannot execute article without plan - Writing mode chat doesn't create a plan
User confusion - Writing mode suggests article generation but can't deliver
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:

Chat context lost - Previous conversation not available to AI
No plan - Cannot execute article
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:

Additional instructions ignored - User's note in writing mode doesn't update plan
Confusing UX - User expects their note to be incorporated
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:

Chat context lost - Previous conversation not available
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:

Initial load delay - Need to fetch chat history from backend
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:

Chat context not used - Previous conversation not considered
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:

No search audit trail - Can't see what was searched
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:

No chat context - Original conversation lost
No plan context - Original outline not referenced
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

Send Chat History to All Modes

// In sidebar.js - sendMessage function
const payload = {
    messages: messages,
    postId: postId,
    type: agentMode,
    chatHistory: messages, // ✅ Add this
    postConfig: postConfig,
    stream: true
};

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

Improve Block Refinement Context

// 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

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"
Context Indicators
- Show badge: "📝 Outline available"
- Show badge: "💬 3 messages in context"
- Show badge: "🔍 Web search enabled"
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

Context Persistence Layer

// 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,
));

Context Debugging Tool
- Admin panel showing current context state
- "What does the AI know?" button
- Context timeline visualization
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:

✅ Chat history available to AI?
✅ Plan available when needed?
✅ Language correctly detected/used?
✅ Post config applied?
✅ 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:

Immediate: Send chatHistory to all API endpoints
Short-term: Handle writing mode notes properly
Medium-term: Add context indicators to UI
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

25 KiB Raw Permalink Blame History

Context Flow Analysis: Chat, Planning, and Writing Modes

🎯 Executive Summary

📊 Context Storage Mechanisms

1. Post Meta Storage

2. Frontend State (React)

3. Request Parameters

🔄 User Interaction Flows

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

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

Flow 3: Chat → Direct Writing (Skip Planning)

Flow 4: Planning → Manual Mode Switch → Writing

Flow 5: Direct Planning Mode (No Chat)

Flow 6: Chat → Planning with Clarity Quiz

Flow 7: Writing Mode → @block Refinement

Flow 8: Multiple Chat Sessions (Page Refresh)

Flow 9: Plan Revision in Planning Mode

Flow 10: SEO Keyword Suggestion Flow

Flow 11: Web Search Integration

Flow 12: Multi-Block Batch Refinement

🔍 Context Loss Scenarios

Critical Context Loss Issues

💡 Recommendations

Priority 1: Critical Fixes

Priority 2: UX Improvements

Priority 3: Advanced Features

📋 Context Flow Matrix

🧪 Testing Checklist

Test Each Flow

Context Verification

🎯 Ideal Context Flow (Recommended)

📝 Conclusion

25 KiB

Raw Permalink Blame History