wp-agentic-writer/docs/architecture/CORE_CHAT_WORKFLOW_GAPS.md

Core Chat Workflow - Gap Analysis

Document: docs/architecture/CORE_CHAT_WORKFLOW_SPEC.md Analysis Date: 2026-05-17 Status: 🔴 ANALYSIS COMPLETE

---

Executive Summary

After comparing the Core Chat Workflow Spec against current implementation, here's what's found:

Category	Spec Items	Implemented	Gap
Document States	6 scenarios	3	3 missing
Mode System	5 modes + transitions	3 modes	2 missing
Context Management	3 layers + optimization	2 layers	1 missing
Intent Detection	6 intents + actions	4 intents	2 missing
Outline System	Full structure + refinement	Basic	Incomplete
Writing Pipeline	8 components	5	3 missing
Refinement	5 types + multi-pass	2 types	3 missing
SEO Handler	6 components	3	3 missing
GEO Handler	Scoring + suggestions	None	Missing
Markdown Renderer	3 preview modes	1 mode	2 missing

---

Detailed Gap Analysis

1. Document State Detection

Spec Scenario	Implementation	Status
New post (no content, no plan)	Onboarding + chat	✅ Done
New post (from quick draft)	Shows if plan exists	⚠️ Partial
Edit existing (has content only)	Enables refinement	⚠️ Partial
Edit existing (has plan + content)	Full restore	⚠️ Partial
Re-open during writing	resume flag	❌ Not implemented
Re-open after completion	Shows completion	❌ Not implemented

Gap Details:

• ❌ Writing state not persisted to post_meta for resume
• ❌ No in_progress flag detection on load
• ❌ No completion status check and SEO prompt

---

2. Mode System

Spec Mode	Current Implementation	Status
chat	✅ Full implementation	Done
planning	✅ Full implementation	Done
writing	✅ Full implementation	Done
refinement	⚠️ Basic block refinement	Partial
seo	❌ No dedicated SEO mode	Missing

Current Modes in sidebar.js:

const validModes = ['chat', 'planning', 'writing', 'writing_section'];
// Missing: refinement, seo

Gap Details:

• ❌ No dedicated seo mode - SEO is scattered in UI, not a mode
• ❌ No refinement mode - only block refinement exists
• ❌ No mode history stack (for undo)
• ❌ Mode transitions not enforced (user can go anywhere)

---

3. Context Management

Spec Component	Implementation	Status
Chat History Context	✅ Implemented	Done
Plan Context	✅ Implemented	Done
Focus Keyword Context	✅ Implemented	Done
Context Optimization (Summarization)	✅ /summarize-context exists	Done
Intent Detection	✅ /detect-intent exists	Done
Context Indicator (UI)	❌ Not visible	Missing

Gap Details:

• ❌ No context indicator showing message/token count
• ❌ No visual feedback when context is optimized
• ❌ Context optimization not triggered automatically

---

4. Intent Detection

Spec Intent	Current	Status
create_outline	✅ Working	Done
write_article	⚠️ Partial	Partial
refine_content	⚠️ Partial	Partial
add_section	❌ Not detected	Missing
clarify	❌ Not detected	Missing
continue_chat	✅ Fallback	Done

Backend Handler (line 5627):

public function handle_detect_intent( $request ) {
    // Returns intent from AI
    // Valid intents: create_outline, start_writing, refine_content, continue_chat, clarify
}

Gap Details:

• ❌ add_section not in valid intents
• ❌ clarify not handled
• ❌ Contextual action buttons not consistently shown

---

5. Outline System

Spec Feature	Implementation	Status
Outline data structure	✅ Basic	Done
Section metadata	⚠️ Partial	Partial
Version tracking	❌ Not implemented	Missing
Status tracking	⚠️ Basic	Partial
Drag-to-reorder	❌ Not implemented	Missing
Inline editing	❌ Not implemented	Missing

Current Outline Structure (simplified):

// In sidebar.js - basic structure
{
  sections: [
    { id, heading, type, description, key_points, status }
  ]
}

Spec Outline Structure (more complete):

