contetn prompt udpate

2026-01-15 10:01:19 +00:00
parent b62350b8e0
commit 22f7bdaa23
4 changed files with 938 additions and 1 deletions
--- a/PROMPT_ALIGNMENT_SUGGESTIONS.md
+++ b/PROMPT_ALIGNMENT_SUGGESTIONS.md
@@ -0,0 +1,425 @@
+# AI Prompt Alignment Suggestions
+
+**Date:** January 15, 2026
+
+## 🚨 CRITICAL FINDING: Data Loss Between Idea Generation & Content Generation
+
+**The Problem:** The idea generation AI creates detailed outlines with 6-10 H2 sections, but this outline structure is **never stored in the database**. Only basic fields (title, description text, keywords) are saved. When content generation runs, it has NO ACCESS to:
+- The planned section count (6? 8? 10?)
+- The section outline structure (h2_topic, coverage details)
+- The primary focus keywords
+- The covered keywords  
+- The target word count
+
+**Result:** Content generator uses a fixed template (6 sections, 1000-1200 words) that conflicts with the variable planning done by ideas generator (6-10 sections, 1200-1800 words).
+
+**Solution:** Either add a JSONField to store the complete idea structure, OR update the content prompt to work with limited information and pass available keyword/word count data.
+
+---
+
+## Executive Summary
+
+After analyzing the current **Ideas Generation** and **Content Generation** prompts from the database, I've identified key areas where these prompts need better alignment to ensure consistency in content output.
+
+---
+
+## Current State Analysis
+
+### Ideas Generation Prompt
+- Generates 3-7 content ideas per cluster
+- Defines 6-10 H2 sections per idea
+- Targets 1-2 primary focus keywords + 2-3 covered keywords (3-5 total)
+- AI-determined word count based on sections/keywords
+- Emphasizes completely different keywords per idea
+- Outputs strategic outline only (no detailed H3/formatting)
+
+### Content Generation Prompt
+- Targets 1000-1200 words
+- Requires exactly 6 H2 sections
+- Has rigid section format requirements (2 paragraphs, 2 lists, 1 table)
+- Detailed HTML structure specifications
+- Strict word count per paragraph (50-80 words)
+- Includes specific formatting rules for lists and tables
+
+---
+
+## Key Inconsistencies Identified
+
+### 1. **Section Count Mismatch**
+- **Ideas Prompt:** 6-10 H2 sections (variable, AI-determined)
+- **Content Prompt:** Exactly 6 H2 sections (fixed)
+- **Issue:** Content generator cannot accommodate ideas with 7-10 sections
+
+### 2. **Word Count Flexibility**
+- **Ideas Prompt:** AI-determined based on topic complexity (typically 1200-1800 words)
+- **Content Prompt:** Fixed 1000-1200 words
+- **Issue:** Complex topics with 8-10 sections cannot fit in 1000-1200 words
+
+### 3. **Format Variety vs. Fixed Pattern**
+- **Ideas Prompt:** No formatting specifications (lets content generator decide)
+- **Content Prompt:** Rigid format (2 paragraphs, 2 lists, 1 table distributed)
+- **Issue:** Some topics need more lists/tables, others need more narrative
+
+### 4. **Keyword Coverage Alignment**
+- **Ideas Prompt:** 3-5 keywords total (1-2 primary + 2-3 covered)
+- **Content Prompt:** Primary keyword + secondary keywords (no clear limit)
+- **Alignment:** This is actually okay, but needs clearer instruction
+
+---
+
+## Suggested Changes to Content Generation Prompt
+
+### Change 1: Dynamic Section Count
+**Current:**
+```
+### 1. WORD COUNT: 1000-1200 words target
+- Write 6 H2 sections
+```
+
+**Suggested:**
+```
+### 1. WORD COUNT AND SECTIONS
+
+**Use the section count from the provided outline:**
+- The outline specifies the number of H2 sections to write
+- Typically 6-10 H2 sections based on topic complexity
+- Write ALL sections from the outline
+
+**Word count calculation:**
+- Base: 150-180 words per H2 section
+- Introduction: 100-150 words
+- Total = (Number of H2 sections × 170) + 125
+- Example: 6 sections = ~1,145 words | 8 sections = ~1,485 words | 10 sections = ~1,825 words
+```
+
+### Change 2: Flexible Format Distribution
+**Current:**
+```
+### 2. SECTION FORMAT VARIETY
+**For 6 H2 sections, distribute as:**
+- 2 sections: Paragraphs ONLY 
+- 2 section: Paragraphs + Lists
+- 1 section: Paragraphs + Tables
+```
+
+**Suggested:**
+```
+### 2. SECTION FORMAT VARIETY
+
+**Format distribution (scales with section count):**
+
+**For 6-7 sections:**
+- 3-4 sections: Paragraphs ONLY
+- 2 sections: Paragraphs + Lists
+- 1 section: Paragraphs + Tables
+
+**For 8-9 sections:**
+- 4-5 sections: Paragraphs ONLY
+- 2-3 sections: Paragraphs + Lists
+- 1-2 sections: Paragraphs + Tables
+
+**For 10+ sections:**
+- 5-6 sections: Paragraphs ONLY
+- 3 sections: Paragraphs + Lists
+- 2 sections: Paragraphs + Tables
+
+**Rules (apply to all counts):**
+- Randomize which sections get which format
+- Never use same pattern for consecutive sections
+- Lists: 4-5 items, 15-20 words each
+- Tables: 4-5 columns, 5-6 rows with real data
+- Use block quotes randomly in non-table sections
+```
+
+### Change 3: Input Structure Alignment - CRITICAL FINDING
+
+**What's Currently Output in [IGNY8_IDEA]:**
+
+Based on code analysis (`backend/igny8_core/ai/functions/generate_content.py`), here's what's actually being passed:
+
+```python
+# From generate_content.py build_prompt():
+idea_data = f"Title: {task.title or 'Untitled'}\n"
+if task.description:
+    idea_data += f"Description: {task.description}\n"
+idea_data += f"Content Type: {task.content_type or 'post'}\n"
+idea_data += f"Content Structure: {task.content_structure or 'article'}\n"
+```
+
+**Current Output Format (Plain Text):**
+```
+Title: How to Build an Email List from Scratch
+Description: This guide covers the fundamentals of list building...
+Content Type: post
+Content Structure: guide
+```
+
+**What's Available But NOT Being Passed:**
+
+The ContentIdeas model has these fields:
+- ✅ `primary_focus_keywords` (CharField - "email list building")
+- ✅ `target_keywords` (CharField - "subscriber acquisition, lead magnets")
+- ✅ `estimated_word_count` (IntegerField - 1500)
+- ✅ `content_type` (CharField - "post")
+- ✅ `content_structure` (CharField - "guide")
+
+But the outline structure (intro_focus, main_sections array) is **NOT stored anywhere**:
+- ❌ No outline JSON stored in ContentIdeas model
+- ❌ No outline JSON stored in Tasks model
+- ❌ The AI generates the outline but it's only in the API response, never persisted
+
+**The Root Problem:**
+
+1. **Ideas Generator outputs** full JSON with outline:
+```json
+{
+  "title": "...",
+  "description": {
+    "overview": "...",
+    "outline": {
+      "intro_focus": "...",
+      "main_sections": [
+        {"h2_topic": "...", "coverage": "..."},
+        {"h2_topic": "...", "coverage": "..."},
+        ...6-10 sections...
+      ]
+    }
+  },
+  "primary_focus_keywords": "...",
+  "covered_keywords": "..."
+}
+```
+
+2. **Only these get saved** to ContentIdeas:
+   - `idea_title` = title
+   - `description` = description.overview (NOT the outline!)
+   - `primary_focus_keywords` = primary_focus_keywords
+   - `target_keywords` = covered_keywords
+   - `estimated_word_count` = estimated_word_count
+
+3. **Content Generator receives** (from Tasks):
+   - Just title and description text
+   - No section outline
+   - No keyword info
+   - No word count target
+
+**Why This Causes Misalignment:**
+- Content generator has NO IDEA how many sections were planned (6? 8? 10?)
+- Content generator doesn't know which keywords to target
+- Content generator doesn't know the word count goal
+- Content generator can't follow the planned outline structure
+
+---
+
+**Recommended Solution Path:**
+
+**OPTION A: Store Full Idea JSON** (Best for Long-term)
+
+1. Add JSONField to ContentIdeas model:
+```python
+class ContentIdeas(models.Model):
+    # ... existing fields ...
+    idea_json = models.JSONField(
+        default=dict,
+        blank=True,
+        help_text="Complete idea structure from AI generation (outline, keywords, sections)"
+    )
+```
+
+2. Update generate_ideas.py to save full JSON:
+```python
+# In save_output method:
+content_idea = ContentIdeas.objects.create(
+    # ... existing fields ...
+    idea_json=idea_data,  # Store the complete JSON structure
+)
+```
+
+3. Update generate_content.py to use full structure:
+```python
+# In build_prompt method:
+if task.idea and task.idea.idea_json:
+    # Pass full JSON structure
+    idea_data = json.dumps(task.idea.idea_json, indent=2)
+else:
+    # Fallback to current simple format
+    idea_data = f"Title: {task.title}\nDescription: {task.description}\n"
+```
+
+4. Update Content Generation prompt INPUT section:
+```
+## INPUT
+
+**CONTENT IDEA:**
+[IGNY8_IDEA]
+
+Expected JSON structure:
+{
+  "title": "Article title",
+  "description": {
+    "overview": "2-3 sentence description",
+    "outline": {
+      "intro_focus": "What the introduction should establish",
+      "main_sections": [
+        {"h2_topic": "Section heading", "coverage": "What to cover"},
+        ... array of 6-10 sections ...
+      ]
+    }
+  },
+  "primary_focus_keywords": "1-2 main keywords",
+  "covered_keywords": "2-3 supporting keywords",
+  "estimated_word_count": 1500,
+  "content_type": "post",
+  "content_structure": "guide_tutorial"
+}
+
+**KEYWORD CLUSTER:**
+[IGNY8_CLUSTER]
+
+**KEYWORDS:**
+[IGNY8_KEYWORDS]
+
+**INSTRUCTIONS:**
+- Use the exact number of H2 sections from main_sections array
+- Each H2 section should follow the h2_topic and coverage from the outline
+- Target the word count from estimated_word_count (±100 words)
+- Focus on primary_focus_keywords and covered_keywords for SEO
+```
+
+**OPTION B: Quick Fix - Pass Available Fields** (Can implement immediately without DB changes)
+
+Update generate_content.py:
+```python
+# In build_prompt method:
+idea_data = f"Title: {task.title or 'Untitled'}\n"
+if task.description:
+    idea_data += f"Description: {task.description}\n"
+idea_data += f"Content Type: {task.content_type or 'post'}\n"
+idea_data += f"Content Structure: {task.content_structure or 'article'}\n"
+
+# ADD: Pull from related idea if available
+if task.idea:
+    if task.idea.primary_focus_keywords:
+        idea_data += f"Primary Focus Keywords: {task.idea.primary_focus_keywords}\n"
+    if task.idea.target_keywords:
+        idea_data += f"Covered Keywords: {task.idea.target_keywords}\n"
+    if task.idea.estimated_word_count:
+        idea_data += f"Target Word Count: {task.idea.estimated_word_count}\n"
+```
+
+Then update Content Generation prompt:
+```
+## INPUT
+
+**CONTENT IDEA:**
+[IGNY8_IDEA]
+
+Format:
+- Title: Article title
+- Description: Content overview
+- Content Type: post|page|product
+- Content Structure: article|guide|comparison|review|listicle
+- Primary Focus Keywords: 1-2 main keywords (if available)
+- Covered Keywords: 2-3 supporting keywords (if available)
+- Target Word Count: Estimated words (if available)
+
+**NOTE:** Generate 6-8 H2 sections based on content_structure type. Scale word count to match Target Word Count if provided (±100 words acceptable).
+```
+
+### Change 4: Keyword Usage Clarity
+**Current:**
+```
+## KEYWORD USAGE
+
+**Primary keyword** (identify from title):
+- Use in title, intro, meta title/description
+- Include in 2-3 H2 headings naturally
+- Mention 2-3 times in content (0.5-1% density)
+
+**Secondary keywords** (3-4 from keyword list):
+- Distribute across H2 sections
+- Use in H2/H3 headings where natural
+- 2-3 mentions each (0.3-0.6% density)
+- Include variations and related terms
+```
+
+**Suggested:**
+```
+## KEYWORD USAGE
+
+**Primary focus keywords** (1-2 from IGNY8_IDEA.primary_focus_keywords):
+- Already in the provided title (use it as-is)
+- Include in 2-3 H2 headings naturally (outline already targets this)
+- Mention 2-3 times in content (0.5-1% density)
+
+**Covered keywords** (2-3 from IGNY8_IDEA.covered_keywords):
+- Distribute across H2 sections
+- Use in H2/H3 headings where natural (outline may already include them)
+- 2-3 mentions each (0.3-0.6% density)
+- Include variations and related terms
+
+**Total keyword target:** 3-5 keywords (1-2 primary + 2-3 covered)
+```
+
+### Change 5: Verification Checklist Update
+**Current:**
+```
+## VERIFICATION BEFORE OUTPUT
+
+- [ ] 1000-1200 words ONLY (excluding HTML tags) - STOP if exceeding
+- [ ] 6 H2 sections
+- [ ] Maximum 2 sections with lists
+- [ ] Maximum 2 sections with tables
+```
+
+**Suggested:**
+```
+## VERIFICATION BEFORE OUTPUT
+
+- [ ] Word count matches outline's estimated_word_count (±100 words acceptable)
+- [ ] Number of H2 sections matches outline's main_sections count
+- [ ] Format distribution scales appropriately with section count
+- [ ] All sections from outline are covered
+- [ ] Primary focus keywords (1-2) used correctly
+- [ ] Covered keywords (2-3) distributed naturally
+- [ ] All paragraphs 50-80 words
+- [ ] All lists 4-5 items, 15-20 words each
+- [ ] All tables 4-5 columns, 5-6 rows, real data
+- [ ] No placeholder content anywhere
+- [ ] Meta title <60 chars, description <160 chars
+- [ ] Valid JSON with escaped quotes
+```
+
+---
+
+## Summary of Benefits
+
+### With These Changes:
+1. ✅ **Flexibility:** Content generator can handle 6-10 sections from ideas
+2. ✅ **Consistency:** Section count matches between idea and content generation
+3. ✅ **Scalability:** Word count scales naturally with complexity
+4. ✅ **Quality:** Format variety adapts to content needs
+5. ✅ **Alignment:** Clear keyword strategy (1-2 primary + 2-3 covered = 3-5 total)
+6. ✅ **Maintainability:** One source of truth for section structure (the outline)
+
+### Key Principle:
+**The Ideas Generator is the strategic planner** (decides sections, word count, keywords)
+**The Content Generator is the tactical executor** (follows the plan, adds formatting/depth)
+
+---
+
+## Implementation Notes
+
+- These changes maintain all quality requirements (word count per paragraph, list/table specs, etc.)
+- The rigid structure is replaced with scalable rules that maintain quality at any section count
+- The content generator becomes more flexible while maintaining consistency
+- Both prompts now work together as a cohesive system
+
+---
+
+## Next Steps
+
+1. Update the `content_generation` prompt in the database with suggested changes
+2. Test with various section counts (6, 8, 10 sections) to verify scalability
+3. Monitor output quality to ensure formatting rules scale properly
+4. Consider creating a validation layer that checks idea/content alignment before generation
--- a/backend/igny8_core/ai/functions/generate_content.py
+++ b/backend/igny8_core/ai/functions/generate_content.py
@@ -84,7 +84,7 @@ class GenerateContentFunction(BaseAIFunction):
        
        account = account or task.account
        
