Search the Lossless Corpus

The Lossless Group keeps a living corpus of its own decisions, shipped work, prior sessions, and tool-failure history in a local Chroma database wired into Claude Code via the chroma MCP server. Most questions a user asks about prior work can be answered from this corpus rather than training data. Don't paraphrase from training data when the corpus could answer.

This skill is the discipline that makes the corpus load-bearing. Without it, Chroma sits there full of high-signal records that nobody queries. With it, every "what did we decide about X" question becomes grounded recall — with citations the user can verify in seconds.

When to use this skill

Trigger when the user's question takes any of these shapes:

• Decisions — "what did we decide about X", "why did we choose X over Y", "what's our stance on X"
• Shipping — "when did we ship X", "what shipped in May", "did we already do X"
• History — "what did we talk about last week", "in a prior session we…", "resume where we left off on X"
• Failures — "has this errored before", "how did we fix X last time", "when did Bash with git rebase fail"
• Location — "where did we put the X spec", "which repo's changelog mentions Y"

Trigger also when the user pastes a question that touches Lossless conventions (changelog format, context-v structure, branch-tier model) — the skill canon may have moved since your training cutoff; the corpus reflects current truth.

The four collections

The MCP server exposes them via tools named mcp__chroma__chroma_query_documents, mcp__chroma__chroma_list_collections, mcp__chroma__chroma_get_documents, etc. Each collection is keyed to a different question shape:

All four live in the same Chroma PersistentClient at /Users/mpstaton/code/lossless-monorepo/ai-labs/context-vigilance-kit/.chroma/. They are populated by the kit's ingest-all.sh script. You don't ingest from inside this skill. That work belongs to context-vigilance-kit.

The agentic-search loop

When a triggering question arrives, run this loop. Cap at 5 chroma queries total per question — if the corpus doesn't have the answer in five tries, it doesn't have it; say so explicitly.

1. Decompose

Read the user's question and break it into 1-3 sub-queries. Each sub-query should target the one collection most likely to hold its answer, not all four. Most questions hit one collection. A few hit two (e.g., "what did we decide about X and when did we ship it" → sessions + changelog).

Avoid the temptation to fan out to all four collections — it wastes the query budget and makes synthesis harder.

2. Execute

For each sub-query, call mcp__chroma__chroma_query_documents with:

• collection_name: the picked collection
• query_texts: a natural-language phrasing of the sub-query (the embedder is semantic; keyword stuffing helps less than coherent phrasing)
• n_results: start with 5. If results look noisy, widen to 10 for one more try.
• where: a metadata filter when it makes the query precise. Examples below.

Common where filters that narrow effectively:

# Only changelog entries from the ai-labs repo
{"source_repo_slug": "ai-labs"}

# Only tool errors (debugging memory)
{"is_error": True}

# A specific tool's failures
{"$and": [{"tool_name": "Bash"}, {"is_error": True}]}

# Only sessions from a particular project
{"project_path": "/Users/mpstaton/code/lossless-monorepo/ai-labs"}

# Only context-v files in a specific kind
{"kind": "spec"}

Chroma supports $and, $or, $in, $nin, $gt, $lt, $eq, $ne operators in where. See [[chroma-local]] for the full operator reference.

3. Evaluate

Read the top results returned. Ask:

• Does this cover the question? If yes, stop and proceed to synthesis.
• Is there a gap? If the results gesture toward the answer but miss a piece, run one more focused query against the gap. Don't re-run the same query — that wastes budget.
• Are the results stale? Records carry ingested_at and frontmatter dates. If a result references a renamed file or removed convention, prefer to verify against the current code rather than recommending from the record. (See "When the memory lies" below.)

4. Synthesize

Combine results into one answer. The user wants the answer, not a search report. Do not dump raw chunks; summarize. But always cite, every claim, with:

• The source_path or source_repo_slug + source_relative_path
• The timestamp or fm_date if available
• A clickable reference the user can open: file_path:line_number for code/markdown, session_id for prior sessions

Citation template:

"We decided to use PersistentClient for v0 ([ai-labs] context-v/explorations/ChromaDB-as-Context-Improvement-Across-Everything-Everyone.md, 2026-05-07). The reasoning was that local PersistentClient survives the four deployment shapes without rewriting the API surface, and ladder-up is decided by collaborator joining, splash live-query, or session-transcript volume — none of which apply yet."