{
  metadata: { id, title, focus_keyword, created_at, updated_at, version, status },
  sections: [
    {
      id, index, heading, type, description,
      key_points, target_word_count, actual_word_count,
      status, content, refinement_notes
    }
  ],
  seo_notes: { primary_keyword, secondary_keywords, ... }
}

Gap Details:

• ❌ No version tracking on outline changes
• ❌ No actual_word_count tracking
• ❌ No refinement_notes per section
• ❌ No seo_notes in outline structure
• ❌ No interactive reordering

---

6. Writing Pipeline

Spec Component	Implementation	Status
Section writing loop	✅ Implemented	Done
Writing state machine	⚠️ Basic	Partial
Pause/Resume	⚠️ Basic	Partial
Abort handling	⚠️ Basic	Partial
Block-level writing	❌ Not implemented	Missing
Writing progress persistence	❌ Not to post_meta	Missing

Current State:

• Writing state exists in React state (agentMode === 'writing')
• resume parameter exists for regenerating
• sectionInsertIndexRef tracks where to insert
• No full state machine (IDLE → WRITING → PAUSED → COMPLETED)

Gap Details:

• ❌ Writing state NOT saved to post_meta (lost on refresh)
• ❌ No current_section_index persistence
• ❌ No sections_written[] tracking
• ❌ No resume from exact point on page reload

---

7. Refinement System

Refinement Type	Implementation	Status
Block Refinement	✅ Full implementation	Done
Section Refinement	❌ Not implemented	Missing
Article Refinement	❌ Not implemented	Missing
SEO Refinement	❌ Not implemented	Missing
Style Refinement	❌ Not implemented	Missing
Multi-Pass Refinement	❌ Not implemented	Missing

Current Implementation:

• Block refinement via /refine-block endpoint (line 2412)
• Uses @mention syntax to select blocks
• Context-aware (includes plan + chat history)
• 3-pass approach mentioned in DISTRIBUTION_STRATEGY but not implemented

Gap Details:

• ❌ No article-wide refinement
• ❌ No multi-pass (clarity → SEO → quality)
• ❌ No diff display for user approval
• ❌ No selective acceptance of changes

---

8. SEO Handler System

SEO Component	Implementation	Status
Meta Title Generation	⚠️ Via chat command	Partial
Meta Description Generation	⚠️ Via chat command	Partial
Focus Keyword Integration	✅ Done	Done
Keyword Density Analyzer	❌ Not implemented	Missing
Content Length Checker	❌ Not implemented	Missing
Heading Structure Checker	❌ Not implemented	Missing
FAQ Generation	❌ Not implemented	Missing
Schema Markup	❌ Not implemented	Missing

Current SEO Implementation:

• Focus keyword stored in postConfig
• Used in context for generation
• seo_focus_keyword field in settings
• No dedicated SEO analysis or suggestions

Gap Details:

• ❌ No SEO audit score
• ❌ No SEO preview (Google snippet)
• ❌ No FAQ generation with schema
• ❌ No FAQ schema markup
• ❌ No Article schema injection
• ❌ No breadcrumb schema

---

9. GEO (Generative Engine Optimization) Handler

GEO Component	Implementation	Status
GEO Score Calculation	❌ Not implemented	Missing
Directness Check	❌ Not implemented	Missing
Structure Check	❌ Not implemented	Missing
Authority Check	❌ Not implemented	Missing
Clarity Check	❌ Not implemented	Missing
GEO Improvement Suggestions	❌ Not implemented	Missing

Note: GEO is a new concept (2024+) for AI-generated search results (Google SGE, Bing Chat).

Gap Details:

• ❌ Completely missing
• Would need scoring system 0-100
• Target 80+ for AI Overview eligibility
• Suggestions for improvement

---

10. Markdown Rendering System

Renderer Feature	Implementation	Status
Markdown to HTML	✅ Implemented (markdown-it)	Done
Syntax highlighting	❌ Not implemented	Missing
Collapsible headings	❌ Not implemented	Missing
Quick copy button	❌ Not implemented	Missing
WYSIWYG Preview mode	❌ Not implemented	Missing
Split View mode	❌ Not implemented	Missing
Code block language detection	❌ Not implemented	Missing

