From ed1db576a8610c6f9f56e13291d92502bbbb2097 Mon Sep 17 00:00:00 2001 From: Jordi Gil Date: Sun, 16 Aug 2026 23:40:18 -0400 Subject: [PATCH] chore: document Serena's *-mirror projects for cross-repo query_project Points agents at the pinned, read-only, auto-synced mirror worktrees (kubernaut-mirror, kubernaut-release-v1.5-mirror, etc.) instead of the ambiguous interactive dev clone names when a query_project call needs a guaranteed branch's state, after a live incident where a query against "kubernaut" silently returned stale pre-merge content because that clone was checked out on release/v1.5 at the time. See jordigilh/engram docs/findings/2026-08.md, 2026-08-16 entry, for the full incident and fix. --- .cursor/rules/hindsight-memory.mdc | 70 +++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 6 deletions(-) diff --git a/.cursor/rules/hindsight-memory.mdc b/.cursor/rules/hindsight-memory.mdc index 97dc92fc..c37fea09 100644 --- a/.cursor/rules/hindsight-memory.mdc +++ b/.cursor/rules/hindsight-memory.mdc @@ -80,6 +80,38 @@ Use `cocoindex_search` when: Prefer `cocoindex_search` over Grep/SemanticSearch when searching by meaning. Use Grep only when you need exact regex matching. +## Multi-branch code search (2026-08-10) + +The code index additionally covers `release/v1.5` and `release/v1.6` mirrors +of kubernaut, kubernaut-operator, and kubernaut-console (docs/issues stay +main-only, unaffected). `cocoindex_search`/`cocoindex_pattern_search` +auto-detect which release line your current workspace belongs to -- either a +checked-out `release/vX.Y` branch, or (the common case) a feature/fix branch +inside a dedicated per-release-line clone directory like `kubernaut-operator-v1.5` +-- and scope results to match, so a v1.5 workspace's searches return v1.5's +code, not main's. Pass `branch: "v1.5"` explicitly to override detection, or +`branch: "main"` to force main regardless of your checkout. + +Branches outside `{main, v1.5, v1.6}` (regular feature/fix work) aren't +indexed here at all -- use gopls for those; it operates on your live checkout +directly so it's always accurate regardless of index staleness. (This repo's +tier-1 tool is still raw `gopls`, not Serena -- see the still-open +Serena-migration question for this repo, tracked separately from this +multi-branch change.) + +**If you do reach for Serena's `query_project` anyway** (e.g. from a +`kubernaut-docs` or cross-repo session) to pull `kubernaut`/`kubernaut-console` +state into an `kubernaut-operator` task, use the `-mirror`-suffixed project +names (`kubernaut-mirror`, `kubernaut-release-v1.5-mirror`, etc.), not the +bare repo names. The bare names are interactive dev clones that get freely +branch-switched, so they don't reliably reflect any particular branch's +state -- this caused a real incident (2026-08-16) where a query against +`kubernaut` silently returned stale pre-merge content because that clone +happened to be sitting on `release/v1.5` at the time. The `-mirror` projects +are dedicated, read-only, auto-synced-every-10-minutes worktrees pinned +one-per-branch. See docs/findings/2026-08.md, 2026-08-16 entry, for the full +incident and fix. + ## When to recall again (mid-session) Call `recall` again if: @@ -155,14 +187,40 @@ Use the right tool for the right question: `user-cocoindex-code` MCP server. Call it with `{"query": "...", "limit": 10}`. Use for "where do we handle CRD reconciliation?", "how does the operator controller work?", "what functions touch this data?" +- **`cocoindex_pattern_search`** — structural (by-example) code search, on the + same `user-cocoindex-code` MCP server. Call it with + `{"pattern": "func \\NAME(\\(A*\\)) error", "language": "go", "repo": "kubernaut-operator"}`. + Use for "find every function shaped like X" (a signature, not a + name/concept) -- purely syntactic, no type resolution or find-references; + not a substitute for gopls. - **hindsight** — past mistakes, conventions, behavioral patterns about code. Use for "how should I structure this test?", "what was corrected before?" Prefer gopls for precise lookups, `cocoindex_search` for semantic exploration, -and hindsight for behavioral context. Do not redundantly call all three for the -same question. - -## Do NOT retain - -Never call `retain` during sessions. Memory extraction runs nightly. +`cocoindex_pattern_search` for structural shape queries, and hindsight for +behavioral context. Do not redundantly call all of these for the same +question. + +## Retain/reflect: on-demand, suggest-then-confirm + +No background job does this anymore — `retain`, `sync_retain`, and `reflect` +are on-demand only, triggered explicitly in-chat (see docs/findings/2026-08.md, +2026-08-13 "retain/reflect on-demand" decision). This keeps LLM cost visible +and bounded until there's a stable, well-understood cost baseline for +background extraction. + +**Suggest, don't call silently.** When you notice one of the following during +a session, propose it to the user and wait for confirmation before calling +the tool: + +- **Retain** — an explicit correction, a decision, a stated preference, or a + hard-won discovery (e.g. a root cause that took real effort to find) worth + recalling in a future session. +- **Reflect** — several related retains have accumulated on the same topic, + you're about to lean on a mental model that looks stale, or the user + directly points out staleness. + +Only call `retain`/`sync_retain`/`reflect` after the user confirms, or when +they ask for it directly ("retain this", "update the mental model", etc.). +Never call them proactively or as a matter of routine.