Branch Aware Context Retrieval Pipelines Failure Patterns And: practical systems guide

# Branch Aware Context Retrieval Pipelines: Failure Patterns And Practical Systems Guide

Most RAG-based coding assistants retrieve context from whatever's in your working directory. When you're on a feature branch three weeks old, rebasing across a dozen upstream changes, this naive approach returns stale embeddings that reference code deleted two sprints ago. Your assistant confidently suggests using a `UserService.authenticate()` method that was refactored into `AuthProvider.verifyCredentials()` last Tuesday.

Branch-aware context retrieval means your embeddings, references, and code graph stay synchronized with the actual state of each Git ref. The challenge isn't just indexing—it's handling the failure modes that emerge when branches diverge, merge conflicts sit unresolved, and your index becomes eventually consistent with a codebase that never stops moving.

Why naive context retrieval breaks on branches

A standard vector store approach indexes your `main` branch, chunks code into overlapping windows, embeds them, and retrieves the top-k nearest neighbors when you ask a question. This works until:

1. **Branch divergence**: Your feature branch deleted `services/billing.ts` but the embedding store still returns it because the index hasn't caught up.

2. **Merge conflicts**: You're resolving conflicts and the file has both `<<<<<<<` markers and actual code. The retriever pulls the conflict-marked version and your assistant tries to write code that references non-existent merged states.

3. **Stale imports**: A dependency was upgraded on `main`, changing the API surface. Your branch still uses the old API, but retrieval pulls examples from the new version because the index prioritized recency on `main`.

The symptom is always the same: the assistant generates syntactically valid code that imports things that don't exist or calls methods with the wrong signatures.

Failure pattern: index lag on branch checkout

When you `git checkout feature/new-auth`, your local filesystem reflects the branch state instantly. Your embedding index doesn't. If you're running re-indexing on a background worker (common in Cursor, Copilot Workspace, and similar tools), there's a window—often 30-90 seconds—where you're querying against the wrong branch's context.

**What breaks**: You ask "how do I call the auth service?" and get back references to code that hasn't been merged to your branch yet. You copy the suggestion, run the build, and hit import errors.

**Mitigation approaches**:

• **Synchronous indexing on checkout**: Block the editor/assistant until embeddings refresh. Adds 10-30s delay every branch switch, users hate it.
• **Branch-keyed embedding stores**: Maintain separate vector indices per branch. Storage multiplies by branch count; infeasible past 5-10 active branches.
• **Lazy invalidation**: Mark embeddings with a Git ref and timestamp. On checkout, invalidate entries whose ref doesn't match the current `HEAD`. Retrieve from valid entries only; trigger background reindexing for the rest. Works but you get degraded context (fewer results) until reindexing completes.

Goatfied's agent loop handles this by validating every code change against the actual filesystem and compiler *before* committing a response. When the retrieval pipeline returns stale context from the wrong branch, the validation step catches the import errors and forces a retry with corrected references. It's slower than hoping the retrieval is perfect, but it prevents shipping broken suggestions.

Failure pattern: conflict markers in retrieved context

During a merge or rebase, Git inserts conflict markers into files. These markers are text, so they get embedded. Retrieval treats them as normal code:

<<<<<<< HEAD

export function calculateTax(amount: number): number {

=======

export function computeTax(amount: number, region: string): number {

>>>>>>> feature/regional-tax

The assistant sees both `calculateTax` and `computeTax` in the retrieved chunks, doesn't know which is the "real" version, and might generate code calling the wrong one—or worse, try to reference the conflict markers themselves.

**What breaks**: Generated code calls `calculateTax` with one argument when the resolved version will be `computeTax` with two. You resolve the conflict, the code still doesn't compile.

**Mitigation approaches**:

• **Pre-filter conflict-marked files**: Exclude any file containing `<<<<<<<` from the embedding index. Simple, but you lose *all* context from those files even if 95% of the file is clean.
• **Chunk-level filtering**: Only exclude chunks that contain conflict markers. Better, but chunking boundaries might split markers across chunks.
• **Prompt the user**: Surface a warning "3 files have unresolved conflicts; context may be incomplete." Honest but unhelpful if they're mid-conflict resolution.

The robust approach is chunk-level filtering plus a fallback: if a query would return zero results after filtering, return the conflict-marked chunks anyway but prepend a warning in the response. At least the user knows why the suggestion looks weird.

Failure pattern: cross-branch reference leakage

Your feature branch depends on a utility function you wrote locally. You ask for help refactoring a different file. The assistant retrieves context from `main` (where your utility doesn't exist) and suggests rewriting your code to not use it—or worse, suggests importing it from a different module where a similarly named function lives.

**What breaks**: The assistant doesn't understand which symbols are available *on your branch* vs. upstream. It optimizes for the most common case (main branch) and gives you code that compiles on main but not on your feature work.

**Mitigation**: Build a symbol index keyed by Git ref. Before retrieval, resolve the current branch's symbol table (all exported functions, classes, types). Filter retrieved chunks to only those defining or importing symbols in the current table. Expensive—requires parsing and AST analysis per branch—but eliminates cross-branch hallucinations.

Alternatively, accept the failure mode and catch it downstream. Goatfied's compile gate runs TypeScript/Go/Rust checks on every generated diff before showing it to you. If the assistant leaked a reference from the wrong branch, the compiler rejects it and the agent retries with corrected context.

Building a branch-aware pipeline that degrades gracefully

Instead of aiming for perfect branch-aware retrieval (which requires per-branch indexing and real-time invalidation), build a pipeline that:

1. **Retrieves optimistically**: Pull from a shared index, assume most context is branch-agnostic (utility functions, types, domain models).

2. **Validates aggressively**: Run language-specific checks (compile, lint, test) on generated code before presenting it.

3. **Retries with refinement**: When validation fails, extract the error (e.g., "cannot find name 'UserService'"), feed it back into the retrieval query ("find the current authentication service implementation"), and regenerate.

This three-step loop—retrieve, validate, retry—handles branch divergence, conflict markers, and cross-branch leakage without requiring perfect up-front indexing. It's slower than a single-shot retrieval, but it produces code that actually works on the branch you're on.

The key insight: branch-aware context retrieval is a mitigation strategy, not a solution. The real solution is validation gates that catch retrieval failures before they reach the user.

Related reading

• [Goatfied vs Cursor vs GitHub Copilot: a benchmark across 50 real PR tasks](/blog/goatfied-vs-cursor-vs-github-copilot-benchmark-50-pr-tasks)
• [The Goatfied agent loop: how we ship code that actually compiles first try](/blog/goatfied-agent-loop-compiles-first-try)