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

# Tasks: Render AI Analysis as Formatted HTML

**Status**: ✅ **COMPLETED** (2025-10-18)
**Branch**: `003-render-ai-analyis`
**Input**: Design documents from `/specs/003-render-ai-analyis/`
**Prerequisites**: plan.md, spec.md

**Completion Summary**:
- All 21 tasks completed (T001-T021)
- 65 automated tests passing (36 unit, 14 contract, 15 integration)
- Manual security and performance validation complete
- Zero regressions in existing functionality
- Feature ready for production

**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

- [X] T001 Add markdown2==2.4.12 and bleach==6.1.0 to requirements.txt
- [X] 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

- [X] T003 [P] [US1] Unit test for markdown conversion with None/empty input in tests/unit/test_markdown_utils.py
- [X] T004 [P] [US1] Unit test for markdown headings conversion in tests/unit/test_markdown_utils.py
- [X] T005 [P] [US1] Unit test for markdown lists conversion in tests/unit/test_markdown_utils.py
- [X] T006 [P] [US1] Unit test for markdown bold/italic conversion in tests/unit/test_markdown_utils.py
- [X] T007 [P] [US1] Unit test for markdown code blocks conversion in tests/unit/test_markdown_utils.py
- [X] T008 [P] [US1] Unit test for markdown tables conversion in tests/unit/test_markdown_utils.py
- [X] T009 [P] [US1] Unit test for markdown links with security attributes in tests/unit/test_markdown_utils.py
- [X] T010 [P] [US1] Unit test for XSS prevention (script/iframe injection) in tests/unit/test_markdown_utils.py
- [X] T011 [P] [US1] Unit test for image/embedded content exclusion in tests/unit/test_markdown_utils.py
- [X] T012 [P] [US1] Unit test for fallback to preformatted block on exception in tests/unit/test_markdown_utils.py
- [X] T013 [P] [US1] Unit test for warning logs on conversion issues in tests/unit/test_markdown_utils.py
- [X] T014 [P] [US1] Contract test for markdown template filter behavior in tests/contract/test_markdown_filter.py
- [X] 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

- [X] T016 [US1] Create app/utils/markdown_utils.py with markdown_filter function implementing conversion, sanitization, link security, and error handling per plan.md specifications
- [X] T017 [US1] Register markdown filter in app/__init__.py create_app function (add app.jinja_env.filters['markdown'] = markdown_filter)
- [X] 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

- [X] 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).
- [X] 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").
- [X] 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

```bash
# 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):

```bash
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