-        # Build idea data string
+        # Build idea data string with all available fields
        idea_data = f"Title: {task.title or 'Untitled'}\n"
        if task.description:
            idea_data += f"Description: {task.description}\n"
@@ -93,6 +93,19 @@ class GenerateContentFunction(BaseAIFunction):
        idea_data += f"Content Type: {task.content_type or 'post'}\n"
        idea_data += f"Content Structure: {task.content_structure or 'article'}\n"
        
+        # Add additional fields from related ContentIdea if available
+        if task.idea:
+            if task.idea.primary_focus_keywords:
+                idea_data += f"Primary Focus Keywords: {task.idea.primary_focus_keywords}\n"
+            if task.idea.target_keywords:
+                idea_data += f"Covered Keywords: {task.idea.target_keywords}\n"
+            if task.idea.estimated_word_count:
+                idea_data += f"Estimated Word Count: {task.idea.estimated_word_count}\n"
+        
+        # Fallback: use task.word_count if idea.estimated_word_count not available
+        if 'Estimated Word Count' not in idea_data and task.word_count:
+            idea_data += f"Estimated Word Count: {task.word_count}\n"
+        
        # Build cluster data string
        cluster_data = ''
        if task.cluster:
--- a/content_generation.md
+++ b/content_generation.md
@@ -0,0 +1,232 @@
+# Editorial Content Generator
+
+Generate complete, SEO-optimized HTML content from the provided outline.
+
+---
+
+## INPUT
+
+**CONTENT IDEA:**
+[IGNY8_IDEA]
+
+Format provided:
+- Title: The article title to use
+- Description: Overview of what content should cover
+- Content Type: post|page|product|taxonomy
+- Content Structure: article|guide|comparison|review|listicle|landing_page|etc
+- Primary Focus Keywords: 1-2 main target keywords (if available)
+- Covered Keywords: 2-3 supporting keywords (if available)
+- Estimated Word Count: Target word count from idea planning (if available)
+
+**KEYWORD CLUSTER:**
+[IGNY8_CLUSTER]
+
+**KEYWORDS:**
+[IGNY8_KEYWORDS]
+
+---
+
+## OUTPUT FORMAT
+
+
+{
+  "title": "string",
+  "meta_title": "string (max 60 chars)",
+  "meta_description": "string (max 160 chars)",
+  "content": "string (HTML)",
+  "word_count": integer,
+  "primary_keyword": "string",
+  "secondary_keywords": ["string"],
+  "tags": ["string"],
+  "categories": ["Parent > Child"]
+}
+
+
+---
+
+## CRITICAL REQUIREMENTS
+
+### 1. WORD COUNT AND SECTIONS
+
+**Target word count:**
+- If "Estimated Word Count" is provided in [IGNY8_IDEA], target that count (±100 words acceptable)
+- Otherwise, default to 1000-1200 words
+
+**Section count:**
+- Base: 6 H2 sections (standard)
+- For longer targets (1400+ words): Use 7-8 H2 sections
+- For shorter targets (800-1000 words): Use 5-6 H2 sections
+- Each H2 section: 150-180 words average
+
+**Section breakdown:**
+- Introduction: 100-150 words
+- Each H2 section: 150-180 words
+- Calculate total: (number of H2s × 170) + 125 ≈ target word count
+
+### 2. SECTION FORMAT VARIETY
+
+**Format distribution (scales with section count):**
+
+**For 5-6 H2 sections:**
+- 3 sections: Paragraphs ONLY
+- 2 sections: Paragraphs + Lists
+- 1 section: Paragraphs + Tables
+
+**For 7-8 H2 sections:**
+- 4-5 sections: Paragraphs ONLY
+- 2 sections: Paragraphs + Lists
+- 1-2 sections: Paragraphs + Tables
+
+* Use block quote element randomly in sections where table is not used
+* Provide the most insightful information within block quotes
+
+**Rules:**
+- Randomize which sections get which format
+- Never use same pattern for consecutive sections
+- Maximum 2-3 sections can have lists
+- Maximum 1-2 sections can have tables
+- Lists: 4-5 items, 15-20 words each
+- Tables: 4-5 columns, 5-6 rows with real data
+
+### 3. CONTENT DEPTH (NOT surface explanations)
+
+**Every paragraph must:**
+- Be 50-60 words 
+- Explain HOW/WHY, not just WHAT
+- Include specific numbers, examples, mechanisms
+- Provide actionable insights
+
+**Lists must contain:**
+- 4-5 items maximum
+- Each item: 15-20 words
+- Specific details with real examples
+- Technical specifics (measurements, ranges, capabilities)
+
+**Tables must contain:**
+- 4-5 columns
+- 5-6 rows 
+- Real comparative data (prices, specs, measurements)
+- No vague terms (avoid "good", "quality", "effective")
+
+---
+
+## HTML STRUCTURE
+
+### Introduction Format:
+
+<p><em>[Hook: 40-50 words]</em></p>
+<p>[Paragraph 1: 50-70 words with primary keyword]</p>
+<p>[Paragraph 2: 50-60 words]</p>
+<p>[Paragraph 3: 50-60 words]</p>
+
+
+### H2 Section Format:
+
+<h2>[Heading]</h2>
+<p>[Opening: 50-70 words explaining core concept]</p>
+
+<!-- Choose ONE format per section based on variety requirement -->
+
+<!-- Option A: Paragraphs only (use for 2 sections) -->
+<h3>[Subheading]</h3>
+<p>[60-70 words of detailed explanation]</p>
+<h3>[Subheading]</h3>
+<p>[60-70 words of detailed explanation]</p>
+
+<!-- Option B: Paragraph + List (use for 1-2 sections max) -->
+<h3>[Subheading]</h3>
+<p>[50-70 words introducing the list]</p>
+<ul>
+  <li>[15-20 word item with specific details]</li>
+  <!-- 4-5 items total -->
+</ul>
+
+<!-- Option C: Paragraph + Table (use for 1-2 sections max) -->
+<h3>[Subheading]</h3>
+<p>[50-70 words introducing the table]</p>
+<table>
+<thead>
+  <tr><th>Col1</th><th>Col2</th><th>Col3</th><th>Col4</th></tr>
+</thead>
+<tbody>
+  <tr><td>Data</td><td>Data</td><td>Data</td><td>Data</td></tr>
+  <!-- 5-6 rows total -->
+</tbody>
+</table>
+
+<p>[Closing: 50-70 words synthesizing the section]</p>
+
+
+**Valid HTML tags only:** `<h2>`, `<h3>`, `<p>`, `<em>`, `<strong>`, `<ul>`, `<ol>`, `<li>`, `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`
+
+---
+
+## WRITING RULES
+
+### DO:
+✓ Use specific examples, brands, models, numbers
+✓ Explain mechanisms and technical details
+✓ Include real data (prices, percentages, measurements)
+✓ Write naturally with varied sentence length
+✓ Use active voice
+✓ Connect ideas logically between paragraphs
+
+### DON'T:
+✗ Generic openings ("In today's world...")
+✗ Repeat H2/H3 in first sentence
+✗ Robotic transitions ("First...", "Second...")
+✗ Filler phrases ("It's important to note...")
+✗ Placeholder content ("Brand A", "Model X", "Data 1")
+✗ Paragraphs under 40 words or over 80 words
+✗ Lists with more than 6 items or items over 25 words
+✗ Tables with more than 5 columns or 6 rows
+✗ Writing more than 1200 words total
+
+---
+
+## KEYWORD USAGE
+
+**Primary focus keywords** (from [IGNY8_IDEA] if provided, otherwise identify from title):
+- Use in title (already provided in [IGNY8_IDEA])
+- Use in intro, meta title/description
+- Include in 2-3 H2 headings naturally
+- Mention 2-3 times in content (0.5-1% density)
+
+**Covered keywords** (from [IGNY8_IDEA] if provided, otherwise select 3-4 from [IGNY8_KEYWORDS]):
+- Distribute across H2 sections
+- Use in H2/H3 headings where natural
+- 2-3 mentions each (0.3-0.6% density)
+- Include variations and related terms
+
+**Total keyword target:** 3-5 keywords (1-2 primary + 2-3 covered)
+
+---
+
+## METADATA
+
+**Meta Title:** Under 60 chars, primary keyword included, action-oriented
+**Meta Description:** 140-160 chars, primary keyword, clear value proposition
+**Tags:** 5 tags, 2-4 words each, lowercase, topically relevant
+**Categories:** 1-2 in format "Parent > Child"
+
+---
+
+## VERIFICATION BEFORE OUTPUT
+
+- [ ] Word count matches Estimated Word Count from [IGNY8_IDEA] (±100 words), or 1000-1200 if not provided
+- [ ] Number of H2 sections: 5-8 based on target word count
+- [ ] Format distribution scales with section count
+- [ ] All paragraphs 50-80 words
+- [ ] All lists 4-5 items, 15-20 words each
+- [ ] All tables 4-5 columns, 5-6 rows, real data
+- [ ] No placeholder content anywhere
+- [ ] Primary focus keywords from [IGNY8_IDEA] used correctly (or identified from title)
+- [ ] Covered keywords from [IGNY8_IDEA] distributed naturally (or selected from [IGNY8_KEYWORDS])
+- [ ] Meta title <60 chars, description <160 chars
+- [ ] Valid JSON with escaped quotes
+
+---
+
+## IMPORTANT
+
+Return ONLY valid JSON. No explanatory text. Ensure word_count reflects actual content words.
--- a/idea_genration.md
+++ b/idea_genration.md
@@ -0,0 +1,267 @@
+# SEO Content Idea Generator
+
+You are a content strategist. Generate content ideas and simple outlines for keyword clusters. The actual content will be written by a separate system.
+
+---
+
+## INPUT FORMAT
+
+**Clusters to analyze:**
+[IGNY8_CLUSTERS]
+
+**Keywords in each cluster:**
+[IGNY8_CLUSTER_KEYWORDS]
+
+---
+
+## OUTPUT REQUIREMENTS
+
+Generate **3-7 content ideas per cluster** based on the number of unique major topics within the cluster:
+- Analyze the cluster keywords to identify distinct major topics
+- Generate one idea per major topic (not for minor keyword variations)
+- Each idea must target completely different major topics/angles
+
+**Important**: 
+- Focus on **major topic differences**, not minor keyword variations
+- Each idea must cover **completely different keywords** from the cluster
+- Generate fewer ideas for focused clusters, more for broad clusters
+
+---
+
+## OUTPUT JSON OBJECT STRUCTURE
+
+{
+  "ideas": [
+    {
+      "title": "[Compelling title with primary focus keyword]",
+      "description": {
+        "overview": "[2-3 sentence description of what this content covers and its unique angle]",
+        "outline": {
+          "intro_focus": "[What the introduction should establish]",
+          "main_sections": [
+            {
+              "h2_topic": "[Section topic/angle]",
+              "coverage": "[What this section should cover - 1 sentence]"
+            }
+          ]
+        }
+      },
+      "primary_focus_keywords": "[1-2 main keywords this content targets, comma-separated]",
+      "covered_keywords": "[2-3 additional supporting keywords, comma-separated]",
+      "content_type": "post|page",
+      "content_structure": "guide_tutorial|how_to|comparison|review|top_listicle|question",
+      "cluster_id": "[Cluster ID number]",
+      "estimated_word_count": "[AI determined based on sections and keyword coverage]"
+    }
+  ]
+}
+
+---
+
+## KEYWORD REQUIREMENTS
+
+### Primary Focus Keywords (1-2 per idea)
+The main keywords this content primarily targets:
+- **MUST appear in the title**
+- **MUST appear in at least 2 different H2 section headings**
+- These drive the content's core topic
+- These have the highest search priority
+
+### Covered Keywords (2-3 per idea)
+Additional supporting keywords from the cluster:
+- Include related search terms from cluster
+- Include natural variations and long-tail keywords
+- Should also appear in H2 section headings where natural
+
+**Total Keywords Per Idea**: 3-5 maximum (1-2 primary + 2-3 covered)
+
+### Keyword Distribution Strategy
+- **Each of the ideas must cover completely different keywords**
+- **Focus on major topic differences, not minor variations**
+- Minimize overlap between ideas in the same cluster
+- Each idea should target a distinct subtopic within the cluster
+
+**Example for "Email Marketing" cluster:**
+
+**Idea 1**: "How to Build an Email List from Scratch"
+- primary_focus_keywords: "email list building"
+- covered_keywords: "subscriber acquisition, lead magnets"
+- Total: 3 keywords covering list growth subtopic
+
+**Idea 2**: "Best Email Marketing Platforms Compared"
+- primary_focus_keywords: "email marketing platforms"
+- covered_keywords: "email software, automation tools"
+- Total: 3 keywords covering platform selection subtopic
+
+**Idea 3**: "Email Campaign Strategy Guide"
+- primary_focus_keywords: "email campaigns"
+- covered_keywords: "campaign optimization, conversion tactics"
+- Total: 3 keywords covering campaign execution subtopic
+
+---
+
+## CONTENT STRUCTURE TYPES
+
+### Guide/Tutorial
+- **Purpose**: Step-by-step educational content
+- **Coverage**: Process-oriented, actionable steps
+- **Sections**: AI determines based on content depth and keywords
+
+### How-To
+- **Purpose**: Solve a specific problem
+- **Coverage**: Problem → solution framework
+- **Sections**: AI determines based on complexity
+
+### Comparison
+- **Purpose**: Compare options/alternatives
+- **Coverage**: Feature analysis, pros/cons, recommendations
+- **Sections**: AI determines based on items compared
+
+### Review
+- **Purpose**: Evaluate specific products/services
+- **Coverage**: Features, testing, verdict
+- **Sections**: AI determines based on review depth
+
+### Top Listicle
+- **Purpose**: Curated ranked list
+- **Coverage**: Criteria, ranked items, selection guide
+- **Sections**: AI determines based on list size
+
+### Question
+- **Purpose**: Answer specific query
+- **Coverage**: Question → context → answer → implications
+- **Sections**: AI determines based on answer complexity
+
+---
+
+## WORD COUNT DETERMINATION
+
+**AI must determine estimated_word_count based on:**
+- Number of H2 sections outlined
+- Number of keywords to be covered (3-5 total)
+- Content structure complexity
+- Topic depth requirements
+
+**Guideline**: More sections + more keywords = higher word count
+**Range**: Typically 1200-1800 words, but AI decides the optimal length
+
+---
+
+## OUTLINE REQUIREMENTS
+
+For each idea, provide:
+
+1. **Intro Focus**: What angle/hook the introduction should take (1 sentence)
+
+2. **Main Sections**: Variable number of H2 topics based on content needs
+   - **CRITICAL**: Primary focus keywords must appear in at least 2 different H2 section headings
+   - Each covered keyword should appear in H2 headings where natural
+   - Integrate keywords naturally into section titles
+   - 1 sentence on what each section should cover
+   - AI determines optimal section count for topic coverage
+   - No need for H3 breakdown (content generator will handle)
+   - No formatting details (content generator will handle)
+
+3. **Section approach**:
+   - Foundation/basics sections (if needed)
+   - Core concept sections (main body)
+   - Application/implementation sections
+   - Advanced/future sections (if appropriate)
+   - AI determines which sections are necessary
+
+---
+
+## SECTION COUNT DETERMINATION
+
+**Must contain 6 - 10 H2 sections based on:**
+
+- Content structure type requirements
+- Number of keywords to cover (3-5 total)
+- Topic complexity and depth
+- Natural content flow
+
+**evaluate each idea independently**
+
+---
+
+## TITLE GUIDELINES
+
+- **MUST include primary focus keywords (1-2 keywords)**
+- 50-65 characters ideal
+- Compelling and specific
+- Match content structure type:
+  - How-to: "How to [Action] [Object/Goal]"
+  - Comparison: "[X] vs [Y]: Which Is Better?"
+  - Review: "[Product/Service] Review: [Key Benefit]"
+  - Listicle: "[Number] Best [Items] for [Purpose]"
+  - Question: "[Question Using Primary Keyword]?"
+  - Guide: "[Complete/Ultimate] Guide to [Topic]"
+
+---
+
+## CONTENT ANGLE REQUIREMENTS
+
+Each idea must have a **unique angle**:
+
+✓ Different content structure types across ideas
+✓ Different major topics (not just minor keyword variations)
+✓ Different target intents (informational, commercial, navigational)
+✓ Different depth levels (overview vs deep-dive)
+✓ No duplicate section topics across ideas in same cluster
+✓ **Completely different keyword sets targeting distinct subtopics**
+
+---
+
+## GENERATING 3-7 IDEAS
+
+**Decision criteria for idea count:**
+- **3 ideas**: Narrow, focused cluster with 1-3 major subtopics
+- **4-5 ideas**: Moderate cluster with 4-5 major subtopics
+- **6-7 ideas**: Broad cluster with 6+ distinct major subtopics
+
+**What counts as a major topic difference:**
+✓ List building vs Platform selection vs Campaign strategy (MAJOR - generate separate ideas)
+✓ "Best tools" vs "Top platforms" (MINOR variation - combine into one idea)
+✓ Email automation vs Email design vs Email analytics (MAJOR - generate separate ideas)
+✓ "How to write emails" vs "Email writing tips" (MINOR variation - combine into one idea)
+
+---
+
+## QUALITY CHECKS
+
+Before finalizing, verify:
+- ✓ 3-7 ideas per cluster (based on major topic count)
+- ✓ Each idea targets a distinct major topic
+- ✓ Each idea has unique content_structure type
+- ✓ Title includes 1-2 primary focus keywords
+- ✓ 1-2 primary_focus_keywords listed per idea
+- ✓ 2-3 covered_keywords listed per idea (3-5 total keywords maximum)
+- ✓ **Primary focus keywords appear in title AND at least 2 H2 headings**
+- ✓ **Each idea covers completely different keywords from cluster**
+- ✓ Content angles represent major topic differences
+- ✓ AI determined optimal section count for each idea
+- ✓ AI determined word count based on sections and keywords
+- ✓ Valid JSON format
+
+---
+
+## OUTPUT FORMAT
+
+Return ONLY valid JSON with no comments or explanations.
+
+The "outline" object should be simple and high-level - just enough to guide the content generator. The actual detailed structure, formatting, H3 subsections, lists, tables, etc. will be handled by the content generation system.
+
+---
+
+## WHAT NOT TO INCLUDE
+
+❌ Detailed H3 subsections (content generator handles this)
+❌ Specific formatting instructions (paragraph/list/table details)
+❌ Word count per section (content generator calculates)
+❌ Detailed content descriptions (keep coverage notes brief)
+❌ HTML structure (content generator outputs HTML)
+❌ Introduction hook text (content generator writes this)
+❌ Hardcoded section counts (AI determines optimal count)
+❌ Hardcoded word count ranges (AI determines based on content needs)
+
+Keep outlines strategic and high-level. Let the content generation system handle tactical execution.