--- name: task-search description: Provides fast, case-insensitive text search across task titles, descriptions, and tags with debounced input, relevance ranking, and highlighted matching text. Uses AND logic for multi-token queries and limits results to top 50 for performance. --- # Task Search Skill ## Overview The task search skill enables users to quickly find specific tasks using text-based queries. It implements intelligent search algorithms with debouncing, relevance ranking, and visual highlighting of matched terms. ## When to Apply Apply this skill: - When user types in the search input field - After 300ms debounce delay from last keystroke - When displaying search results in task lists - When highlighting matched text in search results - When filtering large task datasets - When implementing search-as-you-type functionality ## Search Algorithm ### Case-Insensitive Partial Matching The search algorithm uses case-insensitive partial string matching: ```javascript function matchesSearchTerm(text, searchTerm) { return text.toLowerCase().includes(searchTerm.toLowerCase()); } // Examples matchesSearchTerm('Submit Report', 'submit'); // true matchesSearchTerm('Submit Report', 'SUBMIT'); // true matchesSearchTerm('Submit Report', 'port'); // true (partial match) matchesSearchTerm('Submit Report', 'xyz'); // false ``` ### Searchable Fields The search operates across three task fields: 1. **Title** (highest priority) 2. **Description** (medium priority) 3. **Tags** (lower priority) ```javascript function getSearchableText(task) { return { title: task.title || '', description: task.description || '', tags: (task.tags || []).join(' ') }; } ``` ### Multi-Token Search Logic The search uses **AND logic** for multiple tokens: ```javascript function tokenizeQuery(query) { return query.trim().split(/\s+/).filter(token => token.length > 0); } // Example: "urgent report" splits into ["urgent", "report"] // Task must match BOTH tokens to be included in results ``` **AND Logic Examples**: ```javascript // Query: "urgent report" // Tokens: ["urgent", "report"] // Match: Task with title "Urgent: Submit Report" // (contains both "urgent" AND "report") // No match: Task with title "Submit Report" // (contains "report" but not "urgent") // No match: Task with title "Urgent meeting" // (contains "urgent" but not "report") ``` ### Relevance Ranking Results are ranked by match location (highest to lowest priority): 1. **Exact title match** - Highest relevance 2. **Partial title match** - High relevance 3. **Description match** - Medium relevance 4. **Tag match** - Lower relevance ```javascript function calculateRelevanceScore(task, tokens) { const text = getSearchableText(task); let score = 0; tokens.forEach(token => { const lowerToken = token.toLowerCase(); // Exact title match: +100 points if (text.title.toLowerCase() === lowerToken) { score += 100; } // Partial title match: +50 points else if (text.title.toLowerCase().includes(lowerToken)) { score += 50; } // Description match: +10 points if (text.description.toLowerCase().includes(lowerToken)) { score += 10; } // Tag match: +5 points if (text.tags.toLowerCase().includes(lowerToken)) { score += 5; } }); return score; } ``` ### Result Limit Search results are limited to **top 50 matches** for performance: ```javascript const MAX_SEARCH_RESULTS = 50; function searchTasks(tasks, query) { const tokens = tokenizeQuery(query); if (tokens.length === 0) { return tasks; // No search query, return all } // Filter tasks that match all tokens const matches = tasks.filter(task => { const text = getSearchableText(task); const searchableString = `${text.title} ${text.description} ${text.tags}`.toLowerCase(); return tokens.every(token => searchableString.includes(token.toLowerCase()) ); }); // Calculate relevance scores const rankedMatches = matches.map(task => ({ task, score: calculateRelevanceScore(task, tokens) })); // Sort by relevance (highest first) rankedMatches.sort((a, b) => b.score - a.score); // Return top 50 results return rankedMatches.slice(0, MAX_SEARCH_RESULTS).map(item => item.task); } ``` ## Debounce Timing ### 300ms Delay Search executes **300ms after the last keystroke** to prevent excessive processing: ```javascript function useSearchDebounce(query, delay = 300) { const [debouncedQuery, setDebouncedQuery] = useState(query); useEffect(() => { const timer = setTimeout(() => { setDebouncedQuery(query); }, delay); return () => clearTimeout(timer); }, [query, delay]); return debouncedQuery; } // Usage in component function TaskSearch({ tasks }) { const [searchQuery, setSearchQuery] = useState(''); const debouncedQuery = useSearchDebounce(searchQuery, 300); const searchResults = useMemo(() => { return searchTasks(tasks, debouncedQuery); }, [tasks, debouncedQuery]); return (
setSearchQuery(e.target.value)} placeholder="Search tasks..." />
); } ``` ### Debounce Benefits - **Reduced CPU usage**: Prevents search on every keystroke - **Better UX**: Smoother typing experience - **Network efficiency**: Fewer API calls if searching backend - **Performance**: Limits processing for large task lists ## Text Highlighting ### Highlight Matched Terms Matched text is visually highlighted in search results: ```jsx function highlightText(text, query) { if (!query) return text; const tokens = tokenizeQuery(query); let highlightedText = text; tokens.forEach(token => { const regex = new RegExp(`(${escapeRegex(token)})`, 'gi'); highlightedText = highlightedText.replace( regex, '$1' ); }); return highlightedText; } function escapeRegex(string) { return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); } // Component implementation function HighlightedText({ text, query }) { const highlighted = highlightText(text, query); return ( ); } ``` ### Highlight Styling ```css mark { background-color: #FEF3C7; /* Light yellow background */ color: #92400E; /* Dark amber text */ padding: 2px 4px; border-radius: 2px; font-weight: 600; } /* Alternative purple theme to match VERY IMPORTANT */ mark.purple-theme { background-color: #EDE9FE; /* Light purple background */ color: #6B21A8; /* Dark purple text */ } ``` ### Highlighting Examples ```jsx // Query: "urgent" // Text: "Urgent: Submit Report" // Result: Urgent: Submit Report // Query: "report submit" // Text: "Submit urgent report" // Result: Submit urgent report // Query: "WORK" // Text: "Working on project" // Result: Working on project (case-insensitive) ``` ## Empty State Handling ### No Results Found When search returns zero results: ```jsx function SearchResults({ results, query }) { if (query && results.length === 0) { return (
🔍