Current Implementation:

// sidebar.js line 4975
const markdownToHtml = (markdown) => {
    // Uses markdown-it library
    // Uses DOMPurify for sanitization
}

Gap Details:

• ❌ No toggle between Preview/Markdown/Split modes
• ❌ No code syntax highlighting (highlight.js)
• ❌ No copy-to-clipboard for sections
• ❌ No @mention highlighting in preview

---

Summary: Missing Features by Priority

🔴 HIGH PRIORITY (Core Functionality)

1. Writing State Persistence ✅ DONE

   • Save to post_meta: current_section_index, sections_written[], content
   • Enable seamless resume after page reload

2. SEO Mode (Dedicated) ✅ DONE

   • Create SEO tab/mode in sidebar
   • Meta title/description generation
   • SEO preview (Google snippet)

3. SEO Handler Components ✅ DONE

   • FAQ generation (via SEO tab)
   • Schema markup (Article, FAQ, Breadcrumb) - partial
   • Keyword density checker

🟡 MEDIUM PRIORITY (Enhanced UX)

4. Outline Enhancement ✅ DONE

   • Version tracking ✅
   • Drag-to-reorder sections ✅
   • Inline editing ✅
   • actual_word_count tracking ✅

5. Refinement System Expansion ✅ DONE

   • Article-wide refinement ✅
   • Multi-pass refinement (3 stages) ✅
   • Refinement action buttons ✅

6. Context Optimization UI ✅ DONE

   • Context indicator (message count, token estimate)
   • Visual feedback when context is optimized

🟢 LOW PRIORITY (Polish)

7. Markdown Renderer Enhancement ✅ DONE (partial)

   • Copy button for sections ✅

8. GEO Handler ✅ DONE

   • GEO scoring system ✅
   • 5-checks scoring (Directness, Structure, Authority, Clarity, Completeness) ✅
   • AI Overview eligibility indicator ✅
   • Improvement suggestions ✅

---

Implementation Roadmap

Phase 1: Core Foundation (Critical) ✅ COMPLETE
├── 1.1 Writing State Persistence to post_meta ✅ DONE
├── 1.2 SEO Mode (Dedicated tab) ✅ DONE
├── 1.3 Meta Title/Description Generator ✅ DONE
└── 1.4 SEO Preview (Google snippet) ✅ DONE

Phase 2: SEO Handler ✅ COMPLETE
├── 2.1 FAQ Generation ✅ DONE (via SEO tab)
├── 2.2 Schema Markup (Article, FAQ) ✅ PARTIAL
├── 2.3 Keyword Density Checker ✅ DONE
└── 2.4 SEO Audit Score ✅ DONE

Phase 3: Outline Enhancement ✅ COMPLETE
├── 3.1 Version Tracking ✅ DONE
├── 3.2 Drag-to-Reorder ✅ DONE
├── 3.3 Inline Editing ✅ DONE
└── 3.4 Word Count Tracking ✅ DONE

Phase 4: Refinement Expansion ✅ COMPLETE
├── 4.1 Article-Wide Refinement ✅ DONE
├── 4.2 Multi-Pass Refinement ✅ DONE
└── 4.3 Refinement Actions UI ✅ DONE

Phase 5: Polish ✅ COMPLETE
├── 5.1 Context Indicator UI ✅ DONE
├── 5.2 Copy Button ✅ DONE
└── 5.3 GEO Handler ✅ DONE

Phase 6: WP 7.0 AI Integration ✅ COMPLETE
├── 6.1 WP AI Client Detection ✅ DONE
├── 6.2 Backward-Compatible Wrapper ✅ DONE
├── 6.3 REST Endpoints for Title/Excerpt ✅ DONE
└── 6.4 Settings Integration ✅ DONE

---

Files to Modify

File	Changes Needed
assets/js/sidebar.js	State persistence, SEO mode, context indicator
includes/class-gutenberg-sidebar.php	SEO endpoints, schema generation
assets/css/sidebar.css	New UI components
views/settings/tab-general.php	SEO settings

---

Analysis Completed: 2026-05-17 Next Action: Choose which gap to address first (recommended: 1.1 Writing State Persistence)