feat(evolve): add --skill flag for cross-project skill review

[baleen37]

Summary

/me:evolve could only review skills used in the current project + worktree siblings. Skills exercised mostly in other repos (e.g. research, used while exploring real codebases, not in this meta repo) never surfaced. This adds a --skill <name> mode that scans all projects, and fixes a stale-detection bug it exposed.

Changes

• --skill <name> flag — scans the entire ~/.claude/projects/ tree for sessions that actually invoked the skill (by the Base directory for this skill: injection, not a bare path mention), capped to the most recent N, filtered to that skill. Cross-project, unlike --recent.
• ARGUMENTS stale bugfix — when a slash command is invoked with arguments, the injected body gains a trailing ARGUMENTS: … block. That tail was hashed with the body, so an identical skill body was misjudged stale (dropped, events emptied) whenever called with args. stripBaseDirLine now strips it. This affected --recent too. (Verified: research went from dropped (stale), events=0 to stale:false, events=91.)
• research SKILL.md — multi-session review surfaced one research-specific signal: a live backoffice URL bug where research ran but the user redirected to browser inspection. Added a Depth Selection row + Red Flag routing live UI/page bugs to me:browse first.
• evolve Phase 1 guidance — added cross-skill target selection: a correction firing under skill X may expose a gap owned by a related skill Y; target the skill whose contract would have prevented it.

Tests

• bats tests/me/evolve-build-index.bats — 33 passing (27 existing + 6 new: ARGUMENTS regression, --skill cross-project/filter/exit codes).

Summary by CodeRabbit

Release Notes

• New Features

  • Added --skill <name> option to /me:evolve command for cross-project skill analysis with --recent filtering support.

• Bug Fixes

  • Improved stale detection logic to prevent false positives when injected content or arguments differ.

• Documentation

  • Enhanced /me:evolve command documentation with exit-code semantics and cross-skill targeting guidance.
  • Updated research skill documentation with best practices for live UI debugging.

• Tests

  • Added comprehensive test coverage for new --skill mode and edge cases.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4bcbe9fe-313d-483e-b1a7-a75385d43c9b

📥 Commits

Reviewing files that changed from the base of the PR and between 71ae569 and 098754c.

📒 Files selected for processing (4)

• plugins/me/skills/evolve/SKILL.md
• plugins/me/skills/evolve/scripts/build-index.ts
• plugins/me/skills/research/SKILL.md
• tests/me/evolve-build-index.bats

---

📝 Walkthrough

Walkthrough

The PR extends the /me:evolve build-index command to analyze a skill across all projects via --skill <name>, normalizes stale-detection hashing to ignore dynamically-appended transcript markers, and adds guidance to the research skill about inspecting live UIs before reading code.

Changes

Cross-project skill analysis and --recent normalization

Layer / File(s)	Summary
Stale-detection hash normalization for --recent plugins/me/skills/evolve/scripts/build-index.ts, plugins/me/skills/evolve/SKILL.md	The stripBaseDirLine function now removes both "Base directory for this skill:" lines and trailing ARGUMENTS: blocks from injected transcript bodies so that stale comparison ignores these dynamic additions. Documentation clarifies that normalized body-equivalence is used to determine staleness, decoupling it from argument presence or content.
Documentation for --skill mode and refined semantics plugins/me/skills/evolve/SKILL.md	The SKILL.md documents the new --skill <name> flag for analyzing a skill across ~/.claude/projects, clarifies Phase 0 exit-code 2 to include invalid-argument cases (empty --skill, disallowed --dry-run), documents --recent/--session incompatibility, extends --skill behavior description (session identification, filtering, staleness), and adds "related SKILL.md (cross-skill)" targeting with updated "Nearest resolution" rules.
Helper functions for skill session discovery plugins/me/skills/evolve/scripts/build-index.ts	New functions transcriptInvokesSkill and skillSessionPaths enable cross-project skill analysis: the former detects whether a transcript invokes a specific skill by pattern-matching "Base directory for this skill: …/skills/", and the latter scans ~/.claude/projects to collect and return the N most recently modified matching session paths.
Argument parsing and validation for --skill plugins/me/skills/evolve/scripts/build-index.ts	The parseArgs function adds a --skill <name> parameter and validates that it is not combined with --session, not empty, and not used when no matching sessions exist (exit code 14). The main entry point branches on opts.skill: when set, it collects sessions via skillSessionPaths, builds an index with buildRecentIndex, and filters the output to include only the requested skill.
Test coverage for --skill and --recent features tests/me/evolve-build-index.bats	Six new tests validate the features: one verifies that trailing ARGUMENTS: blocks in --recent mode are ignored for stale comparison, two test multi-project session collection and skill filtering when using --skill, and three verify exit codes for edge cases (no matching sessions return 14, empty --skill returns 2, and combining --skill with --session returns 2).

Research skill guidance refinement

Layer / File(s)	Summary
Live UI inspection guidance for bug investigation plugins/me/skills/research/SKILL.md	The research skill documentation adds an explicit recommendation to inspect the running UI/page (via me:browse) before reading source code when investigating live UI/page bugs, and flags the anti-pattern of reading code first when troubleshooting bugs at a live URL/UI.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• baleen37/bstack#664: Both PRs touch the /me:evolve implementation in plugins/me/skills/evolve/scripts/build-index.ts and SKILL.md, where #664 introduces the initial transcript-based evolution tool and this PR extends its --skill/--recent indexing and stale-hash logic.
• baleen37/bstack#669: Both PRs update stale-hash normalization in build-index.ts for --recent/indexing workflows, with direct alignment on multi-session stale-detection handling and transcript body stripping logic.
• baleen37/bstack#670: Both PRs modify build-index.ts's stale-detection and skill filtering flow; the main PR adds ARGUMENTS: stripping while the retrieved PR handles repo_path remapping and hash normalization in the same area.

Poem

🐰 Cross-project skills now bloom with care,
Stale transcripts stripped of markers fair,
A rabbit hops through projects wide,
Finding skills with --skill as guide,
And researchers browse live first—with flair!

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch witty-summit-kepler

---

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 and usage tips.}