lcbp3/.agents/workflows/113-speckit-ocr-prompt-management.md

auto_execution_mode, description

auto_execution_mode	description
0	Execute OCR & AI Extraction prompt management workflow following ADR-037 3-Step Pipeline (OCR → AI Extract → RAG Prep)

Workflow: speckit.ocr-prompt-management

This workflow orchestrates the OCR & AI Extraction prompt management feature implementation, following the 3-step pipeline pattern defined in ADR-037.

Phase 1: Database & Infrastructure Setup

1. Database Schema:

   • Verify version column exists in ai_prompts table (delta: 2026-06-15-fix-ai-prompts-columns.sql)
   • Seed default OCR system prompt (delta: 2026-06-17-seed-ocr-system-prompt.sql)
   • Verify entity has @VersionColumn() at backend/src/modules/ai/prompts/ai-prompts.entity.ts

2. Infrastructure Verification:

   • Verify OCR sidecar is running on Desk-5439 (port 8765)
   • Verify /embed endpoint exists in sidecar
   • Verify environment variables: OCR_SIDECAR_API_KEY, OCR_API_URL

Phase 2: Foundational Services

1. Validation Service:

   • Extend ai-prompts.service.ts create() to support ocr_system (free-form, no required placeholder)
   • Verify {{ocr_text}} placeholder validation for ocr_extraction
   • Use existing DTOs: CreateAiPromptDto, UpdatePromptNoteDto, ContextConfigDto

2. Optimistic Locking:

   • Modify activate() in ai-prompts.service.ts to accept expectedVersion
   • Handle HTTP 409 Conflict when version mismatch occurs
   • Add retry logic with exponential backoff in frontend

Phase 3: User Story 1 - OCR System Prompt Management

Backend

• Verify AiPromptsService.create() supports ocr_system (version auto-increment)
• Verify getActive(promptType) returns active ocr_system with Redis cache (60s)
• Verify existing routes: GET /api/ai/prompts/{promptType}, POST /api/ai/prompts/{promptType}, POST /api/ai/prompts/{promptType}/{versionNumber}/activate

Frontend

• Create adminAiPromptService in frontend/lib/services/admin-ai-prompt.service.ts
• Implement getPrompts(), createPrompt(), activatePrompt() with optimistic locking
• Create PromptManagementTabs component
• Create OcrPromptTab component with text editor and version history
• Implement "Save New Version" button with validation
• Handle 409 Conflict error - show refresh dialog

Sidecar Integration

• Update /ocr-upload endpoint in specs/04-Infrastructure-OPS/04-00-docker-compose/Desk-5439/ocr-sidecar/app.py:
  • Add parameter: systemPrompt: Optional[str] = Form(default=None)
  • Thread systemPrompt through _process_pdf_doc() → process_ocr()
  • Append system prompt to messages[0]["content"] (typhoon OCR single-message format)
• Update sandbox-ocr-engine.service.ts to fetch active ocr_system prompt and send to sidecar

Phase 4: User Story 2 - AI Extraction Prompt Management

Backend

• Verify ocr_extraction validation in create() ({{ocr_text}} required)
• Verify resolveActive('ocr_extraction', ocrText) exists
• Verify ai-batch.processor.ts uses active ocr_extraction prompt

Frontend

• Create AiExtractionPromptTab component
• Add placeholder helper buttons ({{ocr_text}}, {{master_data_context}})
• Show validation error inline if missing required placeholder
• Add template preview with syntax highlighting

Phase 5: User Story 3 - Separate UI Tabs

Frontend UI Polish

• Style PromptManagementTabs with clear tab indicators
• Add tab icons (OCR: eye/scan icon, AI: brain/robot icon)
• Show active status badge on each tab
• Implement tab state persistence (URL hash or localStorage)
• Add warning badge if no active prompt for a type

Phase 6: User Story 4 - Full 3-Step Sandbox with RAG Prep

Backend (RAG Prep Integration)

• Verify rag_prep_prompt validates {{text}} placeholder
• Verify SandboxRagPrepDto exists at backend/src/modules/ai/dto/sandbox-rag-prep.dto.ts
• Extend ai-batch.processor.ts sandbox-rag-prep job handler
• Implement semantic chunking using active rag_prep_prompt
• Verify sidecar /embed endpoint exists
• Verify POST /api/ai/admin/sandbox/rag-prep exists in AiController
• Verify Redis storage for RAG Prep results
• Verify GET sandbox job result endpoint (/api/ai/admin/sandbox/job/:id)

Frontend (3-Step Sandbox UI)

• Create SandboxStepIndicator component showing 3 steps with status icons
• Extend PromptManagementTabs with "Sandbox" tab containing 3-step workflow
• Create RagPrepResultPanel component with chunk list + vector preview
• Implement vector preview display (first 5 dimensions: [0.234, -0.891, ...])
• Add "Run Step 3 (RAG Prep)" button enabled after Step 2 completes
• Display chunk count and embedding status for each chunk
• Add "Activate This Version" button visible after all 3 steps complete successfully

Integration (Full Pipeline)

• Wire Step 2 output (extracted metadata + text) as Step 3 input
• Implement sequential step execution (Step 1 → Step 2 → Step 3)
• Add pipeline status tracking in Redis

Phase 7: Testing & Validation

Error Handling (ADR-007)

• Add user-friendly error messages for validation errors in frontend
• Implement retry logic for 409 Conflict with exponential backoff
• Add Toast notifications for success/error states

Testing

• Write unit tests for AiPromptValidationService
• Write integration test for optimistic locking conflict scenario
• E2E test: Admin creates OCR prompt → activates → runs Sandbox Step 1
• E2E test: Full 3-step pipeline - upload PDF → OCR → Extract → RAG Prep
• E2E test: Vector preview displays correctly with 5 dimensions
• E2E test: Step indicators show correct status for each step

Usage

/speckit.ocr-prompt-management

Dependencies

• Phase 1: None (infrastructure setup)
• Phase 2: Phase 1
• Phase 3: Phase 2
• Phase 4: Phase 2 (can run in parallel with Phase 3)
• Phase 5: Phase 3 + Phase 4
• Phase 6: Phase 3 + Phase 4
• Phase 7: Phase 6

On Error

If any phase fails, stop and report:

• Which phase failed
• The specific task that failed
• Suggested remediation (e.g., "Verify OCR sidecar is running before Phase 3")

Related ADRs

• ADR-009: Database schema changes (SQL deltas, no TypeORM migrations)
• ADR-016: Security authentication (RBAC for admin-only endpoints)
• ADR-023/023A: AI architecture (BullMQ queues, Ollama isolation)
• ADR-037: 3-Step Pipeline (OCR → AI Extract → RAG Prep)