Prompt Architecture & Versioning
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Prompt Architecture in HEX-YT-INTEL is centered around the Ultimate Content Intelligence & Implementation System (UCIS), a multi-dimensional framework designed to deconstruct YouTube content into structured intelligence products. This system utilizes a centralized factory and service-based architecture to inject metadata, persona context, and specific dimension constraints into large language model (LLM) instructions.
The architecture supports strict versioning, transitioning from legacy persona-weighted editions to the current v5.1 "Monetization & Commercial Yield Edition." It ensures consistency across analysis sessions by enforcing "Transcript Absolutism"—a directive that restricts the AI to information explicitly present in the provided transcript—while utilizing a segmented analysis approach to handle complex, multi-dimensional outputs.
Sources: web/lib/prompts/ucis-v5.1.ts:1-20, worker/src/services/PromptBuilder.ts:1-15, web/lib/prompts/factory.ts:1-10
UCIS Framework & Versioning
The UCIS system is the primary instruction set for content synthesis. As of version 5.1, the system focuses on four simultaneous purposes: human insight, knowledge graph foundation, persona-weighted intelligence, and commercial viability assessment.
Version History
The project maintains a history of prompt iterations stored within the application's database configuration.
| Version | Released | Key Focus | Supersedes |
|---|---|---|---|
| 5.1 | 2026-05-19 | Monetization & Commercial Yield | v5.0 |
| 5.0 | 2026-05-18 | Persona-Weighted Edition | v4.0 |
| 4.0 | 2026-05-18 | Knowledge-Dimension Edition | v3.2 |
| 3.2 | Legacy | Psychology & Implementation | N/A |
Sources: web/lib/prompts/ucis-v5.1.ts:3-8, supabase/migrations/20260611142500_add_prompt_config.sql:6-10, skill/src/prompts.ts:1-12
Database Configuration
Prompt versions are persisted in the public.app_settings table under the prompt_config key. This allows the system to resolve the latest active template or revert to historical versions. The configuration includes the raw prompt text, timestamps, authors, and descriptions for every version.
Sources: supabase/migrations/20260611142500_add_prompt_config.sql:1-10, web/lib/prompts/factory.ts:34-40
Technical Architecture & Components
The prompt generation process is handled by a combination of a centralized factory in the web layer and a prompt builder service in the worker layer.
Prompt Generation Flow
The system follows a specific sequence to construct the final system prompt sent to the LLM.
This diagram illustrates the flow from an initial analysis request to the assembly of the final prompt.
Sources: worker/src/services/PromptBuilder.ts:19-35, web/lib/prompts/factory.ts:31-60
Core Components
PromptBuilderService: A stateless service in the worker layer that implements thePromptBuilderPort. It orchestrates the construction of the system prompt and adds segment-specific (chunk) instructions for multi-pass analysis.getUCISPromptFactory: The central function responsible for merging the base system template with active session data, including metadata JSON blobs, persona configurations, and transcripts.- Segmented Analysis (Chunking): To handle the "11 Knowledge Dimensions," the
PromptBuildercan isolate specific dimensions for analysis, requesting the LLM to only output one specific dimension at a time to stay within token limits.
Sources: worker/src/services/PromptBuilder.ts:1-15, web/lib/prompts/factory.ts:24-33, worker/src/services/PromptBuilder.ts:47-65
Prompt Constraints & Logic
Critical Processing Directives
The architecture enforces strict behavioral guardrails to ensure data integrity and output structure:
- Transcript Absolutism: The LLM is forbidden from using pre-trained external knowledge or web searching. The transcript is the "Closed Universe."
- Insufficient Data Protocol: If a dimension cannot be fulfilled from the transcript, the model must output:
[Insufficient data in source transcript to fulfill this dimension]. - Short-Form Logic: For videos under 180 seconds, the system injects a "Short-Form Content Notice," instructing the model to be a "ruthless parser" and skip complex matrices.
- Persona Weighting: Analysis is weighted based on a primary persona (50% weight) and four supporting personas (25%, 15%, 5%, 5%).
Sources: web/lib/prompts/ucis-v5.1.ts:30-55, web/lib/prompts/factory.ts:44-50, web/lib/prompts/ucis-v5.1.ts:65-75
JSON Output Schema (v2.0)
Starting with v5.1, the system requires a strict JSON output instead of raw Markdown for technical integration.
| Field | Type | Description |
|---|---|---|
schemaVersion | String | Must be exactly "2.0". |
persona | Object | Contains IDs, labels, weights, and cognitive lenses. |
dimensions | Array | Objects containing dimension number, name, and content. |
knowledgeGraph | Object | Nodes and edges for downstream RAG ingestion. |
classification | Object | Boolean tags (authoritative, actionable, etc.). |
Sources: web/lib/prompts/ucis-v5.1.ts:290-330, worker/src/services/PromptBuilder.ts:70-85
Validation & Quality Enforcement
The project includes a UCISValidator to programmatically verify that LLM outputs adhere to the architectural requirements.
Validation Suite Components
The validator performs several categories of checks:
- Structural Checks: Verifies the presence of the Persona Header and all required Dimension Headers.
- Persona Checks: Ensures the primary persona weight is exactly 50% and identifies at least 3 inline cognitive lens tags.
- Content Rigor: Counts timestamps (format
HH:MM:SS) to ensure quantitative claims are rooted in the transcript. - Knowledge Graph (KG) Readiness: Validates the presence of primary semantic nodes, cross-domain bridges, and unfair advantages.
Sources: web/lib/tests/ucis-v5-validator.test.ts:3-120, web/lib/prompts/ucis-v5.1.ts:260-285
Quality Enforcement Checklist
Every prompt generation pass includes a checklist the model must satisfy before delivering output:
- Persona Header present and complete.
- All 11 Dimension headers appear in order.
- No emojis except ⚠️ in risk blocks.
- Filename matches:
[Title]-[Creator]-[YYYY-MM-DD_HH-MM-SS].md.
Sources: web/lib/prompts/ucis-v5.1.ts:260-288, web/lib/tests/ucis-v5-validator.test.ts:80-95
Summary
The Prompt Architecture & Versioning system provides a robust framework for deterministic AI content analysis. By utilizing a database-backed versioning system and a stateless builder pattern, HEX-YT-INTEL ensures that complex UCIS v5.1 syntheses are generated consistently across both web and worker environments, while maintaining strict adherence to the source transcript and target user personas.