docs(dev): clarify review workflow and update Claude Code skills

.claude/commands/release-prep.md

@@ -1,45 +1,80 @@
 ---
 name: Release Prep
-description: Analyze and prepare a milestone for release
-arguments: "<milestone>"
+description: Analyze and prepare a new release by pushing a tag (goreleaser creates the release)
+arguments: "<version> (e.g. v0.26.0)"
 ---
 
 # Release Preparation
 
-Prepare release for milestone **$ARGUMENTS**.
+Prepare release **$ARGUMENTS**.
 
 ## Steps
 
-1. Analyze PRs for proper release notes categorization:
+1. Fetch latest state and derive PR range to analyze:
 ```bash
-go tool gh-helper releases analyze --milestone $ARGUMENTS
+git fetch origin main
+LAST_TAG=$(gh api repos/apstndb/spanner-mycli/releases/latest --jq '.tag_name')
+PR_NUMS=$(git log ${LAST_TAG}..origin/main --oneline | grep -oE '\(#[0-9]+\)' | grep -oE '[0-9]+' | sort -n)
+FIRST_PR=$(echo "$PR_NUMS" | head -1)
+LAST_PR=$(echo "$PR_NUMS" | tail -1)
+echo "PR range: ${FIRST_PR}-${LAST_PR}"
 ```
 
-2. Review the analysis output for:
+2. Analyze PRs merged since the last release tag:
+```bash
+go tool gh-helper releases analyze --pr-range ${FIRST_PR}-${LAST_PR}
+```
+
+3. Review the analysis output for:
    - PRs missing classification labels (`bug`, `enhancement`, `breaking-change`)
-   - PRs that should have `ignore-for-release` label (dev-docs only changes)
+   - PRs that should have `ignore-for-release` label (dev-docs only, test-only changes)
    - Inconsistent labeling patterns
 
-3. Fix missing labels based on analysis:
+4. Fix missing labels based on analysis:
 ```bash
 # Add classification labels to unlabeled PRs
 go tool gh-helper labels add enhancement --items <PR_NUMBERS>
 
-# Mark dev-docs-only PRs
+# Mark dev-docs-only or test-only PRs
 go tool gh-helper labels add ignore-for-release --items <PR_NUMBERS>
 ```
 
-4. Re-analyze to verify all PRs are properly labeled:
+5. Re-analyze to verify all PRs are properly labeled:
 ```bash
-go tool gh-helper releases analyze --milestone $ARGUMENTS
+go tool gh-helper releases analyze --pr-range ${FIRST_PR}-${LAST_PR}
+# Confirm: readyForRelease: true
 ```
 
-5. Generate draft release notes:
+6. Push the release tag to origin/main HEAD (goreleaser will create the draft release automatically):
 ```bash
-gh release create $ARGUMENTS --generate-notes --draft
+git fetch origin main
+git tag $ARGUMENTS origin/main
+git push origin $ARGUMENTS
 ```
 
-6. Review the draft release notes and report any issues found.
+7. Wait for the goreleaser workflow to complete and review the draft release:
+```bash
+gh run watch --repo apstndb/spanner-mycli
+gh release view $ARGUMENTS --repo apstndb/spanner-mycli
+```
+
+8. Enhance the release notes before publishing:
+   - For spanemuboost bump PRs, look up the emulator version and add it as a sub-bullet:
+     ```bash
+     # Replace <VERSION> with the spanemuboost version from the PR
+     gh api "repos/apstndb/spanemuboost/contents/spanemuboost.go?ref=<VERSION>" -q '.content' | base64 -d | grep DefaultEmulatorImage
+     ```
+   - For major new features, add an actual output example as a sub-bullet
+   - Update the release notes via:
+     ```bash
+     gh release edit $ARGUMENTS --repo apstndb/spanner-mycli --notes "..."
+     ```
+
+9. Publish the release:
+```bash
+gh release edit $ARGUMENTS --repo apstndb/spanner-mycli --draft=false
+gh release view $ARGUMENTS --repo apstndb/spanner-mycli --json isDraft,url
+```
 
 **Label → Release notes mapping:**
 - `breaking-change` → "Breaking Changes"

.claude/commands/review-cycle.md

@@ -7,8 +7,13 @@ description: Wait for Gemini review and check feedback
 
 Please execute the following steps:
 
