lcbp3/specs/200-fullstacks/237-unified-prompt-management-ux-ui/tasks.md

Tasks: Unified Prompt Management UX/UI

Input: Design documents from /specs/200-fullstacks/237-unified-prompt-management-ux-ui/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

Tests: Tests are included for backend services to ensure quality and coverage targets (Backend 70%+, Business Logic 80%+).

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

Path Conventions

• Backend: backend/src/, backend/test/
• Frontend: frontend/src/, frontend/__tests__/

Phase 1: Setup (Shared Infrastructure)

Purpose: Database schema and seed data setup

• T001 Create SQL delta for ai_execution_profiles table in specs/03-Data-and-Storage/deltas/2026-06-14-create-ai-execution-profiles.sql
• T002 Create SQL delta for execution profiles seed data in specs/03-Data-and-Storage/deltas/2026-06-14-seed-execution-profiles.sql
• T003 Create SQL delta for additional prompt types seed data in specs/03-Data-and-Storage/deltas/2026-06-14-seed-additional-prompt-types.sql
• T004 [P] Run SQL deltas to create ai_execution_profiles table and seed data

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core backend entities and DTOs that all user stories depend on

⚠️ CRITICAL: No user story work can begin until this phase is complete

• T005 Create AiExecutionProfile entity in backend/src/modules/ai/entities/ai-execution-profile.entity.ts
• T006 [P] Create ContextConfigDto in backend/src/modules/ai/dto/context-config.dto.ts
• T007 [P] Create SandboxRagPrepDto in backend/src/modules/ai/dto/sandbox-rag-prep.dto.ts
• T008 [P] Create CreateExecutionProfileDto in backend/src/modules/ai/dto/create-execution-profile.dto.ts
• T009 [P] Create UpdateExecutionProfileDto in backend/src/modules/ai/dto/update-execution-profile.dto.ts
• T010 [P] Create frontend types in frontend/lib/types/ai-prompts.ts (extend with ContextConfig, ExecutionProfile, SandboxJob types)
• T011 Register AiExecutionProfile entity in AiModule in backend/src/modules/ai/ai.module.ts

Checkpoint: Foundation ready - user story implementation can now begin in parallel

---

Phase 3: User Story 1 - Multi-Type Prompt Management (Priority: P1) 🎯 MVP

Goal: Admin users can manage prompt templates for multiple AI workflow types through a single unified interface with separated version history.

Independent Test: Create and activate versions for different prompt types, verify version history is correctly separated by type, and confirm active version badge displays correctly.

Tests for User Story 1

• T012 [P] [US1] Unit test for placeholder validation in AiPromptsService in backend/test/unit/ai/ai-prompts.service.spec.ts
• T013 [P] [US1] Integration test for version number increment per prompt type in backend/test/integration/ai/ai-prompts.service.spec.ts

Implementation for User Story 1

• T014 [US1] Extend AiPromptsService with placeholder validation logic in backend/src/modules/ai/services/ai-prompts.service.ts
• T015 [US1] Extend AiPromptsService with version number increment per prompt_type in backend/src/modules/ai/services/ai-prompts.service.ts
• T016 [US1] Create PromptTypeDropdown component in frontend/components/admin/ai/PromptTypeDropdown.tsx
• T017 [US1] Extend VersionHistory component with prompt_type filtering in frontend/components/admin/ai/VersionHistory.tsx
• T018 [US1] Create PromptEditor component with placeholder validation in frontend/components/admin/ai/PromptEditor.tsx
• T019 [US1] Create unified prompt management page in frontend/app/(admin)/admin/ai/prompt-management/page.tsx
• T020 [US1] Extend admin-ai.service.ts with prompt type filtering methods in frontend/lib/services/admin-ai.service.ts
• T021 [US1] Add i18n keys for prompt management UI in frontend/public/locales/th/common.json and en/common.json

Checkpoint: At this point, User Story 1 should be fully functional and testable independently

---

Phase 4: User Story 2 - Context Configuration Management (Priority: P1)

Goal: Admin users can view, edit, save, and apply context configuration for each prompt version to control what data context the AI sees.

Independent Test: Edit context config fields, save a new version, and verify that the context config is correctly persisted and applied when the version is activated.

Tests for User Story 2

• T022 [P] [US2] Unit test for context config CRUD in AiPromptsService in backend/test/unit/ai/ai-prompts.service.spec.ts
• T023 [P] [US2] Integration test for context config validation against database in backend/test/integration/ai/ai-prompts.service.spec.ts

Implementation for User Story 2

