Skip to content
Trilogy Care Logo TC Docs

spec

Feature Specification: Brain Knowledge Base

Epic: BKB - Brain Knowledge Base Initiative: TP-2141-Work-Management Created: 2025-11-29 Status: Draft Depends On: MDE (Markdown Documentation Editor) Input: User description: “Create a Docus-style UI to navigate and edit hierarchical documentation in .claude/BRAIN/ with tree sidebar, content editor, and table of contents”

Clarifications

Session 2025-11-29

  • Q: Where should document feedback be stored? → A: Database - store in application database with document_path, user_id, rating, comment
  • Q: What should display when Brain loads with no document selected? → A: Welcome page - show a default welcome/overview document (first doc in tree or dedicated index.md)

User Scenarios & Testing (mandatory)

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

A staff member needs to find information within the Brain knowledge base. They access the Brain section and see a collapsible folder tree on the left sidebar showing all folders and documents. They expand folders to browse the hierarchy and click on a document to view its contents in the main panel.

Why this priority: Navigation is the foundational capability - without it, users cannot access or discover content. The hierarchical structure mirrors how the team has already organized information, so supporting this mental model is essential.

Independent Test: Can be fully tested by navigating to Brain, expanding/collapsing folders in the tree, clicking documents, and verifying content displays correctly.

Acceptance Scenarios:

  1. Given a logged-in user accessing the Brain section, When the page loads, Then they see a left sidebar with a collapsible folder tree and a default welcome document in the center panel
  2. Given a user viewing the folder tree, When they click the expand arrow on a folder, Then the folder expands to show nested folders and documents
  3. Given a user viewing the folder tree, When they click the collapse arrow on an expanded folder, Then the folder collapses hiding its contents
  4. Given a user viewing the folder tree, When they click on a document name, Then the document content displays in the center panel
  5. Given a user viewing a document, When they look at the tree, Then the current document is visually highlighted in the navigation

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

A staff member is reading a long document and wants to jump to a specific section. The right sidebar displays an “On this page” table of contents generated from the document’s headings. They click a heading in the TOC to scroll directly to that section.

Why this priority: Long-form knowledge articles often contain multiple sections. In-page navigation reduces time spent scrolling and helps users understand document structure at a glance.

Independent Test: Can be fully tested by opening a document with multiple headings, verifying TOC displays, and clicking TOC items to confirm smooth scrolling to sections.

Acceptance Scenarios:

  1. Given a user viewing a document with headings, When the document loads, Then the right sidebar displays “On this page” with clickable heading links
  2. Given a user viewing the TOC, When they click a heading link, Then the page scrolls smoothly to that section in the document
  3. Given a user scrolling through a document, When they reach a new section, Then the corresponding TOC item is highlighted as active
  4. Given a document with nested headings (h2, h3), When the TOC renders, Then it shows heading hierarchy with appropriate indentation

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

A staff member has just read a document and wants to indicate whether it was helpful. They use a quick feedback widget to rate the document, optionally adding a comment about what could be improved.

Why this priority: Feedback helps identify which documents need improvement, but core navigation and editing must work first.

Independent Test: Can be fully tested by viewing a document, clicking a feedback emoji, optionally typing a comment, and verifying the feedback is recorded.

Acceptance Scenarios:

  1. Given a user viewing a document, When they look at the right sidebar below the TOC, Then they see a “Was this helpful?” prompt with emoji options
  2. Given a user clicking a feedback emoji, When they optionally add a comment, Then their feedback is submitted and they see a thank you message
  3. Given a user who previously gave feedback, When they return to the same document, Then they can update their feedback

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

A staff member finds outdated information in a Brain document and needs to update it. They click Edit, use the MDE editor to modify content with live preview, and save their changes.

Why this priority: The Brain is only useful if content stays current. Editing capability enables the team to maintain and improve documentation over time without developer assistance.

Independent Test: Can be fully tested by opening a Brain document, clicking Edit, making changes, saving, and verifying changes persist on refresh.

