[danielbushman]

Summary

• Fix two agent-breaking doc classes: wrong repo names in examples (P1) and migrate/scan guidance against a shared read-only index (P2)
• Correct factual error introduced by prior commit: vector-search does not "return empty results" when embeddings are absent — it exits code 2 with an embedding provider error
• Update stale illustrative chunk counts in multi-repo-guide.md to match live index

What Changed

Prior commit (afae91a) — P1 and P2 fixes

• All --repo examples updated to real names (manifoldlogic/crewchief, specs) verified against live maproom status --json
• db migrate / scan demoted from first-time setup to a clearly-labeled admin appendix
• FTS-first callout added at the top of Choosing Search Type (embeddings are 0% in this environment)
• plugin.json bumped 0.10.0 → 0.10.1 (directory-source marketplace re-caches on version change)
• No --all-repos references

This commit (37a469d) — adversarial review MUST-FIX

SKILL.md lines 30, 46, 280 — Three locations incorrectly described maproom vector-search as "returning empty results" or "completing but returning empty" when embeddings are absent. Live measurement (3 runs, exit code verified):

$ export MAPROOM_DATABASE_URL=postgres://maproom:maproom@host.docker.internal:5433/maproom
$ maproom vector-search --repo manifoldlogic/crewchief --query "authentication login flow" --format agent; echo "EXIT: $?"
ERROR | type=embedding_provider | message=Failed to create embedding service | ...
Error: Failed to create embedding service  Caused by: Configuration error: Missing required configuration: No Google credentials found.
EXIT: 2

Vector-search exits with code 2 — it does not produce an empty result set. Agents relying on empty-result fallback logic would instead receive a hard error. All three locations updated to state the actual behavior.

multi-repo-guide.md line 361 — Illustrative chunk counts updated from stale values (24,333 / 1,200) to live values (29,764 / 28,799) verified against maproom status.

Spec Reference

_SPECS/crewchief/research/maproom-eco-plugin-critical-fixes-spec.md — Wave 1, chunk plugin-critical-fixes

Validation Evidence

# R1: All --repo examples use live names
$ export MAPROOM_DATABASE_URL=postgres://maproom:maproom@host.docker.internal:5433/maproom
$ maproom search --repo manifoldlogic/crewchief --query "scan" --k 1 --format agent
# returns results (no Repository-not-found)
$ maproom search --repo specs --query "architecture" --k 1 --format agent
# returns results

# R2: No db migrate / scan in agent-facing sections
$ grep -rn 'maproom db migrate' plugins/maproom/skills/maproom-search/SKILL.md
# Only appears in Appendix: Fresh-Environment Setup (admin-labeled)

# R3: FTS-first callout present
$ grep -n 'FTS-first' plugins/maproom/skills/maproom-search/SKILL.md
# Line 30: FTS-first in this environment callout confirmed

# R4: Version bumped
$ jq -r '.version' plugins/maproom/.claude-plugin/plugin.json
# 0.10.1

# R5: No --all-repos references
$ grep -rn '\-\-all-repos' plugins/maproom/
# (no output)

# MUST-FIX: vector-search behavior corrected
$ grep -n 'exit.*code 2\|code 2.*embedding' plugins/maproom/skills/maproom-search/SKILL.md
# Lines 30, 46, 280 — all describe exit code 2 behavior
$ grep -n 'search completes but returns empty\|will return empty results\|will return no results' plugins/maproom/skills/maproom-search/SKILL.md
# (no output — all three stale phrases removed)

Review

Adversarial review findings (from JSON input):

Severity	Finding	Resolution
MUST-FIX	SKILL.md line 30: "will return empty results" — incorrect, exits code 2	Fixed: "will exit with code 2 and an embedding provider error"
MUST-FIX	SKILL.md line 46: "will return no results" — incorrect	Fixed: "will exit with code 2 (embedding_provider error: no Google credentials found)"
MUST-FIX	SKILL.md line 280: "search completes but returns empty" — incorrect	Fixed: heading and body updated to describe exit code 2 error behavior
SHOULD-FIX	multi-repo-guide.md line 361: stale chunk counts (24,333 / 1,200 vs live 29,764 / 28,799)	Fixed: updated to live values
NOTE	multi-repo-guide.md line 131: MAPMULTI ticket example returns 0 hits in live index	Recorded — this is a documentation-only illustrative example; removing it would reduce utility for agents learning the FTS ticket-ID pattern. Deferred.
NOTE	multi-repo-guide.md line 53: ShadowMode --kind class returns 0 hits (no class chunks for ShadowMode)	Recorded — example is in "Class or struct names" section but ShadowMode has no class chunk in the index. Deferred: the broader "Class or struct names" guidance is still valid; replacing this specific example requires a live class name lookup.

