From 07a876d6b4761865ea3d48ea4f5cf4043b1ca9fe Mon Sep 17 00:00:00 2001 From: jth-nw Date: Thu, 14 May 2026 10:13:42 -0500 Subject: [PATCH] fix(doc-pr): expand comment body in prompt; split question vs task handling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit $COMMENT_BODY was passed as a literal string and blocked by the simple_expansion security check when Claude tried to read it. Switch to GitHub Actions expressions so all context (PR number, repo, comment body, progress comment ID) arrives as literal values — no shell variable expansion needed. Also: split doc-pr-fix skill behavior so questions get a direct answer (no task list language) and file-edit tasks get progress tracking. Neutral ack text replaces the misleading "task list shortly" wording. Generated with AI Co-Authored-By: Claude Code --- .claude/skills/doc-pr-fix/SKILL.md | 65 +++++++++++++++++------------ .github/workflows/claude-doc-pr.yml | 11 +++-- 2 files changed, 45 insertions(+), 31 deletions(-) diff --git a/.claude/skills/doc-pr-fix/SKILL.md b/.claude/skills/doc-pr-fix/SKILL.md index 946b0b98e5..0f5c98015e 100644 --- a/.claude/skills/doc-pr-fix/SKILL.md +++ b/.claude/skills/doc-pr-fix/SKILL.md @@ -12,9 +12,13 @@ Read `docs/CLAUDE.md` before starting. It contains the Netwrix writing standards ## Input -You receive: -- `$1`: The PR number -- `$2`: The writer's comment text (everything after `@claude`) +The prompt contains labeled fields — extract these values and use them as literals throughout: +- `PR: ` — the PR number (e.g. `913`) +- `Repo: ` — the repository (e.g. `netwrix/docs`) +- `Progress comment ID: ` — ID of the "On it." comment already posted (may be empty) +- `Writer's request: ` — everything the writer wrote after `@claude` + +Do not use shell variable expansion (`$VAR`) in any commands — use the literal values you extracted from the prompt. ## Step 1: Understand the request @@ -28,29 +32,48 @@ Parse the writer's comment to determine what they want. Common patterns: ## Step 2: Gather context -1. Run `gh pr diff $PR_NUMBER` to see what changed in the PR +1. Run `gh pr diff ` (use the literal number from the prompt) to see what changed 2. Read the full content of each changed markdown file 3. Find the most recent "Documentation PR Review" comment on the PR: ```bash - gh api repos/{owner}/{repo}/issues/$PR_NUMBER/comments --jq '.[] | select(.body | contains("Documentation PR Review")) | .body' | tail -1 + gh api repos///issues//comments --jq '.[] | select(.body | contains("Documentation PR Review")) | .body' | tail -1 ``` This tells you what the editorial review flagged. -## Step 3: Plan your work and post a progress comment +## Step 3: Respond based on request type + +### If the request is a question or asks for an explanation + +Answer it directly. Do not create a todo list or edit any files. Update the "On it." comment with your answer: -Use Todo to create a task for each discrete piece of work you need to do. Build the task list from what you learned in Steps 1–2. Each task should be concrete and trackable. Mark each task as complete as you finish it. +```bash +gh api repos///issues/comments/ \ + -X PATCH -f body="" +``` + +If the progress comment ID is empty, post a new comment instead: + +```bash +gh pr comment --repo / --body "" +``` + +Then stop — skip Steps 4–7. + +### If the request requires file edits + +Use Todo to create a task for each discrete piece of work. Build the task list from Steps 1–2. Each task should be concrete and trackable. Mark each task complete as you finish it. Example tasks for a "fix all issues" request: - Apply editorial suggestions in `path/to/file.md` - Verify changes - Commit and push -Only include tasks for what the writer actually asked for. The task list must reflect the writer's request exactly. +Only include tasks for what the writer actually asked for. -Then update the acknowledgment comment (already posted by the workflow) with your task list. The comment ID is in `$PROGRESS_COMMENT_ID`: +Update the "On it." comment with your task list (use literal values from the prompt — no shell variables): ```bash -gh api repos/{owner}/{repo}/issues/comments/$PROGRESS_COMMENT_ID \ +gh api repos///issues/comments/ \ -X PATCH -f body="$(cat <<'EOF' **Fix in progress:** @@ -61,24 +84,14 @@ EOF )" ``` -If `$PROGRESS_COMMENT_ID` is empty for any reason, fall back to creating a new comment: - -```bash -if [ -z "${PROGRESS_COMMENT_ID:-}" ]; then - PROGRESS_COMMENT_ID=$(gh api "repos/$REPO_OWNER/$REPO_NAME/issues/$PR_NUMBER/comments" \ - --method POST --field body="**Fix in progress:** ..." \ - --jq '.id' 2>/dev/null || echo "") -fi -``` - -As you complete each Todo task, also update the PR comment to check off the corresponding item: +If the progress comment ID is empty, create a new comment and note its ID for the final update: ```bash -gh api repos/{owner}/{repo}/issues/comments/$PROGRESS_COMMENT_ID \ - -X PATCH -f body="" +gh api repos///issues//comments \ + --method POST --field body="**Fix in progress:** ..." --jq '.id' ``` -Update the PR comment at natural milestones (after finishing each file, after committing, etc.) — not after every single edit. +Update the comment at natural milestones (after finishing each file, after committing) — not after every edit. ## Step 4: Apply fixes @@ -116,7 +129,7 @@ git push Replace the progress comment with a completion summary. Don't post a separate comment — update the same one: ```bash -gh api repos/{owner}/{repo}/issues/comments/$PROGRESS_COMMENT_ID \ +gh api repos///issues/comments/ \ -X PATCH -f body="$(cat <<'EOF' **Fix complete:** @@ -131,8 +144,6 @@ EOF )" ``` -Skip progress tracking only for pure explanations (e.g., "why is this flagged?") where your PR comment IS the deliverable and no files are edited. All other requests — including editorial rewrites like "improve the flow" — should use progress tracking. - ## Behavioral Notes - **Fix what's clear, ask about what isn't.** If a request has both obvious parts and ambiguous parts, apply the obvious fixes, commit and push those, then post a comment that summarizes what you did AND asks clarifying questions about the rest. The writer can reply with another `@claude` comment to continue. diff --git a/.github/workflows/claude-doc-pr.yml b/.github/workflows/claude-doc-pr.yml index 47985d10f6..bf04b577c7 100644 --- a/.github/workflows/claude-doc-pr.yml +++ b/.github/workflows/claude-doc-pr.yml @@ -172,7 +172,7 @@ jobs: run: | COMMENT_ID=$(gh api "repos/${{ github.repository }}/issues/${{ steps.pr-info.outputs.number }}/comments" \ --method POST \ - --field body="**Acknowledged:** Analyzing your request — I'll update this comment with a task list shortly." \ + --field body="**On it.** I'll reply here shortly." \ --jq '.id') echo "comment_id=$COMMENT_ID" >> "$GITHUB_OUTPUT" @@ -189,12 +189,15 @@ jobs: uses: anthropics/claude-code-action@v1 env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - COMMENT_BODY: ${{ github.event.comment.body }} - PROGRESS_COMMENT_ID: ${{ steps.ack-comment.outputs.comment_id }} with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} github_token: ${{ secrets.VALE_TOKEN }} show_full_output: true prompt: | - /doc-pr-fix ${{ steps.pr-info.outputs.number }} $COMMENT_BODY + /doc-pr-fix + PR: ${{ steps.pr-info.outputs.number }} + Repo: ${{ github.repository }} + Progress comment ID: ${{ steps.ack-comment.outputs.comment_id }} + + Writer's request: ${{ github.event.comment.body }} claude_args: '--max-turns 50 --allowedTools "Bash(gh:*),Bash(git:*),Read,Write,Edit,Glob,Grep,Skill(doc-pr-fix),Skill(doc-help)"'