AI Idea Validator

Feature Owner: scorevi (Sean Patrick Caintic)
Module: Diagnose
Priority: P0
Sprint #12: Fully Implemented
Date: 2026-06-29

EXECUTIVE SUMMARY

What is this feature? The AI Idea Validator provides two independent endpoints for evaluating creator content ideas: a lightweight content safety check and a comprehensive curriculum generation engine. It assesses viability, generates curriculum outlines, identifies conflict points, and produces structured recommendations.
Why does it matter? Creators need confidence that their educational ideas are viable before investing time in content creation. Bad ideas caught early save hours of wasted development. The validator ensures content quality and curriculum coherence from the ideation stage.
What's the MVP scope? Content safety validation with 11 evasion techniques and circuit breaker protection, plus full curriculum validation with viability scoring (0-100), curriculum outlines (JSONB), conflict detection, and narrative progression.

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Creators submit ideas without any structured validation. Low-quality or incoherent educational content reaches development, wasting creator and platform resources.

Pain Point

Future State

Creators submit an idea and receive a viability score (0-100), a structured curriculum outline, identified conflict points and crisis scenarios, actionable recommendations, and narrative progression guidance — all before writing a single line of content.

Marketing Hook

"Validate your educational vision in seconds. Know what works before you build."

2. 4D FRAMEWORK MAPPING

3. USER FLOWS

Entry Point

• Creator Dashboard → "Validate Idea" button

• Project Creation Wizard → "Validate First" step

• Standalone Idea Validator page

Success Criteria

• Viability score returned (0-100) with rationale

• Curriculum outline generated as structured JSONB

• Conflict points and crisis scenarios identified

• Narrative progression mapped (TEXT field)

Main Flow

1. Creator enters idea concept / learning objectives

2. Content safety check runs first (POST /api/creator/validate-idea)

3. If safe, full validation runs (POST /api/ai/validate-idea)

4. AI returns viability score, curriculum outline, conflict points, recommendations

5. Results displayed in AIValidator.tsx with score visualization

6. Creator can import validated curriculum to canvas via curriculum-to-canvas.ts

7. Validation saved to idea_validations table for history

Edge Cases

• Toxic/harmful content: Blocked at content safety layer (circuit breaker triggers after 3 failures in 2 min)

• Empty learning objectives: Passed to AI; handled gracefully

• AI timeout: Circuit breaker → 5 min cooldown → local fallback

• Very long ideas: Truncated to 2000 chars (Zod max)

Decision Points

• Accept/reject individual recommendations

• Import full curriculum outline to canvas or partial

• Regenerate with modified input

4. INFORMATION ARCHITECTURE

Primary

• Viability score (0-100), viability rationale, learning objectives (string, max 2000)

• Curriculum outline (JSONB), conflict points (TEXT[])

Secondary

• Crisis scenarios (TEXT[]), recommendations (TEXT[])

• Narrative progression (TEXT), total estimated duration (TEXT)

• Model name for audit trail

Actions

• Validate, Regenerate, Import to Canvas, View History

5. WIREFRAMES

Excluded — existing UI (AIValidator.tsx, 1065 lines).

6. WIREFLOWS

Excluded — existing UI implemented.

7. PROTOTYPE

Excluded — feature is fully implemented.

8. BACKEND SCHEMA

idea_validations table (verified columns)

Important notes:

• NO content_warnings column exists

• NO model_variant column — use model_name instead

• narrative_progression is TEXT, not JSONB

• learningObjectives in Zod schema: z.string().max(2000).trim().optional() — NOT an array

9. API ENDPOINTS

Key distinction: TWO separate endpoints, not one. The creator endpoint handles content safety; the AI endpoint handles full validation.

Content Safety (/api/creator/validate-idea)

• Lightweight safety check

• No curriculum generation

• Uses lib/ai/content-safety.service.ts (533 lines)

• 11 evasion techniques detected

• Circuit breaker: 3 failures in 2 minutes → 5 minute cooldown → local fallback

Full Validation (/api/ai/validate-idea)

• Comprehensive curriculum generation

• Viability scoring, outline, conflicts, recommendations

• Uses lib/ai/validator.service.ts (639 lines)

• Returns idea_validations record

10. DATA REQUIREMENTS

Frontend Needs

• Viability score display (0-100 gauge/visualization)

• Curriculum outline for review

• Conflict points and crisis scenarios for creator awareness

• Recommendations with accept/reject actions

• History sidebar for past validations

API Calls

• POST /api/creator/validate-idea (quick safety check)

• POST /api/ai/validate-idea (full validation)

• GET for validation history

Caching

• No caching on validation results (each validation is unique to input)

• History sidebar persists past results for reference

11. PERFORMANCE CONSIDERATIONS

DB Optimization

• JSONB column for curriculum_outline allows flexible querying

• TEXT[] arrays for conflict points, crisis scenarios, recommendations

Response Time

• Content safety: Near-instantaneous (local logic)

• Full validation: Dependent on Gemini Pro API latency

• Circuit breaker prevents cascading failures during AI outages

12. SECURITY & AUTHORIZATIONAccess Control

• Clerk authentication required on both endpoints

• Creator can only view own validation history (RLS)

Auth Logic

• creator_id is TEXT (Clerk string ID)

• No UUID FK constraint (by design — Clerk IDs are strings)

Validation

• Learning objectives: Zod z.string().max(2000).trim().optional()

• Content safety: 11 evasion technique detection before AI processing

• Circuit breaker: Mitigates abuse and API cost overruns

13. ERROR HANDLING

14. TESTING CHECKLIST

Happy Path

• Submit valid idea → receive viability score and curriculum outline

• Review conflict points and crisis scenarios

• Import curriculum to canvas via converter

• View validation history in sidebar

• Regenerate validation with modified input

Edge Cases

• Submit idea with no learning objectives

• Submit idea at max character limit (2000)

• Content safety blocks harmful input

• Circuit breaker triggers after 3 rapid failures

• Circuit breaker cooldown and recovery

• Local fallback functions during AI outage

15. OPEN QUESTIONS

None — feature is fully implemented.

16. OUT OF SCOPE

• Multi-language curriculum validation

• Peer review integration for validation scores

17. SUCCESS METRICS

• AI validation adoption rate (% of creators validating before creating)

• Average viability score distribution

• Import-to-canvas conversion rate

• Circuit breaker trigger frequency (should be near zero)

18. DEPENDENCIES

• Google Gemini Pro API (validation engine)

• lib/ai/content-safety.service.ts (safety layer)

• lib/ai/validator.service.ts (validation engine)

• curriculum-to-canvas.ts converter (import workflow)

19. TIMELINE

Completed — Feature is fully implemented in Sprint #12.

Document Version

1.0 - Initial version - 2026-06-29 08:11 UTC

1.1 - Added Document Version section and update author to have full name - 2026-06-29 08:43 UTC