No tasks found

No tasks match your search for "{query}"

Try different keywords or check your spelling

); } return (
{results.map(task => ( ))}
); } ``` ### Empty State Styling ```css .empty-state { text-align: center; padding: 48px 24px; color: #6B7280; } .empty-icon { font-size: 48px; margin-bottom: 16px; opacity: 0.5; } .empty-state h3 { font-size: 18px; font-weight: 600; color: #374151; margin-bottom: 8px; } .empty-state p { font-size: 14px; color: #6B7280; margin-bottom: 4px; } .empty-state .suggestion { font-size: 12px; color: #9CA3AF; font-style: italic; } ``` ## Complete Search Implementation ```jsx function TaskSearchComponent({ tasks, onSearchResults }) { const [searchQuery, setSearchQuery] = useState(''); const debouncedQuery = useSearchDebounce(searchQuery, 300); const searchResults = useMemo(() => { return searchTasks(tasks, debouncedQuery); }, [tasks, debouncedQuery]); useEffect(() => { onSearchResults(searchResults); }, [searchResults, onSearchResults]); const handleClearSearch = () => { setSearchQuery(''); }; return (
🔍 setSearchQuery(e.target.value)} placeholder="Search tasks by title, description, or tags..." className="search-input" /> {searchQuery && ( )}
{debouncedQuery && (
Found {searchResults.length} task{searchResults.length !== 1 ? 's' : ''} {searchResults.length >= 50 && ' (showing top 50)'}
)}
); } ``` ## Search Input Styling ```css .task-search { width: 100%; margin-bottom: 24px; } .search-input-wrapper { position: relative; display: flex; align-items: center; } .search-icon { position: absolute; left: 12px; font-size: 18px; color: #9CA3AF; pointer-events: none; } .search-input { width: 100%; padding: 12px 40px 12px 40px; border: 1px solid #D1D5DB; border-radius: 8px; font-size: 14px; transition: all 0.2s ease; } .search-input:focus { outline: none; border-color: #8B5CF6; /* Purple theme */ box-shadow: 0 0 0 3px rgba(139, 92, 246, 0.1); } .search-input::placeholder { color: #9CA3AF; } .clear-button { position: absolute; right: 12px; background: transparent; border: none; font-size: 20px; color: #6B7280; cursor: pointer; padding: 4px; transition: color 0.2s ease; } .clear-button:hover { color: #DC2626; /* Red on hover */ } .search-info { margin-top: 8px; font-size: 12px; color: #6B7280; font-weight: 500; } ``` ## Testing Examples ### Test Case 1: Single Token Search ```javascript const tasks = [ { id: 1, title: 'Submit Report', description: '', tags: [] }, { id: 2, title: 'Review Code', description: '', tags: [] }, { id: 3, title: 'Team Meeting', description: '', tags: [] } ]; const results = searchTasks(tasks, 'report'); // Expected: [{ id: 1, title: 'Submit Report', ... }] ``` ### Test Case 2: Multi-Token AND Logic ```javascript const tasks = [ { id: 1, title: 'Urgent Report', description: '', tags: [] }, { id: 2, title: 'Submit Report', description: '', tags: ['Urgent'] }, { id: 3, title: 'Urgent Meeting', description: '', tags: [] } ]; const results = searchTasks(tasks, 'urgent report'); // Expected: [ // { id: 1, title: 'Urgent Report', ... }, // { id: 2, title: 'Submit Report', tags: ['Urgent'], ... } // ] // Note: Task 3 excluded (has "urgent" but not "report") ``` ### Test Case 3: Relevance Ranking ```javascript const tasks = [ { id: 1, title: 'Report', description: 'Submit the report', tags: [] }, { id: 2, title: 'Meeting', description: 'Discuss report', tags: [] }, { id: 3, title: 'Annual Report', description: '', tags: [] } ]; const results = searchTasks(tasks, 'report'); // Expected order: // 1. id: 1 (exact title match + description match) // 2. id: 3 (partial title match) // 3. id: 2 (description match only) ``` ### Test Case 4: Case-Insensitive Search ```javascript const tasks = [ { id: 1, title: 'URGENT TASK', description: '', tags: [] } ]; const results = searchTasks(tasks, 'urgent'); // Expected: [{ id: 1, title: 'URGENT TASK', ... }] ``` ### Test Case 5: Tag Search ```javascript const tasks = [ { id: 1, title: 'Submit Report', description: '', tags: ['Work', 'Urgent'] }, { id: 2, title: 'Buy Groceries', description: '', tags: ['Personal'] } ]; const results = searchTasks(tasks, 'work'); // Expected: [{ id: 1, title: 'Submit Report', tags: ['Work', 'Urgent'], ... }] ``` ### Test Case 6: Empty Query ```javascript const tasks = [ { id: 1, title: 'Task 1', description: '', tags: [] }, { id: 2, title: 'Task 2', description: '', tags: [] } ]; const results = searchTasks(tasks, ''); // Expected: All tasks returned (no filtering) ``` ### Test Case 7: Top 50 Limit ```javascript const tasks = Array.from({ length: 100 }, (_, i) => ({ id: i + 1, title: `Task ${i + 1}`, description: 'Common description', tags: [] })); const results = searchTasks(tasks, 'task'); // Expected: Exactly 50 tasks returned ``` ## Performance Optimization ### Memoization ```javascript import { useMemo } from 'react'; function TaskList({ tasks, searchQuery }) { const filteredTasks = useMemo(() => { return searchTasks(tasks, searchQuery); }, [tasks, searchQuery]); return (
{filteredTasks.map(task => ( ))}
); } ``` ### Virtual Scrolling For large result sets, implement virtual scrolling: ```jsx import { FixedSizeList } from 'react-window'; function VirtualTaskList({ tasks, searchQuery }) { const filteredTasks = useMemo(() => { return searchTasks(tasks, searchQuery); }, [tasks, searchQuery]); const Row = ({ index, style }) => (
); return ( {Row} ); } ``` ## Integration Points This skill integrates with: - **Task Filter Skill**: Combines with filters (search + filters applied together) - **Task Sorting Skill**: Search results can be sorted - **Priority Classification Skill**: Search matches can include priority - **Task Tagging Skill**: Tags are searchable fields - **Task Organization Agent**: Uses search for task discovery ## Edge Cases ### Special Characters Escape special regex characters in search queries: ```javascript function escapeRegex(string) { return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); } // Query: "report (urgent)" // Escaped: "report \\(urgent\\)" ``` ### Whitespace Handling Trim and collapse whitespace: ```javascript function tokenizeQuery(query) { return query.trim().split(/\s+/).filter(token => token.length > 0); } // Query: " urgent report " // Tokens: ["urgent", "report"] ``` ### Empty Descriptions/Tags Handle null or undefined fields gracefully: ```javascript function getSearchableText(task) { return { title: task.title || '', description: task.description || '', tags: (task.tags || []).join(' ') }; } ``` ## Accessibility - Search input has clear focus states - Clear button has aria-label - Results count announced to screen readers - Keyboard navigation supported - Empty state is descriptive