The point of citing is that the user can independently verify, course-correct your reading, or surface staleness. A grounded answer without citations is half-grounded.

Practical query patterns

The shapes that come up most often:

"What did we decide about X." → query claude-code-sessions with the topic. Filter where={"turn_role": "assistant"} if the user wants the answer shape; leave unfiltered if they want the discussion shape.

"When did we ship X." → query lossless-changelog. Cross-repo by default; add where={"source_repo_slug": "<repo>"} only when the user specifies a repo.

"How did we fix the X failure last time." → query claude-code-tool-traces with where={"is_error": True} first to find the failure, then pivot to claude-code-sessions with the matching session_id to find the recovery turns. This is the 2-hop pattern.

"What's our convention for X." → query context-vigilance-corpus. The chunked-by-heading shape means a single chunk usually contains the convention statement plus its rationale.

"Has this been discussed before." → query claude-code-sessions broadly. If you find prior discussion, summarize the conclusion and ask whether the user wants to continue from there or start fresh.

Where to pivot from a result

Every result carries metadata that points back to where the full context lives. Use it:

• A context-vigilance-corpus hit → open the source_path to read the full doc.
• A lossless-changelog hit → open the entry's source_path; check git log if the entry references a commit.
• A claude-code-sessions hit → if the user wants the full conversation, they can claude --resume <session_id> to re-enter it.
• A claude-code-tool-traces hit → the session_id + timestamp locates the surrounding conversation; the trace's input and output fields are the failure itself.

When NOT to use this skill

The skill is for grounding answers in prior work. It's the wrong move when:

• The question is forward-looking. "How should we build X" is design, not recall. Recall what we decided about adjacent decisions, sure — but don't pretend the corpus has the answer to a question the team hasn't asked itself yet.
• The corpus is provably empty on the topic. If five queries return distant results (distance > 1.5 consistently across collections), the corpus genuinely doesn't have it. Say so. Don't manufacture grounding.
• *The question is about the current state of the code. Code is authoritative; the corpus is frozen at ingest time. Read the code. Use the corpus for intent and history, the code for current behavior*.
• The user explicitly says "don't check memory" / "ignore prior conversations." Honor the override. Answer fresh.

When the memory lies

Records are point-in-time snapshots. A spec from March that named file foo.md may have been renamed; a changelog entry that announced flag --bar may have shipped with --baz. Before recommending an action that depends on a corpus result existing today:

• If the result names a file path → verify the file still exists (ls / Read on it).
• If the result names a function, flag, or command → grep for it in the current code.
• If the user is about to act on the recommendation (not just asking about history), verify first.

"The corpus says X exists" is not the same as "X exists now." Recall is a starting point, not a citation.

Anti-patterns

• Fanning out to all four collections by default. Wastes the 5-query budget. Pick the collection that fits the question shape.
• Re-running the same query with slightly different wording. If query 1 returned nothing useful, query 2 with the same intent won't either. Re-decompose.
• Returning raw chunks instead of a synthesized answer. The user wanted the answer, not the receipts. Cite, don't dump.
• Treating a high-distance hit as a real answer. Distances above ~1.3 on the default all-MiniLM-L6-v2 embedder usually mean "no real match." Don't manufacture certainty from a soft hit.
• Querying the corpus for questions the user could answer faster by looking. "What's in the current branch's diff" is git diff, not Chroma.

Cross-references

• [[chroma-local]] — generic local-Chroma usage (PersistentClient lifecycle, embedding choices, the full where-operator reference). Loaded automatically when you're writing Chroma code; complementary to this skill.
• [[context-vigilance]] — what the context-vigilance-corpus collection indexes. The shape and rationale of context-v/.
• [[changelog-conventions]] — what the lossless-changelog collection indexes. The shape and rationale of <repo>/changelog/.
• [[pseudomonorepos]] — explains the source_repo_slug taxonomy you'll see in metadata across all collections.
• [[Up-and-Running-on-ChromaDB]] (lossless-content lost-in-public/up-and-running/) — the narrative of how the corpus came to be; useful when the user asks "why does this exist."

tl;dr

When the user asks something prior work might know, run the loop: decompose into 1-3 sub-queries, hit the right collection, evaluate, synthesize with citations. Cap at five queries. Pivot back to source files when the user wants depth. Don't paraphrase training-data when the corpus is right there.