pal-e-docs

Review: Hybrid search -- RRF blending + semantic search

review-1570-2026-06-23 Review

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- decomposed from paldocs#52, depends on #52 and #59
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- MCP layer needs Rails semantic and hybrid search endpoints
  • [x] Context -- explains relationship to #52 (embeddings) and #59 (search stub)
  • [x] File Targets -- 2 files to create/modify, 3 files excluded with rationale
  • [x] Feature Flag -- none (replaces stub)
  • [x] Acceptance Criteria -- 3 criteria, all testable
  • [x] Test Expectations -- unit + 2 integration tests, run command specified
  • [x] Constraints -- RRF formula, neighbor gem usage, tsvector dependency documented
  • [x] Checklist -- standard 5-item checklist
  • [x] Related -- project, story, arch note, upstream/downstream issues all listed

Traceability

  • [x] story:consolidation label -- story-paldocs-consolidation
  • [x] story note verified -- found in project-paldocs user-stories section
  • [x] arch:rails-api label -- rails-api component
  • [x] arch note verified -- arch-rails-api note exists in pal-e-docs
  • [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/paldocs/issues/61, open

File Targets

  • [x] app/services/hybrid_search.rb -- to be created. Services directory pattern established by ollama_client.rb on main.
  • [x] app/controllers/api/search_controller.rb -- to be created or modified from #59 stub. Does not exist on main yet.
  • [x] app/models/block.rb -- correctly excluded. Has has_neighbors :embedding from #52.
  • [x] app/jobs/ -- correctly excluded. EmbedBlockJob exists from #52.
  • [x] db/migrate/ -- correctly excluded. No schema changes needed.

Repo Placement

OK. Single-repo ticket, all targets in ldraney/paldocs.

Dependencies

  • paldocs#52 (embedding pipeline) -- CLOSED, merged on main. Dependency satisfied.
  • paldocs#59 (search controller stub) -- OPEN. Non-blocking: agent can create controller directly without stub.
  • paldocs#54 (MCP server) -- downstream, sprint:3, no conflict.
  • Note.keyword_search exists in note.rb using PostgreSQL tsvector -- available for RRF keyword leg.

Acceptance Criteria

3 criteria, all agent-verifiable. Tests need blocks with pre-computed embeddings (mock or fixture vectors).

Blast Radius

Low. Adds new files and routes only. No modification to existing code. Only shared touchpoint is config/routes.rb.

Decomposition Assessment

No decomposition needed. 2 file targets, 1 repo, 3 AC. Under 5 minutes.

Recommendation

No action needed. Scope is solid, traceability complete, file targets verified, dependencies satisfied or non-blocking.