Add refinements to the Claude "update pull request" command

[forstmeier]

Overview

Changes

• refine querying operations
• ensure file/paths exist prior to operations

Context

I noticed a lot of sub-optimal performance from the command and this is a fix for that.

Summary by CodeRabbit

• Documentation
  • Introduced a required local scratch workspace initialization and validation step before file operations.
  • Persisted environment setup across shell sessions to simplify repeated commands.
  • Replaced the single-file PR export with a structured JSON export workflow and updated guidance for reading those files.
  • Improved examples and instructions for locating PR/comment IDs, constructing review/comment actions, and handling threads and check failures.

[coderabbitai]

📝 Walkthrough

Walkthrough

Replaces a single pr_data.json workflow with a structured extraction that writes separate JSON files (metadata.json, review_threads.json, outdated_threads.json, pr_comments.json, check_failures.json), adds SCRATCHPAD initialization/validation and OWNER/REPO derivation, and updates extraction, analysis, and GraphQL mutation examples to use the new files.

Changes

Cohort / File(s)

Summary

PR Workflow Documentation .claude/commands/update-pull-request.md

Adds SCRATCHPAD creation/validation and persistent environment export; derives and exports OWNER/REPO from git remote; replaces single pr_data.json with multiple structured outputs (metadata.json, review_threads.json, outdated_threads.json, pr_comments.json, check_failures.json); updates jq queries, analysis steps, mutation examples, and examples for extracting PR/comment node IDs; adds pre-checks for SCRATCHPAD writability and explicit error handling.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Script as "update-pull-request.sh"
    participant Git as "git remote"
    participant GitHub as "GitHub GraphQL API"
    participant FS as "Scratchpad (FS)"

    User->>Script: invoke command
    Script->>FS: ensure/create SCRATCHPAD dir (private, writable)
    Script->>Git: read remote URL to extract OWNER/REPO
    Script->>GitHub: fetch PR data (GraphQL)
    GitHub-->>Script: PR payload
    Script->>FS: write metadata.json, review_threads.json, outdated_threads.json, pr_comments.json, check_failures.json
    Script->>User: print counts and instructions (IDs for mutations)
    User->>Script: run suggested GraphQL mutations using IDs from files
    Script->>GitHub: send addPullRequestReviewComment / resolve mutations

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Expand "update pull request" command specificity #750 — Overlaps on update-pull-request documentation changes and outdated-thread handling; closely related to the multi-file extraction rewrite.
• Add Claude commands/remove Ralph logic #740 — Earlier modification of the same .claude/commands/update-pull-request.md file that this change extends/restructures.
• Add Ralph autonomous development workflow #728 — Prior work touching review-thread handling and GraphQL mutation examples referenced by the new file-based approach.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main purpose of the PR—refining the Claude update pull request command—which aligns with the changeset's focus on improving the .claude/commands/update-pull-request.md file with fixes and enhancements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refine-update-pull-request-command-functionality

---

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

[Copilot]

Pull request overview

Refines the “update pull request” command to reduce redundant querying and to use intermediate, structured JSON files for subsequent steps.

Changes:

