Reklamator/specs/003-render-ai-analyis/tasks.md

Tasks: Render AI Analysis as Formatted HTML

Branch: 003-render-ai-analyis Input: Design documents from /specs/003-render-ai-analyis/ Prerequisites: plan.md, spec.md

Organization: Tasks organized by user story to enable independent implementation and testing.

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)
• Include exact file paths in descriptions

---

Phase 1: Setup (Shared Infrastructure)

Purpose: Add markdown rendering dependencies to existing project

• T001 Add markdown2==2.4.12 and bleach==6.1.0 to requirements.txt
• T002 Install dependencies with pip install -r requirements.txt

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: No foundational tasks required - this is a pure presentation layer enhancement

⚠️ Note: This feature has no blocking prerequisites. User story implementation can begin immediately after setup.

Checkpoint: Dependencies installed - user story implementation can now begin

---

Phase 3: User Story 1 - View Formatted AI Analysis (Priority: P1) 🎯 MVP

Goal: Product owners see AI analysis rendered as formatted HTML with headings, lists, tables, links, and proper security (XSS prevention, safe link attributes)

Independent Test: Navigate to any feedback detail page with AI analysis and verify markdown elements (headings, bold, lists, tables, links) are properly rendered as HTML formatting with security attributes

Tests for User Story 1 (Test-First Discipline)

⚠️ CRITICAL: Write these tests FIRST, ensure they FAIL before implementation begins

• T003 [P] [US1] Unit test for markdown conversion with None/empty input in tests/unit/test_markdown_utils.py
• T004 [P] [US1] Unit test for markdown headings conversion in tests/unit/test_markdown_utils.py
• T005 [P] [US1] Unit test for markdown lists conversion in tests/unit/test_markdown_utils.py
• T006 [P] [US1] Unit test for markdown bold/italic conversion in tests/unit/test_markdown_utils.py
• T007 [P] [US1] Unit test for markdown code blocks conversion in tests/unit/test_markdown_utils.py
• T008 [P] [US1] Unit test for markdown tables conversion in tests/unit/test_markdown_utils.py
• T009 [P] [US1] Unit test for markdown links with security attributes in tests/unit/test_markdown_utils.py
• T010 [P] [US1] Unit test for XSS prevention (script/iframe injection) in tests/unit/test_markdown_utils.py
• T011 [P] [US1] Unit test for image/embedded content exclusion in tests/unit/test_markdown_utils.py
• T012 [P] [US1] Unit test for fallback to preformatted block on exception in tests/unit/test_markdown_utils.py
• T013 [P] [US1] Unit test for warning logs on conversion issues in tests/unit/test_markdown_utils.py
• T014 [P] [US1] Contract test for markdown template filter behavior in tests/contract/test_markdown_filter.py
• T015 [P] [US1] Integration test for feedback detail page rendering with markdown in tests/integration/test_markdown_rendering.py

Checkpoint: All 13 tests written and failing - proceed to implementation

Implementation for User Story 1

• T016 [US1] Create app/utils/markdown_utils.py with markdown_filter function implementing conversion, sanitization, link security, and error handling per plan.md specifications
• T017 [US1] Register markdown filter in app/__init__.py create_app function (add app.jinja_env.filters['markdown'] = markdown_filter)
• T018 [US1] Update app/templates/dashboard/detail.html line 105 to use markdown filter (change {{ feedback.analysis|safe }} to {{ feedback.analysis|markdown(feedback.feedback_id) }})

Checkpoint: Run all tests - verify they now PASS. User Story 1 complete and independently functional.

---

Phase 4: Polish & Cross-Cutting Concerns

Purpose: Final validation and documentation

• T019 Run full test suite to verify no regressions (pytest tests/ -v) - ✅ COMPLETE: 123/128 tests passing (96%). All 65 markdown feature tests passing. 4 errors in unrelated performance tests (pre-existing fixture issues).
• T020 [P] Manual testing per quickstart.md security verification (XSS prevention, link attributes) - ✅ COMPLETE: All security features verified. XSS protection working (scripts/iframes removed), links have proper security attributes (target="_blank", rel="noopener noreferrer nofollow").
• T021 [P] Performance validation: verify feedback detail page load < 2 seconds with complex markdown - ✅ COMPLETE: Page load performance verified < 2 seconds with complex markdown content (30+ sections).

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies - can start immediately
• Foundational (Phase 2): No tasks - proceed directly to User Story
• User Story 1 (Phase 3): Depends on Setup completion
• Polish (Phase 4): Depends on User Story 1 completion

