RT-260511-04 — P11f search-index brief: task + rationale + /plan-first directive · session

Summary

Tail-end follow-up to RT-260511-03 (which closed at e9318c1). Roman asked whether the deferred search idea was tracked anywhere — it wasn't. Coordinated with peer 0c61x7jq via the claude-peers MCP before touching workstreams/repo-as-canonical-store-vault.md (they were mid-merging three agent branches into main), then landed two small additions: a P11f search-index task bullet + inline UX brief, then an expansion with rationale (search-vs-memory-vs-navigation distinction, keyword-vs-embedding math, 70/30 matcher-vs-rows insight) + 8 open questions for the /plan interview + an explicit "MUST run /plan before /build" directive. Also diagnosed an old failed-deploy GitHub notification: the f936f72 run that was the very commit before I fixed the --commit-message YAML-splat bug in ca31b12 (every push since has deployed cleanly; the email was historical, no further action needed).

What I Did

Pinged peer 0c61x7jq via mcp__claude-peers__send_message to coordinate before editing the shared workstream file. They were mid-merging harden/notion-zero + vault/p10-p11b + plan2/notion-sync-worker into main and pushing P12 + forge-vault-setup additions. Acked all three of my points (P11f insertion, banner-overlap diff-check, render_md.py exclusion of .claude/memory/); asked me to wait ~5 min for their push.
42cc34b — workstream(vault): add P11f search-index task + brief. New Tasks bullet between P11e and P12 (no overlap with peer's P12 extension). Inline ## Search brief (P11f, surfaced 2026-05-11) section with: output paths (scripts/build_search_index.py + docs/rendered/search/index.html), JSON manifest fields, search UI (filter chips on kind/status/author/tag, URL hash sync, / keyboard shortcut), matcher options (homegrown ~50 lines or vendored fuzzysort), composition with P11b + P11e, visual register pointer, out-of-scope items. Updated the existing P11e "Out of scope" bullet for full-text search to point at P11f below.
312a472 — workstream(vault): P11f — expand brief with rationale + /plan-first directive (committed locally as 538044c, rebased to 312a472 by the post-commit hook). Roman: "remind to actually plan it properly and not just to do it." Three new subsections in the Search brief: § Before /build: run /plan (explicit reframing as interview material, not implementation spec); § Why this shape (rationale) (the search-vs-memory-vs-navigation table, the keyword-vs-embedding math at offplan's ~200-artefact scale, the 70/30 matcher-vs-rows insight); § Open questions for the /plan interview (8 real design calls: date-decay scoring, supersedes-in-results, grouping default, snippet rendering, query syntax, recent-search history, empty-state design, mobile keyboard affordance). Also amended the P11f task bullet with MUST run /plan before /build.
Investigated Roman's failed-deploy email for f936f72. Confirmed it was the run that triggered my ca31b12 fix (--commit-message YAML-splat bug); 2-minute gap between failure and fix; every subsequent push has deployed cleanly. No further action.
Notified peer 0c61x7jq when P11f landed (42cc34b → 312a472 after rebase). They acked: "saw it in the diff, no conflict with my P12 extension. You're good to close out."

Decisions Made

P11f gets a /plan interview before /build. The brief now contains 8 explicit open questions framed for the /plan author, not pre-decided spec. Rationale: search seems simple but the result-row UX carries ~70% of the user-perceived quality, and that UX benefits from interview-time decisions (snippet rendering, grouping default, mobile affordance) rather than implementer guesses. Alternative considered: leave it as a "ready-to-build" spec. Rejected at Roman's explicit instruction.
Coordinated with peer before editing the shared file. Used list_peers(scope="repo") (returned empty — peer was on a feature branch not main), then list_peers(scope="machine") to find them at 0c61x7jq. Sent a single coordinated message covering three points (P11f insertion, banner overlap, memory-exclusion heads-up). Alternative: land my work first and let them rebase. Rejected because they were actively editing the same file and a 30s conflict-prevention message was cheaper than a 5-min rebase resolve later.

For Future Me

The P11f brief now reads like interview material, not a spec. When you (or whoever) get to /build vault Phase 11, walk through the 8 open questions in § "Open questions for the /plan interview" before writing code — Roman wants a real /plan session for this, not a "looks simple, just ship it" path. Same discipline arguably applies to P11e (about-page) too; the P11e brief is closer to a spec, but the same reframing would help. Consider promoting that pattern explicitly: every "brief surfaced post-ratification" gets a /plan-first directive by default.

The banner overlap from earlier (my 6d61aee first-line repo banner vs the parallel session's 9cfbc87 closing-banner work) is still un-diff-checked. Peer said "will diff-check on followup" but no confirmation came back. Worth a 30s pass next time someone edits the /resume or /handoff commands — likely they coexist cleanly, but verify before assuming.

Learnings

claude-peers MCP is genuinely useful for shared-file editing. The coordination message + their reply prevented a merge conflict on workstreams/repo-as-canonical-store-vault.md that would have cost more than the 30s of message-roundtrip. Pattern: before editing a file you know a peer is actively editing, list_peers(scope="machine") → send_message is cheaper than git rebase --abort later.
"Brief surfaced post-ratification" is an emerging shape worth naming. When a new task gets added to a workstream AFTER the parent plan is ratified (P11e + P11f both surfaced in conversation 2026-05-11 after the canonical-store plan ratified earlier the same day), the brief sits in the workstream file as a UX/design spec — not in the plan body. The plan stays stable; the workstream evolves. Add MUST run /plan before /build to any such brief so the implementer doesn't skip the interview.

Open Questions

[OPEN] Banner overlap (mine 6d61aee vs peer's 9cfbc87) — peer said "will diff-check"; status unconfirmed. Verify next time someone edits the /resume or /handoff commands.
[OPEN] The GUPPI /handoff slash command loaded twice in this conversation when Roman typed /handoff, shadowing offplan's project-scoped version. Still unresolved. Worth investigating Claude Code's slash-command resolution order — project-scoped should win but apparently isn't. Same issue will bite Sergei.

Resume Prompt

Tiny follow-up session — only two commits (42cc34b + 312a472) since RT-260511-03 sealed. P11f search-index task is now tracked in vault workstream with rationale + /plan-first directive + 8 open questions for the interview. No further work pending from this session. Next /resume picks up wherever Roman directs — likely the vault workstream's actual /build (P11a regen_indexes → P11b already done → P11c lifecycle → P11d gallery → P11e about-page → P11f search → P12 link audit → P13 CLAUDE.md split), or a new plan. Watch out for: (a) banner-overlap still un-diff-checked (mine 6d61aee vs peer's 9cfbc87), 30s polish task; (b) GUPPI /handoff still shadowing offplan's on Roman's terminal — fix command resolution to make /handoff here load .claude/commands/handoff.md not ~/.claude/commands/handoff.md. Confidence: H — clean tail, no in-flight work.