Non-Goals

Per spec: glossary/troubleshooting/embedding-doc banners (Wave 2 plugin-backend-docs-refresh); researcher-agent changes (Wave 2); cross-repo guidance (Wave 3).

---

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Updated Maproom search guidance with clearer repo naming, revised examples, and more specific troubleshooting steps.
  • Added instructions for working with an already-populated shared index and clarified search behavior when embeddings are unavailable.
  • Expanded setup guidance for fresh environments and refreshed cross-repo search examples.

• Chores

  • Bumped the plugin version to 0.10.1.

[coderabbitai]

Warning

Review limit reached

@danielbushman, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 53 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1ae23b30-2e90-461a-98cf-201d1ab468cf

📥 Commits

Reviewing files that changed from the base of the PR and between 37a469d and 142e797.

📒 Files selected for processing (2)

• plugins/maproom/skills/maproom-search/SKILL.md
• plugins/maproom/skills/maproom-search/templates/maproom-repos.yaml

Walkthrough

Maproom search guidance now targets a populated shared index, uses canonical repository identifiers, updates multi-repository examples and setup commands, expands troubleshooting instructions, and bumps the plugin version to 0.10.1.

Changes

Maproom search guidance

Layer / File(s)	Summary
Shared-index and search operations plugins/maproom/skills/maproom-search/SKILL.md	Adds shared-index verification, FTS-first guidance, vector-search requirements, expanded troubleshooting, and admin-only fresh-environment setup instructions.
Canonical repository naming plugins/maproom/skills/maproom-search/templates/maproom-repos.yaml, plugins/maproom/skills/maproom-search/references/multi-repo-guide.md	Documents repository key derivation and changes example keys to manifoldlogic/crewchief and specs.
Search workflow examples and release metadata plugins/maproom/skills/maproom-search/references/multi-repo-guide.md, plugins/maproom/.claude-plugin/plugin.json	Propagates canonical keys through search, troubleshooting, setup, verification, and test examples, while updating the plugin version to 0.10.1.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• manifoldlogic/claude-code-plugins#7: Also rewrites Maproom SKILL.md workflow and configuration guidance.
• manifoldlogic/claude-code-plugins#65: Also updates Maproom search documentation and repository key behavior.

Poem

I’m a rabbit with an index to tend,
FTS hops first from beginning to end.
specs and code now know their names,
Shared searches follow safer lanes.
A tiny version bump crowns the feat—
Maproom’s burrow is neat and complete! 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main changes: vector-search behavior docs, repo-name/shared-index fixes, and the plugin version bump.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch maproom-plugin-critical-fixes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/maproom/skills/maproom-search/SKILL.md`:
- Around line 15-46: The search guidance is inconsistent: the “Choosing Search
Type” table still sends conceptual queries to maproom vector-search even though
this section says embeddings are 0% and maproom search is the only usable path
right now. Update the table in SKILL.md so it matches the FTS-first guidance by
routing all current search use cases to maproom search, and keep maproom
vector-search clearly marked as unavailable until embeddings exist.

In `@plugins/maproom/skills/maproom-search/templates/maproom-repos.yaml`:
- Around line 29-34: The repo naming note in maproom-repos.yaml is too absolute
because it states repo keys are always owner/repo, but the same mapping includes
specs as a non-owner/repo key. Update the comment near the repo-key guidance to
either explicitly call out specs as an exception or rephrase it to say “most
repo keys” are owner/repo, using the existing repo-key note text as the target
for the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bcae393a-eb7b-4f63-8cb3-5eb91c5c5025

📥 Commits

Reviewing files that changed from the base of the PR and between c79c200 and 37a469d.

📒 Files selected for processing (4)

• plugins/maproom/.claude-plugin/plugin.json
• plugins/maproom/skills/maproom-search/SKILL.md
• plugins/maproom/skills/maproom-search/references/multi-repo-guide.md
• plugins/maproom/skills/maproom-search/templates/maproom-repos.yaml