• Adds scratchpad setup/validation and exports SCRATCHPAD early for consistent temp-file usage.
• Replaces scattered jq parsing with a single extraction pass into focused JSON artifacts (metadata, threads, comments, check failures).
• Updates later steps to consume the extracted files rather than re-parsing the large GraphQL response.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In @.claude/commands/update-pull-request.md:
- Around line 357-361: Add a blank line before and after the fenced code block
that starts with "```bash" and contains the COMMENT_ID=$(jq -r '.[] |
select(.threadId == "PRRT_xxx") | .comments[0].id'
"${SCRATCHPAD}/review_threads.json") line so the Markdown complies with MD031;
specifically insert an empty line between the preceding "Example to get comment
node ID:" text and the opening ```bash, and another empty line after the closing
``` fence.
- Around line 212-220: The jq pipeline is iterating check runs directly so
.checkSuite is unavailable and workflowRunId ends up null; instead iterate check
suites first and capture the parent suite (e.g., .checkSuites.nodes[] as $suite)
then iterate its .checkRuns.nodes[] and build each entry using
$suite.workflowRun.databaseId (e.g., .checkSuites.nodes[] as $suite |
$suite.checkRuns.nodes[] | {name: .name, conclusion: .conclusion, detailsUrl:
.detailsUrl, workflowRunId: ($suite.workflowRun.databaseId // null)}), keeping
the existing select(...) filter and unique_by(.name) logic.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR updates the Claude /update-pull-request command to reduce repeated querying by fetching PR data once via GraphQL and then extracting focused JSON artifacts (metadata.json, review_threads.json, outdated_threads.json, pr_comments.json, check_failures.json) for later steps.

Main issues to address before merge:

• The new scratchpad setup defaults to a shared /tmp/claude-scratchpad, which undermines the command’s per-session isolation/cleanup expectations.
• The jq used to build check_failures.json references a non-existent .checkSuite field while iterating checkRuns, so workflowRunId extraction won’t work.
• The example jq -r commands for printing thread summaries contain invalid nested quoting around "N/A", so they won’t run as written.

Confidence Score: 2/5

• This PR should not be merged until the updated command examples and jq extraction logic are corrected.
• While the refactor improves performance by consolidating PR data extraction, the current text contains instructions that will fail in normal use (invalid jq quoting and incorrect workflow run ID extraction) and it changes scratchpad behavior in a way that can cause cross-session collisions and stale data reuse.
• .claude/commands/update-pull-request.md

Important Files Changed

Filename	Overview
.claude/commands/update-pull-request.md	Refactors the update-pull-request command to pre-extract PR data into smaller JSON files and adds scratchpad setup, but introduces a non-isolated scratchpad default, a broken jq reference for workflowRunId extraction, and invalid jq string quoting in examples.

[greptile-apps]

_{1 file reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Greptile Overview

Greptile Summary

This PR updates the .claude/commands/update-pull-request.md workflow to (1) create a per-run scratchpad directory via mktemp -d and validate it before use, and (2) reduce repeated parsing by extracting the large GraphQL PR response into smaller JSON artifacts (metadata.json, review_threads.json, outdated_threads.json, pr_comments.json, check_failures.json).

However, the updated examples introduce jq filters that will not parse due to nested quoting in interpolated strings, and the GraphQL addPullRequestReviewComment example wraps the PR node ID in extra quotes (sending 'PR_...' instead of PR_...), which will make the mutation fail as written.

Confidence Score: 2/5

• Not safe to merge as-is because documented commands will fail when followed exactly.
• The PR is documentation-only, but it directly instructs users to run shell+jq+GraphQL commands. As written, at least two jq invocations contain invalid quoting and the GraphQL mutation example appears to send an incorrectly quoted pullRequestId, so following the guide will reliably break key steps (listing threads and posting responses).
• .claude/commands/update-pull-request.md

Important Files Changed

Filename	Overview
.claude/commands/update-pull-request.md	Refactors update-pull-request command docs to create a unique scratchpad dir and pre-extract PR data into smaller JSON files, but introduces broken jq quoting and a GitHub GraphQL mutation quoting issue that will fail at runtime.

[greptile-apps]

_{1 file reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.claude/commands/update-pull-request.md (1)

155-156: ⚠️ Potential issue | 🟡 Minor

Quote the SCRATCHPAD path in redirection to avoid breakage.

If SCRATCHPAD contains spaces or glob characters, the redirection target will fail or point to the wrong path.

🔧 Proposed fix

-  ' -f owner="${OWNER}" -f repo="${REPO}" -F number=${ARGUMENTS} > ${SCRATCHPAD}/pr_data.json
+  ' -f owner="${OWNER}" -f repo="${REPO}" -F number="${ARGUMENTS}" > "${SCRATCHPAD}/pr_data.json"

🤖 Fix all issues with AI agents

In @.claude/commands/update-pull-request.md:
- Around line 49-52: The script calls git remote get-url origin twice to derive
OWNER and REPO; change it to capture the remote once (e.g., store it in a REMOTE
variable) and reuse that variable when extracting OWNER and REPO so parsing is
consistent and you avoid the duplicate external call; update the assignments
that set OWNER and REPO to use the single captured REMOTE value.
- Around line 32-45: Save the current umask before setting umask 077, then
restore it immediately after the scratchpad directory is created and hardening
(the branches that create SCRATCHPAD: the mktemp branch and the caller-provided
branch that runs mkdir -p and chmod 700). Concretely: capture the prior umask
into a variable (e.g., old_umask=$(umask)), set umask 077 for
creation/hardening, perform mktemp or mkdir -p and chmod 700 on SCRATCHPAD, and
then call umask "$old_umask" to restore the original mask so later commands are
unaffected.

[forstmeier]

Thank you for the comprehensive reviews! All feedback has been addressed: fixed jq quoting issues, simplified GraphQL mutation quoting, added umask restore, and optimized git remote calls. Changes committed in c100702.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR significantly improves the update-pull-request command by addressing all previously identified critical issues and refining the workflow:

Key improvements:

• Fixed SCRATCHPAD isolation by using mktemp -d with unique session directories instead of shared /tmp/claude-scratchpad
• Fixed jq checkSuite reference by properly binding parent context with as $suite before iterating checkRuns
• Fixed jq string quoting issues in thread listing commands - now uses proper "N/A" syntax
• Fixed GraphQL mutation string interpolation - now uses "'$PR_ID'" for proper shell variable expansion
• Added comprehensive validation for SCRATCHPAD directory existence and permissions
• Introduced structured data extraction that creates focused JSON files (metadata.json, review_threads.json, etc.) to avoid redundant jq parsing and reduce context usage
• Added validation for PR data fetch and GraphQL response structure
• Improved documentation with clearer instructions about environment variable persistence

Remaining minor issue:
The data extraction block (lines 256-261) doesn't validate that the extracted JSON files were successfully created before attempting to read them with jq 'length'. If any extraction fails, the error messages will be confusing.

Confidence Score: 4/5

• This PR is safe to merge with minimal risk
• Score reflects that all critical issues from previous review threads have been properly addressed (scratchpad isolation, jq syntax errors, GraphQL quoting). The code shows good defensive practices with validation checks and error handling. Only minor improvement suggested is adding validation for extracted JSON files, which is a non-critical enhancement that won't affect correctness in normal operation.
• No files require special attention - the single file changed contains documentation for a Claude command with solid error handling patterns

Important Files Changed

Filename	Overview
.claude/commands/update-pull-request.md	Improved PR command with structured data extraction, SCRATCHPAD validation, and better error handling. Previous critical issues (scratchpad isolation, jq quoting, GraphQL references) have been fixed. Minor risk: no validation that extracted JSON files were created successfully.

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.claude/commands/update-pull-request.md (1)

375-385: ⚠️ Potential issue | 🔴 Critical

Variable expansion bug in GraphQL mutation.

The $PR_ID variable on line 378 will not expand because it's inside single quotes (-f query='...'). In bash, single quotes preserve literal strings and prevent variable expansion. The GraphQL API will receive the literal text $PR_ID instead of the actual pull request ID, causing the mutation to fail.

Fix by switching to double quotes and escaping the inner quotes:

Proposed fix using double quotes

-    gh api graphql -f query='
+    gh api graphql -f query="
       mutation {
         addPullRequestReviewComment(input: {
-          pullRequestId: "'$PR_ID'",
+          pullRequestId: \"$PR_ID\",
           body: "<response_text>",
           inReplyTo: "<comment_node_id>"
         }) {
           comment { id }
         }
       }
-    '
+    "

Alternatively, use the -F flag to pass variables safely:

gh api graphql -f query='
  mutation($prId: ID!) {
    addPullRequestReviewComment(input: {
      pullRequestId: $prId,
      body: "<response_text>",
      inReplyTo: "<comment_node_id>"
    }) { comment { id } }
  }
' -F prId="$PR_ID"