Skip to content

feat(sdd): configurable search strategy for code-reading phases #266

@Lotto724

Description

@Lotto724

Problem

SDD phases that investigate the codebase (sdd-explore, sdd-apply, sdd-verify) rely on brute-force Grep+Read with no configurable search backend. Token consumption scales linearly with codebase size — there is no extension point to leverage semantic/vector code search via MCP RAG servers.

Currently:

  • sdd-phase-common.md has no section about code search
  • sdd-explore Step 3 is prose ("read entry points and key files")
  • sdd-apply Step 2 says "read existing code" with no mechanism
  • sdd-verify Step 4 says "search codebase for implementation evidence" with no mechanism

Proposal

Add a search_strategy config (top-level key alongside strict_tdd) with two modes:

Mode Behavior
grep Default. Current behavior — Grep + Read. Zero change for existing users.
hybrid RAG-first cascade with grep fallback. Requires search_strategy.rag.mcp_tool.

Hybrid cascade (each step strictly additive)

1. Semantic query → MCP RAG tool → relevant chunks
   ├── Sufficient (≥2 snippets)? → use them
   └── Insufficient?
       ↓
2. Grep → exact symbol/pattern match
       ↓
3. Read → targeted line ranges (NOT full files)

Config schema

search_strategy:
  mode: grep | hybrid
  rag:
    mcp_tool: "tool_name"       # REQUIRED for hybrid
    reindex_tool: "tool_name"   # optional — fire-and-forget after sdd-apply batch

Design

Follows the strict_tdd pattern exactly:

  1. Auto-detected in sdd-init (Step 3.5) — scans MCP tools, no interactive prompts
  2. Persisted in project context (engram or openspec/config.yaml)
  3. Each code-reading phase reads config and branches via shared Section E protocol
  4. Missing config = grep = current behavior (zero regression)

Files affected

File Change
_shared/sdd-phase-common.md New Section E: Code Search Protocol
_shared/persistence-contract.md search_strategy schema in sub-agent context
sdd-init/SKILL.md Step 3.5 + config output + summary rows
sdd-explore/SKILL.md Step 3 references Section E
sdd-apply/SKILL.md Step 2 references Section E + reindex hook in Step 6
sdd-verify/SKILL.md Step 4 references Section E

Out of scope

  • Standalone rag mode without grep fallback
  • Multiple simultaneous RAG tools
  • Embedding generation or vector DB management

Metadata

Metadata

Assignees

No one assigned

    Labels

    status:approvedApproved for implementation — PRs can now be opened

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions