Skip to main content

Knowledge > Runbooks > Content Ops > Add New Sermon Illustrations

Add New Sermon Illustrations

Add new sermon illustrations to the ITW (IllustrateTheWord) database. Illustrations are stored in unified_rag_content with category='illustration'.

Prerequisites​

  • Supabase MCP or direct DB access
  • Illustration content prepared (title, body, scripture reference, topic tags, theological lens)
  • Theological lens ID from sai_theological_lenses (18 options — 17 traditions + universal)
  • For batch generation: access to sermon-illustrations/scripts/ and Claude CLI (claude -p)

Steps​

Option A: Add a Single Illustration Manually​

  1. Look up the theological lens ID:

    SELECT id, name, tradition FROM sai_theological_lenses ORDER BY name;

  2. INSERT the illustration:

    INSERT INTO unified_rag_content (
      category,
      title,
      content,
      scripture_reference,
      theological_lens_id,
      topic_tags,
      is_public,
      source,
      created_at,
      updated_at
    ) VALUES (
      'illustration',
      '[Illustration Title]',
      '[Full illustration text — 200–800 words recommended]',
      '[e.g., John 3:16 or Romans 8:28-30]',
      [lens_id],
      ARRAY['grace', 'redemption', 'forgiveness'],  -- adjust topics
      true,
      'editorial',
      now(),
      now()
    );

  3. Verify the illustration appears in the database:

    SELECT id, title, scripture_reference, is_public, created_at
    FROM unified_rag_content
    WHERE category = 'illustration'
    ORDER BY created_at DESC
    LIMIT 5;

Option B: Batch Generation via Script​

  1. Navigate to the ITW codebase:

    cd /c/dev/sermon-illustrations

  2. Unset Claude CLI env vars before running (required for nested CLI invocation):

    unset CLAUDE_CODE_ENTRYPOINT
    unset CLAUDECODE

  3. Run the generation script (uses claude -p internally — never the Anthropic API directly):

    node scripts/generate-illustrations.js \
      --count 10 \
      --lens "universal" \
      --topic "grace"

  4. Review the generated output before inserting — check for:

    • Theological accuracy
    • Appropriate length (200–800 words)
    • No hallucinated scripture references (verify the reference exists)
    • No repetition of existing illustrations

  5. Approve and insert the reviewed content using the INSERT statement above, or use the script's --insert flag if available.

Add an Image (Optional)​

See illustration-images.md for adding illustration cover images after the content is inserted.

Content Quality Standards​

  • Scripture accuracy: Always verify the quoted reference matches the actual text.
  • Length: 200–800 words per illustration for optimal embedding quality.
  • Topics: Use consistent tag vocabulary (check existing tags in the DB for established terms).
  • Theological lens: Match the tradition's hermeneutical emphasis — do not use universal for content that is tradition-specific.

Verification​

  • New row appears in unified_rag_content with category='illustration' and is_public=true.
  • Illustration is findable on the ITW site via scripture or topic search.
  • No broken scripture references or placeholder text in the content field.

See Also​