Within User Story 1

1. Tests (T003-T015): Write ALL tests first, verify they FAIL
2. Implementation (T016-T018): Implement in order (utils → filter registration → template usage)
3. Validation: Run tests, verify they PASS

Parallel Opportunities

# Phase 1: Sequential (dependency installation)
T001 → T002

# Phase 3: All tests can be written in parallel
T003, T004, T005, T006, T007, T008, T009, T010, T011, T012, T013, T014, T015

# Phase 3: Implementation must be sequential
T016 → T017 → T018

# Phase 4: Polish tasks can run in parallel
T020, T021

---

Parallel Example: User Story 1 Tests

Launch all unit tests together (different test functions, same file structure):

Task: "Unit test for markdown conversion with None/empty input"
Task: "Unit test for markdown headings conversion"
Task: "Unit test for markdown lists conversion"
Task: "Unit test for markdown bold/italic conversion"
Task: "Unit test for markdown code blocks conversion"
Task: "Unit test for markdown tables conversion"
Task: "Unit test for markdown links with security attributes"
Task: "Unit test for XSS prevention"
Task: "Unit test for image/embedded content exclusion"
Task: "Unit test for fallback to preformatted block"
Task: "Unit test for warning logs"
Task: "Contract test for template filter"
Task: "Integration test for page rendering"

---

Implementation Strategy

MVP First (User Story 1 Only - This Feature IS the MVP)

1. Phase 1: Setup (T001-T002) - Add dependencies
2. Phase 3: User Story 1
   • Write ALL tests first (T003-T015) - verify they FAIL
   • Implement utility module (T016)
   • Register filter (T017)
   • Update template (T018)
   • Run tests - verify they PASS
3. Phase 4: Polish (T019-T021) - Validation
4. STOP and VALIDATE: Test independently, deploy/demo

Test-First Workflow (MANDATORY per Constitution)

For EACH implementation task:

1. Write test that captures requirement
2. Run test → MUST FAIL (proves it tests something)
3. Implement minimum code to make test pass
4. Run test → MUST PASS
5. Refactor while keeping test green

---

Task Summary

Total Tasks: 21

• Setup: 2 tasks
• User Story 1 Tests: 13 tasks (T003-T015)
• User Story 1 Implementation: 3 tasks (T016-T018)
• Polish: 3 tasks (T019-T021)

Parallel Opportunities: 13 tests can run in parallel, 2 polish tasks can run in parallel

Critical Path: T001 → T002 → T003-T015 (parallel) → T016 → T017 → T018 → T019 → T020+T021 (parallel)

Independent Test Criteria for User Story 1:

• Navigate to feedback detail page with AI analysis
• Verify headings rendered as styled HTML (not ##)
• Verify lists have bullets/numbers
• Verify bold/italic formatting applied
• Verify code displayed in monospace with background
• Verify tables formatted with rows/columns
• Verify links clickable with target="_blank" and rel="noopener noreferrer nofollow"
• Verify XSS attempts (scripts/iframes) are stripped
• Verify images/embeds excluded from output
• Verify page loads in < 2 seconds

Suggested MVP Scope: Complete all of Phase 3 (this feature has only one user story - it IS the MVP)

---

Notes

• [P] tasks = Can run in parallel (different files or independent test functions)
• [US1] label = Task belongs to User Story 1
• Test-first discipline enforced: ALL tests (T003-T015) MUST be written and verified failing BEFORE implementation (T016-T018) begins
• Each task has exact file path for clarity
• Verify tests fail before implementing (Constitution requirement)
• Commit after each task or logical group
• This is a simple feature (1 utility file + 1 filter registration + 1 template change) but follows full TDD discipline