Skip to main content

Knowledge > Runbooks > Content Ops > Generate Illustrations by Topic or Theme

Generate Illustrations by Topic or Theme

Generate sermon illustrations focused on a specific topic, theme, or season. Use this to build out topic pages on ITW, fill seasonal gaps (Advent, Easter, stewardship season), or respond to common search queries that return few results.

Prerequisites​

  • Access to sermon-illustrations/scripts/ directory
  • Claude CLI (claude -p) available in the shell
  • Supabase MCP or direct DB access
  • Target topic (e.g., "forgiveness", "Advent", "stewardship", "grief", "discipleship")

Steps​

  1. Check existing coverage for the topic:

    SELECT id, title, scripture_reference, theological_lens_id, created_at
    FROM unified_rag_content
    WHERE category = 'illustration'
      AND (
        topic_tags @> ARRAY['[topic]']
        OR content ILIKE '%[topic]%'
      )
      AND is_public = true
    ORDER BY created_at DESC
    LIMIT 20;

    Note how many exist and which lenses are already covered.

  2. Identify seasonal or campaign context:

    • Advent (4 weeks pre-Christmas): focus on hope, waiting, prophecy, incarnation
    • Lent (40 days pre-Easter): repentance, sacrifice, wilderness, redemption
    • Stewardship season (typically October): generosity, tithing, kingdom resources
    • General topics: use evergreen framing, not seasonal

  3. Navigate to the scripts directory:

    cd /c/dev/sermon-illustrations

  4. Unset Claude CLI env vars before spawning:

    unset CLAUDE_CODE_ENTRYPOINT
    unset CLAUDECODE

  5. Run the topic generation script:

    node scripts/generate-by-topic.mjs \
      --topic "forgiveness" \
      --lenses "universal,reformed,wesleyan,pentecostal,catholic" \
      --count 3 \
      --dry-run

    Review the dry-run output: titles, planned scripture references, and lens assignments. Confirm before running without --dry-run.

  6. Generate without dry-run:

    node scripts/generate-by-topic.mjs \
      --topic "forgiveness" \
      --lenses "universal,reformed,wesleyan,pentecostal,catholic" \
      --count 3

  7. Review each generated illustration for:

    • Relevance to the topic (not tangential)
    • Accurate scripture references — verify they actually address the topic
    • Appropriate tone for the lens (Reformed emphasis on grace/sovereignty, Wesleyan emphasis on free will/sanctification, etc.)
    • No repetition of illustrations already in the DB
    • Length: 300–700 words

  8. Insert approved illustrations with correct topic tags:

    INSERT INTO unified_rag_content (
      category, title, content, scripture_reference,
      theological_lens_id, topic_tags, is_public, source, created_at, updated_at
    ) VALUES (
      'illustration',
      '[Title]',
      '[Content]',
      '[Reference]',
      [lens_id],
      ARRAY['forgiveness', 'reconciliation', 'grace'],
      true,
      'generated',
      now(),
      now()
    );

  9. Verify topic tags are consistent with existing vocabulary:

    SELECT DISTINCT unnest(topic_tags) AS tag, COUNT(*) as uses
    FROM unified_rag_content
    WHERE category = 'illustration'
    GROUP BY tag
    ORDER BY uses DESC
    LIMIT 30;

    Use established tags rather than inventing new variants (e.g., use 'prayer' not 'praying').

Topic Coverage Targets​

Topic PriorityMinimum Illustrations
Core theological (grace, salvation, faith, prayer)15–20 across multiple lenses
Common sermon themes (forgiveness, hope, love)8–12 illustrations
Seasonal (Advent, Easter, Pentecost)6–10 per season
Specific application (stewardship, evangelism, discipleship)4–6 illustrations

Verification​

SELECT COUNT(*), theological_lens_id
FROM unified_rag_content
WHERE category = 'illustration'
  AND topic_tags @> ARRAY['[topic]']
  AND is_public = true
GROUP BY theological_lens_id;

Search for the topic on illustratetheword.com and confirm new illustrations appear.

See Also​