docs(evolve): clarify --session <id> meaning and read-only cache rule

[baleen37]

Summary

• Clarify --session <id> accepts a transcript session id (the .jsonl filename), NOT the ARGUMENTS: uuid Claude Code injects for slash-command args.
• Expand the read-only cache rule: cache is overwritten on plugin updates; if the user points at the plugin's source repo, redirect the edit there.

Why

In a /me:evolve session, the main agent passed the slash-command ARGUMENTS: uuid as --session and got exit-14. The skill's usage block did not disambiguate the two ids. Separately, the existing "never modify cache" rule did not explain why (overwritten on update) or what to do when the user offers the source repo.

Test plan

• Re-run /me:evolve with no arg → auto-detects current transcript (no --session passed).
• Re-run /me:evolve --session <real-jsonl-id> → indexer finds the transcript.

Summary by CodeRabbit

• Documentation
  • Improved documentation for the evolve skill's command-line interface with clarified argument semantics. Enhancements include detailed guidance on proper session reference conventions, revised instructions for parameter passing in various operational phases, and expanded descriptions of key command flags. Documentation now better explains correct session argument usage and reinforces important best practices.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 572bfca4-ae66-4fa0-8cdd-3b8a0959d37f

📥 Commits

Reviewing files that changed from the base of the PR and between 53fb4cb and 6651356.

📒 Files selected for processing (1)

• plugins/me/skills/evolve/SKILL.md

---

📝 Walkthrough

Walkthrough

SKILL.md documentation for /me:evolve updated to clarify that --session <id> refers to transcript .jsonl filenames under the project directory and must only be forwarded to build-index.ts when explicitly provided by the user.

Changes

CLI Documentation Clarification

Layer / File(s)	Summary
CLI flag semantics clarification plugins/me/skills/evolve/SKILL.md	Documentation expanded to clarify that --session <id> refers to transcript .jsonl filenames in ~/.claude/projects/<project>/, not the ARGUMENTS uuid, and specifies that --session should only be forwarded to build-index.ts when explicitly provided.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• baleen37/bstack#665: Rewrites /me:evolve Phase 0 instructions describing how build-index.ts is invoked with --session; overlaps directly with this PR's clarification of --session semantics.
• baleen37/bstack#666: Also updates plugins/me/skills/evolve/SKILL.md to clarify flag-forwarding semantics to build-index.ts (covering --dry-run in that PR).

Poem

🐰 A clarity hop through flags so bright,
--session now shines in the project's light,
.jsonl filenames dance into place,
Forward with care—only when the user's case!

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/evolve-doc-clarifications

---

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.}