feat: symbol ranking, smart snippets, and edit decision card

[PatrickSys]

Summary

Cleaned up the edit decision card and sharpened search ranking for symbol queries.

When searching for a specific symbol (like a class name), the file that defines it now ranks above files that just import it. Snippets include a scope header so you see context at a glance. And the preflight response for edit intent is now lean and actionable — ready, nextAction, patterns to follow/avoid, caller coverage so you know which files you haven't looked at yet, and concrete next steps in whatWouldHelp when you need more evidence.

Removed the internal fields that used to leak (evidenceLock, riskLevel, confidence, intent, circularDependencies). The decision card is stable by design.

Changes

Search ranking (SEARCH-01):

• Definition-first boost: when intent is EXACT_NAME, results where symbolName matches the query get +15% score boost
• Symbol-level dedup: within each symbol group (symbolPath), keep only the highest-scoring chunk (prevents duplicate methods from the same class clogging the top slots)

Smart snippets (SEARCH-02):

• When includeSnippets: true, code chunks include a scope header comment (// ClassName.methodName) before the snippet
• Fallback to basic snippet if no metadata available

Clean decision card (PREF-01 to PREF-04):

• New output shape: { ready, nextAction?, warnings?, patterns?, bestExample?, impact?, whatWouldHelp? }
• ready: boolean, whether evidence is sufficient to edit
• nextAction: why evidence is thin (only when ready=false)
• warnings: failure memories (capped at 3)
• patterns: do/avoid patterns with adoption %, capped at 3 each
• bestExample: top 1 golden file for the area
• impact: caller coverage ("X/Y callers in results") + top 3 files importing the results
• whatWouldHelp: concrete next steps when ready=false (max 4 items)

Impact coverage (PREF-02):

• Tracks which known callers appear in search results
• Low coverage (< 40% with > 3 total callers) triggers epistemic stress
• Surfaces in impact card: "3/5 callers in results" tells you 2 callers weren't searched yet

whatWouldHelp recommendations (PREF-03):

• Generated when ready=false from evidence gaps
• "Search with more specific query targeting implementation files"
• "Call get_team_patterns to see patterns for this area"
• "Search for uncovered callers" (when caller coverage is low)
• "Review related memories with get_memory"
• Each is actionable in one sentence

Documentation

• CHANGELOG: Phase 09 entry with human voice
• README: Updated preflight JSON example and tool table description
• MOTIVATION: Concretized evidence gating section with real caller coverage example
• docs/capabilities.md: Full rewrite of preflight section, added symbol ranking and dedup to retrieval pipeline, added scope headers to enrichment steps

Testing

• 219 tests passing
• 5 pre-existing timeout failures (unrelated to this work)
• TypeScript: zero any types in new code
• Verified: decision card has no old fields, ready is always present, whatWouldHelp shows when ready=false, impact.coverage shows caller counts, snippets include scope headers

Guardrails

✅ TypeScript compilation passes
✅ Tests pass (219 passing)
✅ Preflight output is clean (no evidenceLock, riskLevel, confidence)
✅ ready is always present as boolean
✅ whatWouldHelp appears when ready=false
✅ Snippets include scope headers when metadata available
✅ Docs match actual output

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[greptile-apps]

Greptile Summary

This PR refactors the search and preflight systems to provide cleaner, more actionable output. The decision card now exposes only stable, user-facing fields (ready, nextAction, patterns, bestExample, impact, whatWouldHelp) and removes internal fields like evidenceLock, riskLevel, and confidence.

Key changes:

• Definition-first ranking: EXACT_NAME queries boost results where symbolName matches the query (+15%), ensuring defining files rank above using files
• Symbol-level deduplication: Within each symbolPath group, keeps only the highest-scoring chunk to prevent duplicate methods from the same class
• Smart snippets: Adds scope header comments (// ClassName.methodName) to code snippets when symbol metadata is available
• Caller coverage gating: Tracks which known callers appear in results and triggers epistemic stress when <40% coverage with >3 total callers
• whatWouldHelp recommendations: When ready=false, provides concrete next steps (search specific files, call get_team_patterns, review memories)

Potential issue:

• The caller coverage logic at src/tools/search-codebase.ts:492-494 may not match the intended behavior described in the PR. It counts callers that are both importers of result files AND are themselves in the result set, rather than checking if known callers were included in the search.

Confidence Score: 4/5

• This PR is safe to merge with one logic verification needed
• The changes are well-structured and align with project constraints (framework-agnostic, no over-engineering). Documentation is thorough and matches implementation. The main concern is the caller coverage calculation logic which may not behave as described in the PR, warranting verification before merge. All other changes follow established patterns and improve code clarity by removing internal fields from public API.
• Verify src/tools/search-codebase.ts caller coverage logic matches intended behavior

Important Files Changed

Filename	Overview
src/core/search.ts	Adds definition-first boost (+15%) for EXACT_NAME intent and symbol-level deduplication to prevent duplicate methods from same class
src/preflight/evidence-lock.ts	Adds caller coverage gating (triggers epistemic stress when <40% coverage with >3 callers) and generates whatWouldHelp recommendations
src/tools/search-codebase.ts	Refactors preflight response to clean decision card shape, computes impact coverage, adds scope headers to snippets. Potential issue with caller coverage logic
docs/capabilities.md	Comprehensive update: adds retrieval pipeline steps for symbol ranking/dedup, rewrites preflight section with TypeScript interface and detailed field explanations

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Search Query] --> B[Dual Retrieval]
    B --> C[RRF Fusion]
    C --> D{Intent = EXACT_NAME?}
    D -->|Yes| E[Definition-First Boost +15%]
    D -->|No| F[Structure-Aware Boosting]
    E --> F
    F --> G[File-Level Deduplication]
    G --> H[Symbol-Level Deduplication]
    H --> I[Stage-2 Reranking]
    I --> J[Build Decision Card]
    J --> K{Ready to Edit?}
    K -->|No| L[Generate whatWouldHelp]
    K -->|Yes| M[Return Results]
    L --> N[Check Caller Coverage]
    N -->|<40% with >3 callers| O[Trigger Epistemic Stress]
    N -->|Sufficient| M
    O --> M
    M --> P[Enrich with Scope Headers]
    P --> Q[Final Response]

Loading

_{Last reviewed commit: 9efe5c5}

[greptile-apps]

_{7 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}