-1. Wait for Gemini review (request if needed):
-!go tool gh-helper reviews wait --request-review
+1. Wait for Gemini code review:
+!go tool gh-helper reviews wait
+
+**IMPORTANT**: `/gemini summary` and `/gemini review` are DIFFERENT commands.
+- `/gemini summary` generates a "Summary of Changes" — this is posted **automatically** on PR creation. Never request it manually.
+- `/gemini review` triggers an **inline code review** — this is also automatic but may take several minutes for large PRs.
+- If the wait times out without a review, **wait longer or request `/gemini review`** (NOT `/gemini summary`).
 
 2. Check for unresolved threads:
 !go tool gh-helper reviews fetch --unresolved-only

.claude/commands/start-issue.md

@@ -0,0 +1,33 @@
+---
+allowed-tools: Bash, mcp__github__issue_read, mcp__Phantom__phantom_create_worktree
+description: Start working on a GitHub issue by fetching latest state and creating a worktree
+arguments: "<issue number>"
+---
+
+## Context
+
+You are starting work on issue #$ARGUMENTS in the spanner-mycli repository.
+
+## Your task
+
+1. Fetch the latest state from origin:
+   ```bash
+   git fetch origin
+   ```
+
+2. Read the issue details to understand the task:
+   - Use `mcp__github__issue_read` with method `get` for issue #$ARGUMENTS
+   - Also check sub-issues: `go tool gh-helper issues show $ARGUMENTS --include-sub`
+
+3. Derive a descriptive worktree name from the issue title:
+   - Format: `issue-{N}-{slug}` (e.g., `issue-483-read-lock-mode`)
+   - Slug: lowercase, hyphens only, strip conventional prefixes (`feat:`, `fix:`, `chore:`, etc.)
+   - Keep it concise (3-5 meaningful words max)
+
+4. Create the worktree:
+   - Use `mcp__Phantom__phantom_create_worktree` with `name=issue-{N}-{slug}` and `baseBranch=origin/main`
+
+5. Report:
+   - The issue title and summary
+   - The worktree path and branch name created
+   - Key implementation points to address

CLAUDE.md

@@ -34,7 +34,7 @@ spanner-mycli is a personal fork of spanner-cli, an interactive CLI for Google C
 2. **Resolve conflicts with origin/main** - ensure branch can merge cleanly
 3. **Never push/commit directly to main branch** - always use feature branches + PRs
 4. **Squash merge only** - enforced via Repository Ruleset
-5. **PR merge process**: Use `go tool gh-helper reviews wait` before merging (**DO NOT** use `--request-review`). Request `/gemini summary` only if additional commits were pushed after initial review.
+5. **PR merge process**: Use `go tool gh-helper reviews wait` before merging. Gemini review and summary are auto-triggered on PR creation — do NOT use `--request-review` or `--request-summary` at that point. After additional commits: use `--request-review` to get a new review. Use `--request-summary` only right before merge to update the summary.
 6. **Squash merge commits**: MUST include descriptive summary of PR changes
 7. **GitHub comment editing**: NEVER use `gh pr comment --edit-last` - always specify exact comment ID
 8. **GitHub checks must pass**: All CI checks MUST pass before merging. Always investigate failures - never assume they are transient.

dev-docs/issue-management.md

@@ -42,20 +42,24 @@ go tool gh-helper threads resolve <ID1> <ID2> <ID3>    # Batch resolve threads
 
 **Gemini Review Workflow:**
 ```bash
-# 1. Create PR (Gemini automatically reviews initial creation)
+# 1. Create PR (Gemini automatically reviews and summarizes)
 gh pr create --title "feat: new feature" --body "Description"
 
-# 2. Wait for automatic Gemini review (initial PR only)
+# 2. Wait for automatic Gemini review (initial PR only — no flags needed)
 go tool gh-helper reviews wait --timeout 15m
 
-# 3. For subsequent pushes: ALWAYS request Gemini review
+# 3. After additional commits: request a new review
 git add <specific-files> && git commit -m "fix: address feedback" && git push
 go tool gh-helper reviews wait <PR> --request-review --timeout 15m
+
+# 4. Right before merge: update summary if additional commits were pushed
+go tool gh-helper reviews wait <PR> --request-summary --timeout 15m
 ```
 
 **Gemini Review Rules:**
-- ✅ Initial PR creation: Automatic review (no flag needed)
-- ✅ All subsequent pushes: MUST use `--request-review` flag
+- ✅ Initial PR creation: Review and summary are auto-triggered (no flags needed)
+- ✅ After additional commits: Use `--request-review` for a new review
+- ✅ Right before merge: Use `--request-summary` to update the summary
 - ✅ Always wait for review completion before proceeding
 
 ## Issue Management