clawfort/openspec/specs/news-image-relevance-and-fallbacks/spec.md

Purpose

Canonical specification for news-image-relevance-and-fallbacks requirements synced from OpenSpec change deltas.

Requirements

Requirement: Image query fallback uses AI-focused defaults

When extracted image keywords are insufficient, the system SHALL use AI-focused default fallback terms.

Scenario: Empty keyword extraction

• WHEN keyword extraction yields no usable topic keywords
• THEN the system uses default fallback terms including AI-domain keywords (for example ai, machine learning, deep learning)

Requirement: Generic AI image fallback is guaranteed

If provider lookups fail to return a usable summary image, the system SHALL use a generic AI-themed fallback image.

Scenario: Provider chain failure

• WHEN all configured image providers return no usable image
• THEN the system assigns a generic AI fallback image URL/path for summary image

Requirement: Fallback behavior remains context-aware first

The system SHALL evaluate context-aware candidates before fallback and require refetched summary images to be relevant, non-redundant alternatives.

Scenario: Context-aware attempt precedes fallback

• WHEN summary image selection runs for a news item
• THEN the system first attempts provider queries from extracted context-aware keywords
• AND only falls back to generic AI image if candidate evaluation fails

Scenario: Finance-story relevance guard

• WHEN article topic contains finance/market terms (for example stocks, shares, plunge, earnings)
• THEN image selection rejects obviously unrelated animal/portrait outcomes
• AND system retries with finance-safe query refinements before final fallback

Scenario: Guarded fallback remains deterministic

• WHEN provider chain cannot return a relevant finance-safe image
• THEN system uses deterministic generic fallback that is topic-safe
• AND avoids unrelated imagery classes flagged by guardrails

Scenario: Refetch rejects unrelated and duplicate outcomes

• WHEN candidate images are evaluated during refetch
• THEN the system rejects candidates matching current image identity for the same article
• AND rejects clearly unrelated animal/pet imagery classes before final selection