nexus-a1/search-requirements

Search Requirements

Search the team's requirements knowledge base for similar past work.

Purpose

Find past implementations, architectural decisions, and lessons learned from similar features to inform current work.

When to Use

• Before starting new feature work (research phase)
• Looking for implementation patterns to reuse
• Finding past decisions on similar problems
• Exploring team's historical knowledge

Arguments

/search-requirements <query>

query (required): Search query

• Can be keywords (e.g., "user export excel")
• Can include filters (e.g., "tag:export component:UserService")
• Can combine multiple terms

Search Syntax

Keyword search:

/search-requirements "user authentication"

Tag filter:

/search-requirements "tag:export,api"

Component filter:

/search-requirements "component:UserController"

Date filter:

/search-requirements "export after:2025-01-01"

Combined:

/search-requirements "export tag:excel component:UserService after:2025-01-01"

Process

Step 1: Check Configuration

Read project configuration:

# Source resolve-config: marketplace installs get ${CLAUDE_PLUGIN_ROOT} substituted
# inline before bash runs; ./install.sh users fall back to ~/.claude. If neither
# path resolves, fail loudly rather than letting resolve_artifact be undefined.
if [ -f "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh" ]; then
  source "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh"
elif [ -f "$HOME/.claude/shared/resolve-config.sh" ]; then
  source "$HOME/.claude/shared/resolve-config.sh"
else
  echo "ERROR: resolve-config.sh not found. Install via marketplace or run ./install.sh" >&2
  exit 1
fi
IFS='|' read -r REPO _TYPE <<< "$(resolve_artifact_typed requirements requirements)"
_BASE="$(dirname "$REPO")"

If the storage location type is git, sync before reading:

if [[ "$_TYPE" == "git" ]]; then
  cd "$_BASE" && git pull
fi

Extract requirements artifact path from storage configuration.

If not configured:

Requirements storage not configured

To search past work, configure requirements storage:
1. See: ~/.claude/templates/requirements-repo/README.md
2. Add to .claude/configuration.yml:

storage:
  locations:
    team-knowledge:
      type: git
      path: /path/to/team-knowledge
  artifacts:
    requirements: { location: team-knowledge, subdir: requirements }

Step 2: Delegate to Archivist

Use Task tool with subagent_type: "archivist":

