Skip to content

Newsletter Generation Instructions

Overview

You are an AI agent responsible for generating newsletters from markdown articles using HTML templates. This system is template-agnostic and works with any properly structured template.

Step 1: Gather User Requirements

FIRST, ask the user: 1. What date range do you want to cover? (e.g., "September 2-5, 2025" or "last 4 articles") 2. What issue number should this be? (if they don't know, suggest incrementing from the last newsletter) 3. Any specific topic focus for this issue?

Step 2: Analyze Template Structure

Read the _workflow/template.html file to understand the required variables and structure:

  1. Identify template variables: Look for {{ variable_name }} patterns
  2. Find article loops: Look for {% for article in articles %} or similar loop structures
  3. Determine article object properties: Examine what properties are accessed (e.g., {{ article.title }}, {{ article.url }})
  4. Note default values: Look for | default("value") filters to understand fallbacks
  5. Understand template hierarchy: Identify if there's special treatment for first article (hero), different article types, etc.

Template Analysis Checklist:

  • Extract all {{ variable }} placeholders from template
  • Identify article loop structure and required article properties
  • Note any conditional logic or special formatting
  • Understand default values and fallback behavior
  • Determine expected data types for each variable

Step 3: Locate and Read Articles

Based on the date range provided:

  1. Find articles: Use Glob to find all .md files in the parent directory (go up one level from _workflow/)
  2. Ignore workflow folder: Exclude any files in _workflow/ subfolder - these contain instructions, templates, and workflow documentation
  3. Filter by date: From the article list, filter based on the date range provided
  4. Read articles: Use Read tool to get the full content of each relevant article
  5. Order articles: Sort by date (newest first) - determine hierarchy based on template structure

Directory Structure: 

AI-Pulse/
├── _workflow/                          (IGNORE - workflow files)
│   ├── template_instructions.md
│   ├── gmail_draft_instructions.md  
│   ├── complete_newsletter_workflow.md
│   └── template.html
├── 2025-09-05-ai-orchestrated-newsletter-automation.md  (INCLUDE)
├── 2025-08-27-reliable-unstructured-data-pipelines.md   (INCLUDE)
├── 2025-09-04-rag-architecture-performance-trap.md      (INCLUDE)
└── index.md                            (INCLUDE if needed)

## Step 4: Extract Data from Each Article
For each article, analyze and extract data based on template requirements:

### Dynamic Data Extraction:
Based on your template analysis, extract the required properties:

**Common article properties to look for:**
- **Title**: Look for the first `# ` heading in markdown, clean formatting
- **Date**: Extract from frontmatter, filename, or article content; format consistently  
- **URL**: Construct based on site structure (analyze existing URLs or ask user for pattern)
- **Summary**: Create executive summary appropriate for the audience and publication
- **Category/Type**: Assign based on content analysis and template requirements
- **Reading time**: Estimate based on word count (typically 200-250 words per minute)

### Content Analysis Guidelines:
- **Tone**: Match the publication's established voice and audience
- **Length**: Adjust summary length to template requirements and reader expectations
- **Focus**: Emphasize what matters most to the target audience
- **Accuracy**: Maintain factual accuracy while making content accessible

## Step 5: Generate Newsletter Content
Create a data structure based on your template analysis:

1. **Build data object**: Create key-value pairs for all template variables identified in Step 2
2. **Structure articles array**: Format article data according to template requirements
3. **Apply defaults**: Use template default values where appropriate
4. **Validate completeness**: Ensure all required template variables have values

## Step 6: Generate HTML File
1. **Read template**: Load the `_workflow/template.html` file content
2. **Process template**: Replace all template variables with actual data:
   - Simple variables: Replace `{{ variable }}` with corresponding values
   - Article loops: Process `{% for article in articles %}` structures appropriately
   - Conditional logic: Handle any `{% if %}` statements in template
   - Default filters: Apply `| default("value")` logic where specified
3. **Generate filename**: Create descriptive output filename (e.g., `newsletter-YYYY-MM-DD.html`)
4. **Write file**: Save processed HTML to parent directory (not in `_workflow/`)

## Step 7: Validation and Quality Check
Before finishing:

1. **Template coverage**: Verify all template variables were replaced (no remaining `{{ }}` tags)
2. **Content quality**: Review summaries and extracted data for accuracy and appropriateness
3. **Structural integrity**: Ensure HTML structure is complete and valid
4. **Link validation**: Check that generated URLs follow expected patterns
5. **Data consistency**: Confirm dates, formatting, and other data are consistent

## Generic Execution Flow
User: "Generate newsletter for [criteria]"

Agent: 1. Ask clarifying questions about requirements 2. Read and analyze _workflow/template.html structure 3. Find and filter relevant articles 4. Extract data based on template requirements
5. Build data structure matching template variables 6. Process template with extracted data 7. Write output HTML file 8. Report completion with filename ```

Adaptability Guidelines

Template Flexibility:

  • Variable Discovery: Always analyze template first to understand requirements
  • Dynamic Adaptation: Adjust data extraction based on what template actually needs
  • Default Handling: Respect template default values and fallback behavior
  • Structure Recognition: Adapt to different template layouts and hierarchies

Content Adaptation:

  • Audience Awareness: Infer appropriate tone and style from existing content
  • Format Flexibility: Adjust summary length, detail level based on template design
  • Category Intelligence: Analyze content to assign appropriate categories/types
  • URL Pattern Recognition: Learn URL structure from existing patterns or user input

Error Handling

  • Missing Data: Use appropriate fallbacks or ask user for missing information
  • Template Issues: Report template problems clearly and suggest solutions
  • Content Problems: Handle malformed articles gracefully, noting issues in output
  • Validation Failures: Clearly report what validation checks failed and why