Knowledge > Runbooks > Content Ops > Regenerate Stub Illustrations

Regenerate Stub Illustrations

Identify and regenerate illustrations that are incomplete, too short, or contain placeholder content. Stubs degrade search quality and user experience.

Prerequisites

• Supabase MCP or direct DB access
• Access to sermon-illustrations/scripts/ directory
• Claude CLI (claude -p) available in the shell
• Sufficient Claude Max quota for batch generation

What Is a Stub?

A stub is an illustration that:

• Has fewer than 150 words in the content field
• Contains placeholder text (e.g., "[PLACEHOLDER]", "TODO", "..." as the body)
• Has a title but empty or near-empty content
• Has is_public = false but was not intentionally hidden

Steps

1. Identify stubs by content length:

   SELECT
     id,
     title,
     scripture_reference,
     theological_lens_id,
     length(content) AS char_count,
     LEFT(content, 100) AS preview,
     created_at
   FROM unified_rag_content
   WHERE category = 'illustration'
     AND (
       length(content) < 300
       OR content LIKE '%[PLACEHOLDER]%'
       OR content LIKE '%TODO%'
     )
   ORDER BY char_count ASC
   LIMIT 50;

2. Export stub IDs and metadata to a working list:

   SELECT id, title, scripture_reference, theological_lens_id, topic_tags
   FROM unified_rag_content
   WHERE category = 'illustration'
     AND length(content) < 300
   ORDER BY created_at ASC;

3. Navigate to the scripts directory:

   cd /c/dev/sermon-illustrations

4. Unset Claude CLI env vars before running any script that spawns claude -p:

   unset CLAUDE_CODE_ENTRYPOINT
   unset CLAUDECODE

5. Run the stub regeneration script:

   node scripts/regenerate-stubs.js --dry-run

   Review the dry-run output first. Confirm the script is targeting the correct stub IDs and using the correct prompts.

6. Run without dry-run to generate content:

   node scripts/regenerate-stubs.js --limit 20

   Process in batches of 20 to manage Claude CLI rate limits and allow quality review between runs.

7. Review generated content before updating the database:

   • Read a representative sample (at least 20%).
   • Check for theological accuracy, appropriate length, no hallucinated scripture references.
   • Confirm the illustration relates to its stated scripture reference.

8. Update approved stubs in the database:

   UPDATE unified_rag_content
   SET content = '[regenerated content]',
       is_public = true,
       updated_at = now()
   WHERE id = '[stub-uuid]';

   Or use the script's --update flag if it writes directly to Supabase.

9. Repeat for remaining stubs in batches until the stub queue is clear.

Batch Size Guidance

Total Stubs	Recommended Batch Size	Estimated Time
< 50	Run all at once	10–20 min
50–200	Batches of 25	1–2 hours
200+	Batches of 50 per session	Multiple sessions

Verification

After regenerating:

SELECT COUNT(*) AS remaining_stubs
FROM unified_rag_content
WHERE category = 'illustration'
  AND length(content) < 300;

Target: zero remaining stubs. Spot-check 5–10 regenerated illustrations on the ITW site by searching for their scripture reference or topic.

See Also

• add-illustrations.md — add entirely new illustrations
• audit-content.md — broader content quality audit
• generate-by-scripture.md — generate targeted content for specific passages