Task(archivist, "Search requirements repository

Query: ${query}
Configuration: ${requirements_config}

Tasks:
1. Sync requirements repository (if sync_command configured)
2. Parse query for keywords, filters, date ranges
3. Load index.json for fast search
4. Calculate relevance scores for matching tickets
5. Rank results by relevance (0.0-1.0)
6. Return top results with summaries

Search dimensions:
- Keyword match (title, description, requirements text)
- Tag match (if filters specified)
- Component match (if filters specified)
- Date range (if specified)

Return:
- Top 10 results ranked by relevance
- Each result: id, title, summary, relevance score, tags, components
- Total matches found
")

Step 3: Display Results

Format results:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Search Results: "${query}"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found 7 matches (showing top 5):

[1] USER-123: User data export to Excel (relevance: 0.95) ⭐
    Tags: export, excel, queue, user-data
    Components: UserController, ExportService, ExportJob
    Date: 2026-02-20

    Summary: Queue-based async export with PhpSpreadsheet.
    Handles 10k+ users without timeout. S3 storage with
    7-day retention.

    Match reason: High keyword match: 'export', 'excel'.
    Same component: ExportService.

─────────────────────────────────────────────────

[2] REPORT-200: Report export system (relevance: 0.82)
    Tags: export, pdf, reports
    Components: ReportController, ExportService
    Date: 2026-01-15

    Summary: PDF report generation with async processing.
    Uses dompdf library with queue jobs.

    Match reason: Keyword match: 'export'. Component
    overlap: ExportService.

─────────────────────────────────────────────────

[3] INVOICE-300: Invoice export (relevance: 0.75)
    Tags: export, pdf, invoices
    Components: InvoiceController, PdfGenerator
    Date: 2025-12-10

    Summary: Sync invoice export to PDF with template
    system.

    Match reason: Keyword match: 'export'.

─────────────────────────────────────────────────

Load details: /load-requirements <id>
Search again: /search-requirements "<new query>"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

No results:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Search Results: "${query}"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

No matches found.

Suggestions:
- Try broader keywords: "export" instead of "excel export"
- Check spelling
- Try related terms: "download" instead of "export"
- Browse by tag: /search-requirements "tag:export"
- Browse recent work: /search-requirements "after:2025-01-01"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Examples

Example 1: Keyword Search

/search-requirements "user authentication"

Finds tickets related to user authentication.

Example 2: Tag Filter

/search-requirements "tag:export"

Finds all tickets tagged with "export".

Example 3: Component Search

/search-requirements "component:UserController"

Finds tickets that modified UserController.

Example 4: Combined Search

/search-requirements "authentication tag:jwt,oauth component:AuthService"

Finds authentication tickets with JWT/OAuth tags that modified AuthService.

Example 5: Date Range

/search-requirements "api after:2025-06-01"

Finds API-related tickets from June 2025 onwards.

Example 6: Recent Work

/search-requirements "after:2025-01-01"

Browses all work from this year.

Search Tips

Effective Queries

✅ Good:

• "user export" - Broad, finds variations
• "tag:export" - Finds all export-related work
• "component:UserService" - Finds all changes to UserService
• "authentication after:2025-01-01" - Recent auth work

❌ Less Effective:

• "user export feature to excel with async processing" - Too specific
• "USER-123" - Use /load-requirements for specific IDs
• "how to implement export" - Use natural keywords instead

Understanding Relevance Scores

• 0.9-1.0 ⭐ - Highly relevant, likely very similar work
• 0.7-0.9 - Relevant, useful context
• 0.5-0.7 - Somewhat relevant, may have useful patterns
• < 0.5 - Low relevance, filtered out

Refining Search

Too many results?

• Add more specific keywords
• Use tag filters: "tag:export,excel"
• Use component filters: "component:UserService"
• Narrow date range: "after:2025-06-01"

Too few results?

• Use broader keywords: "export" vs "excel export"
• Remove filters
• Try related terms: "download" vs "export"
• Search by technology: "tag:phpspreadsheet"

Search Filters Reference

Tag Filters

tag:export          # Single tag
tag:export,api      # Multiple tags (OR)
tag:export tag:api  # Multiple tags (AND)

Component Filters

component:UserController              # Single component
component:UserController,AuthService  # Multiple (OR)

Date Filters

after:2025-01-01     # On or after date
before:2025-12-31    # On or before date
after:2025-01-01 before:2025-06-30  # Date range

Project Filters

project:main-app     # Filter by project
project:api-service  # Different project

Status Filters

status:completed     # Only completed work
status:archived      # Only archived work

Common Searches

Browse by Category

/search-requirements "tag:authentication"
/search-requirements "tag:api"
/search-requirements "tag:database"
/search-requirements "tag:export"
/search-requirements "tag:integration"

Browse by Technology

/search-requirements "tag:jwt"
/search-requirements "tag:aws"
/search-requirements "tag:queue"
/search-requirements "tag:redis"

Browse Recent Work

/search-requirements "after:2025-01-01"  # This year
/search-requirements "after:2025-06-01"  # Last 6 months

Find Similar to Current Work

If working on authentication feature:

/search-requirements "authentication tag:jwt"

If working on export:

/search-requirements "export tag:excel,pdf"

Error Handling

Repository Not Found

❌ Requirements repository not found

Configured path: /path/to/requirements-repo
Error: Directory does not exist

Check CLAUDE.md configuration.

Index Corrupted

❌ Search failed: Index file corrupted

Path: /path/to/requirements-repo/index.json
Error: Invalid JSON

To fix:
1. /rebuild-requirements-index
2. Or restore from backup: git checkout HEAD~1 index.json

Retry search after fixing.

No Results

No matches found for: "${query}"

Try:
- Broader keywords
- Different search terms
- Browse by tag: /search-requirements "tag:export"
- Browse recent: /search-requirements "after:2025-01-01"

Performance

Fast search:

• Index-based search (no file reads)
• Results in < 100ms for typical repositories

Scales to:

• 1000+ archived requirements
• Complex queries with multiple filters

See Also

• /load-requirements <id> - Load full details for a result
• /archive-requirements [id] - Archive completed work
• /rebuild-requirements-index - Fix corrupted index