tasks

Tasks: Brain Knowledge Base (BKB)

Spec: spec.md Plan: plan.md Design: design-spec.md Created: 2025-11-29 Depends On: MDE (Markdown Documentation Editor) - Phases 5-6 blocked until complete

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

[P]: Can run in parallel (different files, no dependencies)
[Story]: Which user story this task belongs to (US1, US2, US2b, US3, US4, US5, US6)
All paths relative to repository root

User Story Mapping

ID	Story	Priority	Title
US1	Navigate Hierarchical Documentation	P1	Tree navigation, folder expand/collapse
US2	View Document with Table of Contents	P1	Content viewing, TOC, scroll spy
US2b	Provide Document Feedback	P3	Emoji rating widget
US3	Edit Brain Documents	P2	Edit using MDE components
US4	Create New Documents	P2	New document creation
US5	Manage Folders	P3	Create/rename/delete folders
US6	Search Brain Content	P3	Full-text search

Phase 1: Setup (Shared Infrastructure)

Purpose: Project initialization, domain structure, database schema

T001 Create domain/Brain/ directory structure per plan.md
T002 [P] Create migration for document_feedback table in database/migrations/
T003 [P] Create TypeScript interfaces in resources/js/types/brain.d.ts
T004 [P] Create routes file at domain/Brain/Routes/brainRoutes.php
T005 Register Brain routes in routes/web.php

Phase 2: Foundation (Blocking Prerequisites)

Purpose: Core backend services and layout that ALL user stories depend on

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

Checkpoint: Navigate to /brain, see three-column layout skeleton

Phase 3: User Story 1 - Navigate Hierarchical Documentation (Priority: P1)

Goal: Interactive tree with folder expand/collapse and document selection

Independent Test: Navigate to /brain, expand folders in tree, click documents, verify tree state persists across navigation

Implementation for User Story 1

T016 [US1] Create TreeSidebar.vue container in resources/js/Components/Brain/Tree/
T017 [P] [US1] Create TreeNode.vue recursive component in resources/js/Components/Brain/Tree/
T018 [P] [US1] Create TreeSectionHeader.vue styling in resources/js/Components/Brain/Tree/
T019 [US1] Create useTreeState.ts composable in resources/js/composables/
T020 [US1] Implement keyboard navigation (arrows, enter) in TreeNode.vue
T021 [US1] Persist expansion state to session storage in useTreeState.ts
T022 [US1] Highlight selected document in tree with border-l-4 styling
T023 [US1] Integrate tree into BrainLayout.vue left panel
T024 [US1] Navigate to document on tree node click via Inertia router

Checkpoint: User Story 1 complete - Tree navigation fully functional

Phase 4: User Story 2 - View Document with Table of Contents (Priority: P1)

Goal: Display markdown content with TOC and scroll spy

Independent Test: Click a document with multiple headings, verify TOC displays, click TOC items to scroll, verify scroll spy highlights active heading

Implementation for User Story 2

Checkpoint: User Stories 1 AND 2 complete - Full navigation and viewing functional

Phase 5: User Story 6 - Search Brain Content (Priority: P3)

Goal: Find documents by search term, navigate to results

Independent Test: Type search term, verify matching documents appear, click result to navigate and expand tree to location

Note: Implementing before P2 stories because it has no MDE dependency

Implementation for User Story 6

T035 [US6] Create SearchInput.vue in resources/js/Components/Brain/Search/
T036 [P] [US6] Create SearchResults.vue dropdown in resources/js/Components/Brain/Search/
T037 [US6] Create useBrainSearch.ts client-side search in resources/js/composables/
T038 [US6] Add search API endpoint GET /api/brain/search in BrainApiController.php
T039 [US6] Navigate to document on result click via Inertia router
T040 [US6] Auto-expand tree to show result location via useTreeState.ts
T041 [US6] Integrate search into TreeSidebar.vue header

Checkpoint: User Stories 1, 2, AND 6 complete - Browse and search functional

Phase 6: User Story 3 - Edit Brain Documents (Priority: P2)

Goal: Edit documents using MDE editor components

Independent Test: Open a document, click Edit, modify content, save, verify changes persist on refresh

BLOCKED: Requires MDE (Markdown Documentation Editor) feature to be complete

Implementation for User Story 3

T042 [US3] Add Edit button to ContentHeader.vue
T043 [US3] Create UpdateBrainDocumentRequest.php in domain/Brain/Http/Requests/
T044 [US3] Add update endpoint PUT /api/brain/document/{path} in BrainApiController.php
T045 [US3] Integrate MDE MarkdownEditor.vue component into ContentPanel.vue
T046 [US3] Implement edit mode toggle state in ContentPanel.vue
T047 [US3] Handle save/cancel flow with Inertia form
T048 [US3] Reuse MDE concurrent edit detection (if available)

Checkpoint: User Stories 1, 2, 3, AND 6 complete - View and edit functional

Phase 7: User Story 4 - Create New Documents (Priority: P2)

Goal: Create new documents within any folder

Independent Test: Select folder, click New Document, enter title, save, verify document appears in tree

BLOCKED: Requires MDE (Markdown Documentation Editor) feature to be complete

Implementation for User Story 4

T049 [US4] Create NewDocumentModal.vue in resources/js/Components/Brain/Modals/
T050 [P] [US4] Create TreeActions.vue (New Doc/Folder buttons) in resources/js/Components/Brain/Tree/
T051 [US4] Create StoreBrainDocumentRequest.php in domain/Brain/Http/Requests/
T052 [US4] Add create endpoint POST /api/brain/document in BrainApiController.php
T053 [US4] Implement filename generation (slugify) in BrainService.php
T054 [US4] Open editor after creation via Inertia redirect
T055 [US4] Add new document to tree via reactive props refresh
T056 [US4] Integrate TreeActions into TreeSidebar.vue