• T024 [US2] Add GET /api/ai/prompts/:type/:version/context-config endpoint in backend/src/modules/ai/controllers/ai-prompts.controller.ts
• T025 [US2] Add PUT /api/ai/prompts/:type/:version/context-config endpoint in backend/src/modules/ai/controllers/ai-prompts.controller.ts
• T026 [US2] Extend AiPromptsService with context config CRUD methods in backend/src/modules/ai/services/ai-prompts.service.ts
• T027 [US2] Add context config validation (project/contract ID validation) in backend/src/modules/ai/services/ai-prompts.service.ts
• T028 [US2] Create ContextConfigEditor component in frontend/components/admin/ai/ContextConfigEditor.tsx
• T029 [US2] Integrate ContextConfigEditor into prompt management page in frontend/app/(admin)/admin/ai/prompt-management/page.tsx
• T030 [US2] Extend admin-ai.service.ts with context config API methods in frontend/lib/services/admin-ai.service.ts

Checkpoint: At this point, User Stories 1 AND 2 should both work independently

---

Phase 5: User Story 3 - Three-Step Sandbox Testing (Priority: P1)

Goal: Admin users can test the full AI pipeline (OCR → AI Extract → RAG Prep) in sandbox to validate prompt versions before activation.

Independent Test: Upload a PDF, run all three sandbox steps sequentially, and verify that each step produces expected outputs (OCR text, extracted metadata, RAG chunks).

Tests for User Story 3

• T031 [P] [US3] Unit test for sandbox RAG Prep job processing in ai-batch.processor in backend/test/unit/ai/ai-batch.processor.spec.ts
• T032 [P] [US3] Integration test for 3-step sandbox workflow in backend/test/integration/ai/sandbox-workflow.spec.ts

Implementation for User Story 3

• T033 [US3] Add POST /api/ai/admin/sandbox/rag-prep endpoint in backend/src/modules/ai/controllers/ai.controller.ts
• T034 [US3] Add GET /api/ai/admin/sandbox/job/:jobId endpoint in backend/src/modules/ai/controllers/ai.controller.ts
• T035 [US3] Extend ai-batch.processor with sandbox-rag-prep job handler in backend/src/modules/ai/processors/ai-batch.processor.ts
• T036 [US3] Extend OcrService with RAG Prep integration (semantic chunking + embedding) in backend/src/modules/ai/services/ocr.service.ts
• T037 [US3] Create SandboxTabs component with 3-step workflow in frontend/components/admin/ai/SandboxTabs.tsx
• T038 [US3] Integrate SandboxTabs into prompt management page in frontend/app/(admin)/admin/ai/prompt-management/page.tsx
• T039 [US3] Extend admin-ai.service.ts with sandbox RAG Prep API methods in frontend/lib/services/admin-ai.service.ts
• T040 [US3] Add "Activate This Version" button in sandbox results in frontend/components/admin/ai/SandboxTabs.tsx

Checkpoint: All user stories should now be independently functional

---

Phase 6: User Story 4 - Runtime Parameters vs Context Config Separation (Priority: P2)

Goal: Admin users have clear separation between Runtime Parameters (AI model behavior) and Context Config (data context) to avoid confusion.

Independent Test: Verify that Runtime Parameters are in the Sandbox tab and apply globally to AI execution profiles, while Context Config is in the Prompt Editor panel and applies per prompt version.

Tests for User Story 4

• T041 [P] [US4] Unit test for execution profile CRUD in AiExecutionProfilesService in backend/test/unit/ai/ai-execution-profiles.service.spec.ts
• T042 [P] [US4] Integration test for runtime parameters application to sandbox in backend/test/integration/ai/execution-profiles.spec.ts

Implementation for User Story 4

• T043 [US4] Create AiExecutionProfilesService in backend/src/modules/ai/services/ai-execution-profiles.service.ts
• T044 [US4] Add GET /api/ai/execution-profiles endpoint in backend/src/modules/ai/controllers/ai.controller.ts
• T045 [US4] Add POST /api/ai/execution-profiles endpoint in backend/src/modules/ai/controllers/ai.controller.ts
• T046 [US4] Add PUT /api/ai/execution-profiles/:id endpoint in backend/src/modules/ai/controllers/ai.controller.ts
• T047 [US4] Add DELETE /api/ai/execution-profiles/:id endpoint in backend/src/modules/ai/controllers/ai.controller.ts
• T048 [US4] Create RuntimeParametersPanel component in frontend/components/admin/ai/RuntimeParametersPanel.tsx
• T049 [US4] Integrate RuntimeParametersPanel into SandboxTabs in frontend/components/admin/ai/SandboxTabs.tsx
• T050 [US4] Extend admin-ai.service.ts with execution profile API methods in frontend/lib/services/admin-ai.service.ts
• T051 [US4] Add "Apply to Production" button in RuntimeParametersPanel in frontend/components/admin/ai/RuntimeParametersPanel.tsx

Checkpoint: All user stories including US4 should now be independently functional

