💡 Ready to create an outline?
- -⚠️ You need an outline first
- -💡 Ready to write the article?
- -💡 Use @block to refine specific sections
-; ?>){kind=icon}
- - v · - -
-| - | - | - | - | - | - | - | - |
|---|
${escapeHtml(record.created_at)}- Brave Search API. Free tier: 2,000 queries/month.', 'wp-agentic-writer' ) ), - 'https://brave.com/search/api/' - ); ?> -
-Reuses search results for identical queries. Can save 40-60% on costs.
-How long to keep cached search results (1-90 days).
-Stop searches when monthly cost exceeds this amount.
-' . wp_kses_post( $args['description'] ) . '
'; - } -} - -public function clarification_quiz_section_callback() { - echo '' . __( 'Configure when and how the clarification quiz appears to gather context for better article generation.', 'wp-agentic-writer' ) . '
'; -} -``` - -**Hook Integration:** -Add to `__construct()` or settings initialization: -```php -add_action( 'admin_init', array( $this, 'add_clarification_quiz_settings' ), 20 ); -``` - ---- - -## Phase 2: Update Clarity Check System Prompt - -### File: `includes/class-gutenberg-sidebar.php` - -**Location:** Lines 1195-1231 (check_clarity method) - -**Replace the current system prompt with:** - -```php -$required_categories = get_option( 'required_context_categories', array( - 'target_outcome', - 'target_audience', - 'tone', - 'content_depth', - 'expertise_level', - 'content_type', - 'pov' -) ); - -$threshold = get_option( 'clarity_confidence_threshold', '0.6' ); -$enabled = get_option( 'enable_clarification_quiz', true ); - -// If quiz is disabled, always return clear -if ( ! $enabled ) { - return new WP_REST_Response( - array( - 'result' => array( - 'is_clear' => true, - 'confidence' => 1.0, - 'questions' => array() - ), - ), - 200 - ); -} - -$system_prompt = "You are an expert editor who determines if an article request has sufficient context to write effectively. - -Evaluate the user's request and determine which context categories are clear: - -CATEGORIES TO EVALUATE: -1. target_outcome - What should this content achieve? (education/marketing/sales/entertainment/brand_awareness) -2. target_audience - Who is reading this? (demographics, role, knowledge level) -3. tone - How should we sound? (formal/casual/technical/friendly/professional/conversational) -4. content_depth - How comprehensive? (quick_overview/standard_guide/detailed_analysis/comprehensive) -5. expertise_level - Reader's knowledge? (beginner/intermediate/advanced/expert) -6. content_type - What format? (tutorial/how_to/opinion/comparison/listicle/case_study/news_analysis) -7. pov - Whose perspective? (first_person/third_person/expert_voice/neutral) - -For each MISSING category, generate a clarifying question using PREDEFINED OPTIONS. -Use 'single_choice' or 'multiple_choice' types - NEVER 'open_text'. - -QUESTION STRUCTURE: -{ - 'id': 'q1', - 'category': 'target_outcome', - 'question': 'What is the primary goal of this content?', - 'type': 'single_choice', - 'options': [ - { 'value': 'Education - Teach something new', 'default': true }, - { 'value': 'Marketing - Promote a product/service', 'default': false }, - { 'value': 'Sales - Drive conversions/signups', 'default': false }, - { 'value': 'Entertainment - Engage and entertain', 'default': false }, - { 'value': 'Brand Awareness - Build authority/trust', 'default': false } - ] -} - -CONFIDENCE CALCULATION: -- Start at 100% (1.0) -- Subtract 15% for each missing required category -- If confidence < {$threshold}, generate questions for ALL missing categories - -Return ONLY valid JSON with this structure: -{ - 'is_clear': true/false, - 'confidence': 0.0-1.0, - 'missing_categories': ['category1', 'category2'], - 'questions': [ ... ] -} - -No markdown, no explanation - just JSON."; - -$messages = array( - array( - 'role' => 'system', - 'content' => $system_prompt, - ), - array( - 'role' => 'user', - 'content' => "Topic: {$topic}\n\nRequired Categories: " . implode( ', ', $required_categories ) . "\n\nEvaluate this request and determine which context is missing.", - ), -); -``` - ---- - -## Phase 3: Improve Fallback Behavior - -### File: `includes/class-gutenberg-sidebar.php` - -**Location:** Around lines 1603-1615 - -**Add new helper method:** - -```php -/** - * Get default clarification questions when AI fails - * - * @since 0.1.0 - * @param string $topic User's topic. - * @return array Clarification result with default questions. - */ -private function get_default_clarification_questions( $topic ) { - $required_categories = get_option( 'required_context_categories', array( - 'target_outcome', - 'target_audience', - 'tone', - 'content_depth', - 'expertise_level', - 'content_type', - 'pov' - ) ); - - $questions = array(); - $question_id = 1; - - $question_templates = array( - 'target_outcome' => array( - 'category' => 'target_outcome', - 'question' => 'What is the primary goal of this content?', - 'type' => 'single_choice', - 'options' => array( - array( 'value' => 'Education - Teach something new', 'default' => true ), - array( 'value' => 'Marketing - Promote a product/service', 'default' => false ), - array( 'value' => 'Sales - Drive conversions', 'default' => false ), - array( 'value' => 'Entertainment - Engage readers', 'default' => false ), - array( 'value' => 'Brand Awareness - Build authority', 'default' => false ), - ) - ), - 'target_audience' => array( - 'category' => 'target_audience', - 'question' => 'Who is the primary audience for this content?', - 'type' => 'single_choice', - 'options' => array( - array( 'value' => 'General public / Beginners', 'default' => true ), - array( 'value' => 'Professionals in the field', 'default' => false ), - array( 'value' => 'Potential customers', 'default' => false ), - array( 'value' => 'Existing customers/users', 'default' => false ), - array( 'value' => 'Industry peers / Experts', 'default' => false ), - ) - ), - 'tone' => array( - 'category' => 'tone', - 'question' => 'What tone should this content have?', - 'type' => 'single_choice', - 'options' => array( - array( 'value' => 'Professional & Authoritative', 'default' => true ), - array( 'value' => 'Friendly & Conversational', 'default' => false ), - array( 'value' => 'Technical & Detailed', 'default' => false ), - array( 'value' => 'Casual & Entertaining', 'default' => false ), - array( 'value' => 'Formal & Academic', 'default' => false ), - ) - ), - 'content_depth' => array( - 'category' => 'content_depth', - 'question' => 'How comprehensive should this content be?', - 'type' => 'single_choice', - 'options' => array( - array( 'value' => 'Quick overview (500-800 words)', 'default' => false ), - array( 'value' => 'Standard guide (800-1500 words)', 'default' => true ), - array( 'value' => 'Detailed analysis (1500-2500 words)', 'default' => false ), - array( 'value' => 'Comprehensive deep-dive (2500+ words)', 'default' => false ), - ) - ), - 'expertise_level' => array( - 'category' => 'expertise_level', - 'question' => 'What is the target audience\'s expertise level?', - 'type' => 'single_choice', - 'options' => array( - array( 'value' => 'Beginner - No prior knowledge', 'default' => true ), - array( 'value' => 'Intermediate - Basic understanding', 'default' => false ), - array( 'value' => 'Advanced - Deep technical knowledge', 'default' => false ), - array( 'value' => 'Expert - Industry professional', 'default' => false ), - ) - ), - 'content_type' => array( - 'category' => 'content_type', - 'question' => 'What type of content works best for this topic?', - 'type' => 'single_choice', - 'options' => array( - array( 'value' => 'Tutorial / How-to guide', 'default' => true ), - array( 'value' => 'Opinion / Commentary', 'default' => false ), - array( 'value' => 'Comparison / Review', 'default' => false ), - array( 'value' => 'Listicle / Tips', 'default' => false ), - array( 'value' => 'Case study', 'default' => false ), - array( 'value' => 'News analysis', 'default' => false ), - ) - ), - 'pov' => array( - 'category' => 'pov', - 'question' => 'From what perspective should this be written?', - 'type' => 'single_choice', - 'options' => array( - array( 'value' => 'Third person (objective, "it", "they")', 'default' => true ), - array( 'value' => 'First person (personal, "I", "my")', 'default' => false ), - array( 'value' => 'Expert voice (authoritative, experienced)', 'default' => false ), - array( 'value' => 'Neutral / Unbiased', 'default' => false ), - ) - ), - ); - - foreach ( $required_categories as $category ) { - if ( isset( $question_templates[ $category ] ) ) { - $q = $question_templates[ $category ]; - $q['id'] = 'q' . $question_id++; - $questions[] = $q; - } - } - - return array( - 'is_clear' => false, - 'confidence' => 0.0, - 'missing_categories' => $required_categories, - 'questions' => $questions - ); -} -``` - -**Update error handling (lines 1603-1615):** - -```php -if ( is_wp_error( $response ) ) { - // Log error - error_log( 'WP Agentic Writer: Clarity check API error - ' . $response->get_error_message() ); - // Use default questions instead of skipping - return $this->get_default_clarification_questions( $topic ); -} - -if ( null === $result ) { - // Log parse error - error_log( 'WP Agentic Writer: Failed to parse clarity check JSON' ); - // Use default questions instead of skipping - return $this->get_default_clarification_questions( $topic ); -} -``` - ---- - -## Phase 4: Update Frontend Quiz Display - -### File: `assets/js/sidebar.js` - -**Enhancement 1: Add category labels to questions** - -Find the question rendering code and add category display: - -```javascript -// Inside renderClarificationQuestion function -const categoryLabels = { - 'target_outcome': '🎯 Target Outcome', - 'target_audience': '👥 Target Audience', - 'tone': '🎨 Tone of Voice', - 'content_depth': '📏 Content Depth', - 'expertise_level': '📊 Expertise Level', - 'content_type': '📝 Content Type', - 'pov': '👁️ Point of View' -}; - -// Add category badge above question -if (question.category && categoryLabels[question.category]) { - html += 'Writing mode requires an outline to structure your article.
- -- Or switch to to discuss your ideas. -
-