Checkpoint: User Stories 1-4 AND 6 complete - Full CRUD for documents

Phase 8: User Story 5 - Manage Folders (Priority: P3)

Goal: Create, rename, and delete folders

Independent Test: Create folder, rename it, delete it, verify tree updates correctly each time

Implementation for User Story 5

T057 [US5] Create NewFolderModal.vue in resources/js/Components/Brain/Modals/
T058 [P] [US5] Create RenameModal.vue in resources/js/Components/Brain/Modals/
T059 [P] [US5] Create DeleteModal.vue confirmation in resources/js/Components/Brain/Modals/
T060 [US5] Create TreeContextMenu.vue right-click menu in resources/js/Components/Brain/ContextMenu/
T061 [US5] Create StoreBrainFolderRequest.php in domain/Brain/Http/Requests/
T062 [US5] Add folder CRUD endpoints in BrainApiController.php:
- POST /api/brain/folder (create)
- PUT /api/brain/folder/{path} (rename)
- DELETE /api/brain/folder/{path} (delete)
T063 [US5] Implement section header checkbox in NewFolderModal.vue
T064 [US5] Delete confirmation with content warning for non-empty folders
T065 [US5] Integrate context menu into TreeNode.vue

Checkpoint: User Stories 1-6 complete - Full folder management

Phase 9: User Story 2b - Provide Document Feedback (Priority: P3)

Goal: Document helpfulness ratings with emoji widget

Independent Test: View document, click feedback emoji, optionally add comment, verify feedback persists on return

Implementation for User Story 2b

T066 [US2b] Create DocumentFeedback.php Eloquent model in domain/Brain/Models/
T067 [P] [US2b] Create BrainFeedbackService.php in domain/Brain/Services/
T068 [US2b] Create StoreFeedbackRequest.php in domain/Brain/Http/Requests/
T069 [US2b] Create FeedbackWidget.vue emoji buttons in resources/js/Components/Brain/Feedback/
T070 [P] [US2b] Create FeedbackComment.vue optional textarea in resources/js/Components/Brain/Feedback/
T071 [US2b] Create useFeedback.ts composable in resources/js/composables/
T072 [US2b] Add feedback endpoints in BrainApiController.php:
- POST /api/brain/feedback (submit)
- GET /api/brain/feedback/{path} (get existing)
T073 [US2b] Show existing feedback on return visit via props
T074 [US2b] Integrate feedback widget into TocPanel.vue below TOC

Checkpoint: All user stories complete - Full feature functional

Phase 10: Polish & Cross-Cutting Concerns

Purpose: Edge cases, accessibility, performance, testing

Checkpoint: Feature complete, tested, accessible, performant

Dependencies & Execution Order

Phase Dependencies

graph TD
    P1[Phase 1: Setup] --> P2[Phase 2: Foundation]
    P2 --> P3[Phase 3: US1 Tree Navigation]
    P2 --> P4[Phase 4: US2 Content + TOC]
    P3 --> P4
    P4 --> P5[Phase 5: US6 Search]

    MDE[MDE Feature] --> P6[Phase 6: US3 Editing]
    MDE --> P7[Phase 7: US4 Create Docs]
    P4 --> P6
    P4 --> P7

    P5 --> P8[Phase 8: US5 Folders]
    P6 --> P8

    P4 --> P9[Phase 9: US2b Feedback]

    P6 --> P10[Phase 10: Polish]
    P7 --> P10
    P8 --> P10
    P9 --> P10

External Dependency

MDE Feature: Phases 6-7 (Editing, Document Creation) are BLOCKED until MDE is complete
Phases 1-5, 8-9: Can proceed without MDE

Within Each User Story

Models before services
Services before controllers
Controllers before Vue components
Core implementation before integration
Story complete before checkpoint

Parallel Opportunities

Phase 1 (all parallel): T002, T003, T004 can run simultaneously Phase 2: T007, T008, T009, T011, T013 can run in parallel Phase 3: T017, T018 can run in parallel Phase 4: T026, T027, T029 can run in parallel Phase 5: T036 can run parallel with T035 Phase 8: T058, T059 can run in parallel Phase 9: T067, T070 can run in parallel Phase 10: Most tasks marked [P] can run in parallel

MVP Delivery Strategy

MVP Option 1: View-Only (No MDE Dependency)

Complete phases 1-5 for a fully functional read-only Brain:

Tree navigation (US1)
Document viewing with TOC (US2)
Search (US6)

Tasks: T001-T041 (41 tasks)

MVP Option 2: Full CRUD (After MDE)

Complete all phases for full Brain functionality including editing:

All of MVP Option 1
Plus editing (US3), creation (US4), folders (US5), feedback (US2b)

Tasks: T001-T089 (89 tasks)

Recommended Approach

Immediate: Start Phase 1-5 (no MDE dependency)
After MDE: Complete Phase 6-7 (editing, creation)
Polish: Complete Phase 8-10 (folders, feedback, polish)

Summary

Phase	User Story	Tasks	Parallel Tasks	Blocked By
1	Setup	5	3	None
2	Foundation	10	5	Phase 1
3	US1 Navigation	9	2	Phase 2
4	US2 Content/TOC	10	3	Phase 3
5	US6 Search	7	1	Phase 4
6	US3 Editing	7	0	MDE, Phase 4
7	US4 Create Docs	8	1	MDE, Phase 4
8	US5 Folders	9	2	Phase 5, 6
9	US2b Feedback	9	2	Phase 4
10	Polish	15	9	Phase 6-9
Total		89	28