Acceptance Scenarios:

  1. Given a user viewing a Brain document, When they click the Edit button, Then the MDE editor opens with the document content loaded
  2. Given a user editing a document, When they modify content, Then they see a live preview of the rendered markdown
  3. Given a user who has made changes, When they click Save, Then the document is updated and they return to view mode
  4. Given a user editing a document, When they click Cancel, Then they return to view mode without saving changes

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

A staff member needs to add new knowledge to the Brain. They select a folder in the tree, click “New Document”, enter a title, write content using the MDE editor, and save the new document.

Why this priority: The knowledge base must grow to remain valuable. Document creation allows teams to capture new processes, decisions, and information as the organization evolves.

Independent Test: Can be fully tested by selecting a folder, clicking New Document, entering title and content, saving, and verifying the document appears in the tree.

Acceptance Scenarios:

  1. Given a user with a folder selected, When they click “New Document”, Then they see a form to enter the document title
  2. Given a user creating a document, When they enter a title and content, Then the MDE editor opens with the new document
  3. Given a user saving a new document, When the save completes, Then the document appears in the folder tree under the selected folder
  4. Given a user entering a title that already exists in the folder, When they save, Then the system auto-appends a number to create a unique filename

User Story 5 - Manage Folders (Priority: P3)

A staff member needs to reorganize the Brain structure by creating new folders, renaming existing ones, or removing empty folders. They use folder management controls to maintain the hierarchy.

Why this priority: As knowledge accumulates, reorganization becomes necessary. Folder management enables teams to evolve the structure without developer intervention.

Independent Test: Can be fully tested by creating a new folder, renaming it, and deleting it, verifying each operation updates the tree correctly.

Acceptance Scenarios:

  1. Given a user in the Brain section, When they click “New Folder”, Then they can enter a folder name and the folder is created
  2. Given a user right-clicking a folder, When they select “Rename”, Then they can edit the folder name inline
  3. Given a user with an empty folder selected, When they click Delete, Then they see a confirmation and the folder is removed
  4. Given a user with a non-empty folder selected, When they click Delete, Then they are warned the folder contains documents and must confirm explicit deletion

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

A staff member knows a topic exists somewhere in the Brain but doesn’t know the exact location. They use the search feature to find documents containing their search terms.

Why this priority: As the knowledge base grows, hierarchical browsing becomes insufficient. Search provides a fast path to relevant content regardless of location in the tree.

Independent Test: Can be fully tested by entering a search term, verifying matching documents appear in results, and clicking a result to navigate to it.

Acceptance Scenarios:

  1. Given a user in the Brain section, When they type in the search field, Then they see matching documents from across all folders
  2. Given search results displayed, When they click a result, Then the document opens and the tree expands to show its location
  3. Given a search with no matches, When results display, Then the user sees a “No documents found” message

Edge Cases

  • Empty folders: Display folders with no documents; allow deletion without warning
  • Very deep nesting (>5 levels): Render all levels; consider horizontal scroll if tree width exceeds sidebar
  • Documents without headings: Show “On this page” panel with “No sections” message or hide TOC
  • Large documents (>100KB): Use debounced preview per MDE behavior (500ms delay)
  • Special characters in folder/document names: Slugify per MDE conventions
  • Concurrent editing: Show “User X is editing” indicator per MDE behavior
  • Folder with same name as sibling document: Allow both to exist; differentiate with folder icon

Requirements (mandatory)

Functional Requirements

Navigation:

  • FR-001: System MUST display a left sidebar with a collapsible folder tree
  • FR-002: System MUST render all folders and documents from .claude/BRAIN/ directory
  • FR-003: System MUST allow expanding and collapsing folders with click or keyboard
  • FR-004: System MUST highlight the currently selected document in the tree
  • FR-005: System MUST persist tree expansion state during the session
  • FR-024: System MUST support section headers in tree (e.g., “OVERVIEW”, “PROCESSES”) to group folders
  • FR-029: System MUST display a default welcome document on initial load (index.md at root or first document in tree)

Document Viewing:

  • FR-006: System MUST display selected document content in the center panel
  • FR-007: System MUST render markdown content as formatted HTML
  • FR-008: System MUST extract headings and display them in a right sidebar TOC
  • FR-009: System MUST scroll to sections when TOC items are clicked
  • FR-010: System MUST highlight active TOC item based on scroll position

