ADR: Semantic search across ADR content (adr_search)

[rshade]

Priority: P2 - Medium Priority

Part of Epic: #289
Estimated Effort: 6-8 hours
Phase: 2 - Analysis & Validation

Problem Statement

As ADR collections grow, finding relevant decisions becomes difficult. Title-based search is insufficient - users need to search across all content including context, decisions, and consequences.

Proposed Solution

Implement adr_search tool that:

1. Searches across all ADR content (not just titles)
2. Returns relevance-scored results
3. Provides snippets with match context
4. Supports filtering by status

Implementation Guidance

Tool Schema

const AdrSearchArgsSchema = z.object({
  directory: z.string().optional()
    .describe("Working directory"),
  query: z.string()
    .describe("Search query (searches title, context, decision, consequences)"),
  status: z.enum(["proposed", "accepted", "rejected", "deprecated", "superseded"]).optional()
    .describe("Filter by status"),
  limit: z.number().optional()
    .describe("Max results (default: 10)"),
});

Search Result Interface

interface AdrSearchResult {
  adr: AdrMetadata;
  score: number;           // 0-1 relevance score
  matchedSections: string[]; // ["context", "decision"]
  snippet: string;         // "...found in the **authentication** layer..."
}

Scoring Algorithm

// Section weights (higher = more relevant for architecture)
const SECTION_WEIGHTS = {
  title: 3.0,
  decision: 2.5,
  context: 2.0,
  consequences: 1.5,
  options: 1.0,  // MADR
};

// Scoring factors:
// - Term frequency in section
// - Section weight
// - Exact phrase match bonus
// - Status bonus (accepted > proposed > deprecated)

Development Steps

1. Codebase Analysis

   • Review search patterns in codebase
   • Consider simple text matching vs full-text search

2. Implementation

   • Implement tokenization and matching
   • Implement relevance scoring
   • Generate contextual snippets
   • Add result caching

3. Testing Requirements

   • Test single-term queries
   • Test multi-term queries
   • Test phrase queries
   • Test status filtering
   • Test result ordering
   • Target: 85-90%+ coverage

4. Linting & Validation

   make lint
   make test
   make build

Acceptance Criteria

Feature Complete:

• Searches all ADR content
• Returns relevance-scored results
• Generates useful snippets
• Filters by status work
• Results are cached

Quality Gates:

• make lint passes with zero errors
• make test passes with 85-90%+ coverage
• make build completes successfully

Documentation:

• JSDoc comments for all public methods
• Update src/instructions.md

Example Usage

// Simple search
adr_search({ query: "authentication" })
// Returns:
// [
//   { adr: { number: 5, title: "Use OAuth2" }, score: 0.92,
//     matchedSections: ["title", "context", "decision"],
//     snippet: "...implement **authentication** using OAuth2..." },
//   { adr: { number: 8, title: "JWT Token Format" }, score: 0.78,
//     matchedSections: ["context"],
//     snippet: "...for **authentication** tokens we will use..." }
// ]

// Filter by status
adr_search({ query: "database caching", status: "accepted" })

// Limit results
adr_search({ query: "performance", limit: 5 })

References

• Epic: Epic: Architecture Decision Records (ADR) Tooling Support #289
• Depends on: Phase 1 tools (parsing)
• This is a key differentiator from existing ADR tools