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

[apstndb]

Summary

• Clarify when to use --request-review and --request-summary flags with gh-helper reviews wait in CLAUDE.md
• Update release-prep skill for tag-based goreleaser workflow with PR range analysis
• Update review-cycle skill to clarify Gemini review vs summary distinction
• Add new start-issue skill for starting work on GitHub issues with worktree setup

Labels

docs-dev, ignore-for-release

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @apstndb, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request updates the development documentation to provide clearer guidance on the usage of gh-helper reviews wait flags, specifically --request-review and --request-summary. The changes aim to prevent redundant manual requests for Gemini reviews and summaries by detailing when these flags are appropriate, aligning with the automated triggering of these processes upon PR creation.

Highlights

• Gemini Review/Summary Timing: Clarified when to use the --request-review and --request-summary flags with gh-helper reviews wait.
• Automated Triggers: Stated that Gemini review and summary are automatically triggered upon PR creation, eliminating the need for manual requests at that stage.
• Post-Commit Review: Specified that --request-review should only be used after additional commits have been pushed to a PR.
• Pre-Merge Summary: Indicated that --request-summary should only be used immediately before merging a PR to update its summary.

Changelog

• CLAUDE.md
  • Updated instructions for the PR merge process, clarifying when to use --request-review and --request-summary flags.

Activity

• No human activity has occurred on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This PR provides a helpful clarification on the timing for Gemini review and summary requests within CLAUDE.md. However, this change introduces an inconsistency with the more detailed workflow documentation in dev-docs/issue-management.md, which has not been updated to reflect the new process, especially concerning the --request-summary flag. I've added a comment suggesting to update the other documentation file to ensure consistency.

[github-actions]

Code Metrics Report

📊 View detailed coverage report (available for 7 days)

	main (0c76571)	#505 (0337087)	+/-
Coverage	70.0%	69.9%	-0.2%
Code to Test Ratio	1:1.2	1:1.2	0.0
Test Execution Time	1m9s	1m6s	-3s

Details

  |                     | main (0c76571) | #505 (0337087) |  +/-  |
  |---------------------|----------------|----------------|-------|
- | Coverage            |          70.0% |          69.9% | -0.2% |
  |   Files             |             54 |             54 |     0 |
  |   Lines             |           5704 |           5704 |     0 |
- |   Covered           |           3997 |           3990 |    -7 |
  | Code to Test Ratio  |          1:1.2 |          1:1.2 |   0.0 |
  |   Code              |          13118 |          13118 |     0 |
  |   Test              |          16510 |          16510 |     0 |
+ | Test Execution Time |           1m9s |           1m6s |   -3s |

Code coverage of files in pull request scope (66.5% → 64.7%)

Files	Coverage	+/-	Status
internal/mycli/execute_sql.go	73.1%	-0.6%	affected
internal/mycli/metrics/execution_metrics.go	0.0%	-11.2%	affected

---

Reported by octocov

[apstndb]

/gemini review

[gemini-code-assist]

Code Review

The pull request clarifies the review workflow documentation and updates Claude Code skills. The changes primarily involve updating markdown files to reflect new Go features and best practices, as well as refining the release preparation and issue management processes. The new start-issue skill is a valuable addition for streamlining development. Overall, the changes improve clarity and align with modern Go development practices.

[apstndb]

/gemini summary

[gemini-code-assist]

Summary of Changes

This pull request enhances the developer documentation by clarifying the workflow for interacting with Gemini Code Assist during pull request reviews and updating the release preparation process. It also introduces a new utility command to simplify starting work on GitHub issues by automating worktree creation.

Highlights

• Clarified Gemini Review Workflow: The documentation now provides clearer guidance on when to use --request-review and --request-summary flags with gh-helper reviews wait, distinguishing between automatic triggers and manual requests for Gemini reviews and summaries.
• Updated Release Preparation Workflow: The release-prep command has been updated to reflect a tag-based goreleaser workflow, including new steps for deriving PR ranges, pushing release tags, and enhancing draft release notes.
• New 'start-issue' Command: A new Claude command, start-issue, was added to streamline the process of beginning work on GitHub issues by automating the fetching of the latest state and the creation of a dedicated Git worktree.

Changelog

• .claude/commands/release-prep.md
  • Updated the release preparation process to use a tag-based goreleaser workflow instead of milestone-based analysis.
  • Added steps for fetching the latest state, deriving PR ranges, pushing release tags, and reviewing/enhancing draft releases.
  • Expanded the description for ignore-for-release labels to include test-only changes.
• .claude/commands/review-cycle.md
  • Modified the gh-helper reviews wait command to remove the --request-review flag for initial waits.
  • Added a detailed explanation distinguishing between /gemini summary (auto-posted) and /gemini review (inline code review), clarifying when to manually request a review.
• .claude/commands/start-issue.md
  • Added a new command that outlines steps to start working on a GitHub issue, including fetching the latest state, reading issue details, deriving a worktree name, and creating a Git worktree.
• CLAUDE.md
  • Revised the PR merge process guidelines to clarify when to use --request-review and --request-summary flags, emphasizing that initial Gemini reviews and summaries are auto-triggered.
• dev-docs/issue-management.md
  • Updated the 'Gemini Review Workflow' and 'Gemini Review Rules' sections to align with the clarified usage of --request-review and --request-summary flags, and the auto-triggering of initial reviews/summaries.

Activity

• gemini-code-assist[bot] provided an initial summary of changes.
• github-actions[bot] posted a Code Metrics Report.
• apstndb manually requested a /gemini review.
• apstndb manually requested a /gemini summary.
• gemini-code-assist[bot] commented on dev-docs/issue-management.md being out of sync with CLAUDE.md regarding review workflow.
• apstndb addressed the feedback in a subsequent commit.
• gemini-code-assist[bot] provided feedback on the efficiency of PR_NUMS derivation in release-prep.md.
• gemini-code-assist[bot] provided feedback on the robustness of the gh api command for fetching spanemuboost.go content.