Document Feedback:

  • FR-025: System MUST display a “Was this helpful?” widget below the TOC
  • FR-026: System MUST allow users to rate helpfulness via emoji selection (positive, neutral, negative)
  • FR-027: System MUST allow optional comment input with feedback
  • FR-028: System MUST store feedback in the application database with document_path, user_id, rating, and optional comment

Document Editing (via MDE):

  • FR-011: System MUST reuse MDE editor components for editing Brain documents
  • FR-012: System MUST provide an Edit button on document view
  • FR-013: System MUST preserve all MDE editing features (live preview, auto-save, validation)

Document Creation:

  • FR-014: System MUST allow creating new documents within any folder
  • FR-015: System MUST prompt for document title before opening editor
  • FR-016: System MUST generate valid filename from title per MDE conventions

Folder Management:

  • FR-017: System MUST allow creating new folders at any level
  • FR-018: System MUST allow renaming folders
  • FR-019: System MUST allow deleting empty folders without warning
  • FR-020: System MUST require confirmation for deleting non-empty folders

Search:

  • FR-021: System MUST provide full-text search across Brain documents
  • FR-022: System MUST display search results with document title and path
  • FR-023: System MUST expand tree and navigate to document when result is clicked

Key Entities

  • Brain Folder: A directory within .claude/BRAIN/ that can contain documents and subfolders. Has a name and path.
  • Brain Document: A markdown file within .claude/BRAIN/. Has title (from filename or h1), content, and path.
  • Tree Node: UI representation of either a folder (expandable) or document (selectable) in the navigation sidebar.
  • TOC Entry: A heading extracted from document content with level (h1-h6), text, and anchor ID.
  • Document Feedback: Database record containing document_path, user_id, rating (positive/neutral/negative), optional comment, and timestamp.
  • Section Header: A non-navigable grouping label in the tree sidebar (e.g., “OVERVIEW”, “PROCESSES”) used to organize folders visually.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: Users can locate a known document via tree navigation within 10 seconds
  • SC-002: Users can navigate to a specific section using TOC within 3 seconds
  • SC-003: Users can create a new document within 60 seconds of starting the action
  • SC-004: Users can create a new folder within 30 seconds
  • SC-005: Search returns relevant results within 1 second
  • SC-006: Tree expansion state persists across document selections within a session
  • SC-007: System handles folder structures up to 5 levels deep without UI degradation
  • SC-008: 90% of users can successfully navigate to and edit a document without assistance

Assumptions

  • MDE (Markdown Documentation Editor) feature is implemented and available for reuse
  • Users have appropriate authentication to access the Brain section
  • Any authenticated user with Brain access can view, create, edit, and manage content
  • The existing .claude/BRAIN/ directory structure will be read/write accessible
  • Documents in Brain use standard markdown format (no frontmatter required)
  • Folder naming follows filesystem conventions (alphanumeric, hyphens, underscores)
  • Browser supports required features for tree component (modern browsers only)
  • Tree and TOC component libraries may be used from existing project dependencies
  • Section headers in tree can be defined via folder naming convention (e.g., folders starting with numbers like “1. OVERVIEW” become section headers)

Out of Scope (Future Considerations)

Phase 2: Tab-Based Architecture

GitBook-style top tabs for multiple content collections (e.g., “Brain”, “API Docs”, “Guides”, “Changelog”). Phase 1 components should be built with extensibility in mind:

  • Tree sidebar accepts rootPath prop (not hardcoded to .claude/BRAIN/)
  • URL routing supports /brain/{path} pattern for future /docs/{path}, /guides/{path}
  • Search component accepts scope parameter for tab-specific or cross-tab search

Other Future Enhancements

  • Version history: Document version tracking beyond what MDE provides
  • Multi-user real-time editing: Collaborative simultaneous editing (MDE’s “soft lock” approach is sufficient for initial release)
  • Advanced search: Filters, operators, fuzzy matching
  • Analytics: Most viewed docs, least helpful ratings, usage patterns