---

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Improvements that affect multiple user stories

• T052 [P] Add error handling following ADR-007 (BusinessException hierarchy) in backend/src/modules/ai/services/ai-prompts.service.ts
• T053 [P] Add error handling following ADR-007 in backend/src/modules/ai/services/ai-execution-profiles.service.ts
• T054 [P] Add CASL guards to all new mutation endpoints in backend/src/modules/ai/controllers/ai-prompts.controller.ts
• T055 [P] Add CASL guards to all new mutation endpoints in backend/src/modules/ai/controllers/ai.controller.ts
• T056 [P] Add ThrottlerGuard to sandbox endpoints in backend/src/modules/ai/controllers/ai.controller.ts
• T057 [P] Add Redis cache invalidation on version activation in backend/src/modules/ai/services/ai-prompts.service.ts
• T058 [P] Add i18n keys for all new UI components in frontend/public/locales/th/common.json and en/common.json
• T059 [P] Add TypeScript strict mode compliance checks (no any, no console.log) in backend/src/modules/ai/ and frontend/components/admin/ai/
• T060 [P] Add E2E test for full prompt management workflow in frontend/e2e/prompt-management.spec.ts
• T061 Run quickstart.md validation checklist
• T062 Update ADR-037 with implementation status

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies - can start immediately
• Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
• User Stories (Phase 3-6): All depend on Foundational phase completion
  • User stories can then proceed in parallel (if staffed)
  • Or sequentially in priority order (US1 → US2 → US3 → US4)
• Polish (Phase 7): Depends on all desired user stories being complete

User Story Dependencies

• User Story 1 (P1): Can start after Foundational (Phase 2) - No dependencies on other stories
• User Story 2 (P1): Can start after Foundational (Phase 2) - Integrates with US1 (uses same page) but independently testable
• User Story 3 (P1): Can start after Foundational (Phase 2) - Integrates with US1 (uses same page) but independently testable
• User Story 4 (P2): Can start after Foundational (Phase 2) - Integrates with US3 (SandboxTabs) but independently testable

Within Each User Story

• Tests MUST be written and FAIL before implementation
• DTOs before services
• Services before controllers
• Backend before frontend (for API-dependent features)
• Core implementation before integration
• Story complete before moving to next priority

Parallel Opportunities

• All Setup tasks marked [P] can run in parallel
• All Foundational tasks marked [P] can run in parallel (within Phase 2)
• Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
• All tests for a user story marked [P] can run in parallel
• DTOs within a story marked [P] can run in parallel
• Different user stories can be worked on in parallel by different team members

---

Parallel Example: User Story 1

# Launch all tests for User Story 1 together:
Task: "Unit test for placeholder validation in AiPromptsService in backend/test/unit/ai/ai-prompts.service.spec.ts"
Task: "Integration test for version number increment per prompt type in backend/test/integration/ai/ai-prompts.service.spec.ts"

# Launch all DTOs for User Story 1 together (in Foundational phase):
Task: "Create ContextConfigDto in backend/src/modules/ai/dto/context-config.dto.ts"
Task: "Create SandboxRagPrepDto in backend/src/modules/ai/dto/sandbox-rag-prep.dto.ts"

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
3. Complete Phase 3: User Story 1
4. STOP and VALIDATE: Test User Story 1 independently
5. Deploy/demo if ready

Incremental Delivery

1. Complete Setup + Foundational → Foundation ready
2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
3. Add User Story 2 → Test independently → Deploy/Demo
4. Add User Story 3 → Test independently → Deploy/Demo
5. Add User Story 4 → Test independently → Deploy/Demo
6. Each story adds value without breaking previous stories

Parallel Team Strategy

With multiple developers:

1. Team completes Setup + Foundational together
2. Once Foundational is done:
   • Developer A: User Story 1 (Multi-Type Prompt Management)
   • Developer B: User Story 2 (Context Configuration Management)
   • Developer C: User Story 3 (Three-Step Sandbox Testing)
3. After P1 stories complete:
   • Developer A: User Story 4 (Runtime Parameters Separation)
   • Developer B: Polish & Cross-Cutting Concerns
   • Developer C: E2E testing
4. Stories complete and integrate independently

---

Notes

• [P] tasks = different files, no dependencies
• [Story] label maps task to specific user story for traceability
• Each user story should be independently completable and testable
• Verify tests fail before implementing
• Commit after each task or logical group
• Stop at any checkpoint to validate story independently
• Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence
• Follow ADR-019 UUID handling (no parseInt, use publicId only)
• Follow ADR-009 schema changes (edit SQL directly, no migrations)
• Follow ADR-016 security (CASL guards on all mutations)
• Follow ADR-007 error handling (layered classification)
• Follow ADR-023/023A AI boundary (BullMQ queues, no direct AI access)