Design Documentation Search

Searches across all design documentation to find relevant content, decisions, and patterns.

Overview

This skill provides full-text search across all design docs with filtering, ranking, and contextual results. Use it to quickly locate specific topics, architectural decisions, implementation patterns, or TODO items across the entire design documentation system.

Quick Start

Simple search:

/design-search "observability"

Filtered search:

/design-search "data flow" --category=architecture

Section-specific:

/design-search "performance" --section=Rationale

Parameters

Required

• query

  - Search query (keywords or phrase)

Optional

• module

  - Limit to specific module

• category

  - Filter by category (architecture, performance, etc.)

• status

  - Filter by status (stub, draft, current, etc.)

• section

  - Search only in specific sections

• context

  - Lines of context to show (default: 2)

Workflow

High-level search process:

1. Parse query and filters from user request
2. Load design.config.json to identify target modules
3. Find documents matching filters (module, category, status)
4. Execute search using Grep with appropriate context
5. Extract metadata from document frontmatter
6. Rank results by relevance, status, location, and recency
7. Format output with context, metadata, and navigation
8. Suggest related docs based on cross-references

For detailed implementation steps, see supporting documentation below.

Supporting Documentation

When you need detailed information, load the appropriate supporting file:

For Detailed Workflow

See instructions.md for:

• Complete step-by-step search workflow
• Frontmatter parsing and metadata extraction
• Result ranking algorithm and scoring
• Navigation path generation
• Edge case handling (no results, too many results)
• Performance optimization strategies
• Output customization options

Load when: Performing search or need implementation details

For Query Syntax

See query-syntax.md for:

• Search strategies (keyword, multi-term, section-specific, metadata)
• Search patterns (find decisions, implementations, TODOs, trade-offs)
• Query operators (grep options, regex patterns)
• Best practices and performance tips

Load when: Performing complex searches or need query syntax reference

For Filter Options

See filter-options.md for:

• All filter parameters and their valid values
• Filtering process and frontmatter extraction
• Result ranking algorithm and factors
• Advanced features (cross-references, highlighting, grouping)
• Performance optimization techniques

Load when: Applying filters, ranking results, or need filtering details

For Usage Examples

See examples.md for:

• Complete search examples (simple, filtered, section-specific)
• Output format examples
• Multi-filter searches
• Special cases (no results, too many results)
• Finding decisions, implementations, and TODOs

Load when: User needs examples or clarification on search usage

Error Handling

No Results Found

INFO: No matches found for "{query}"

Suggestions:
- Try broader search terms
- Remove filters
- Check spelling
- Search for related terms

Too Many Results

WARNING: {count} results found (showing top 20)

Suggestions:
- Add filters (module, category, status)
- Use more specific search terms
- Search in specific section

Invalid Filter

ERROR: Invalid {filter-name}: "{value}"
Valid values: {valid-list}

Integration

Works well with:

• /design-review

  - Review docs found in search

• /design-validate

  - Validate docs found

• /design-link

  - See relationships between search results

• /design-update

  - Update docs found in search

Success Criteria

A successful search:

• ✅ Finds all relevant matches
• ✅ Ranks results by relevance
• ✅ Provides sufficient context
• ✅ Shows document metadata
• ✅ Offers clear navigation paths
• ✅ Suggests related documents