fix doc-pr to give acknowledgement comment with todos, refine editorial review so it focuses only on changes

.claude/skills/doc-pr-fix/SKILL.md

@@ -47,17 +47,27 @@ Example tasks for a "fix all issues" request:
 
 Only include tasks for what the writer actually asked for. The task list must reflect the writer's request exactly.
 
-Then post a PR comment mirroring your task list so the writer can see what you're doing:
+Then update the acknowledgment comment (already posted by the workflow) with your task list. The comment ID is in `$PROGRESS_COMMENT_ID`:
 
 ```bash
-PROGRESS_COMMENT_ID=$(gh pr comment "$PR_NUMBER" --body "$(cat <<'EOF'
+gh api repos/{owner}/{repo}/issues/comments/$PROGRESS_COMMENT_ID \
+  -X PATCH -f body="$(cat <<'EOF'
 **Fix in progress:**
 
 - [ ] Apply editorial suggestions in `path/to/file.md`
 - [ ] Verify changes
 - [ ] Commit and push
 EOF
-)" --format json | jq -r '.id' 2>/dev/null || echo "")
+)"
+```
+
+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 pr comment "$PR_NUMBER" --body "**Fix in progress:** ..." \
+    --format json | jq -r '.id' 2>/dev/null || echo "")
+fi
 ```
 
 As you complete each Todo task, also update the PR comment to check off the corresponding item:

.claude/skills/doc-pr/SKILL.md

@@ -32,23 +32,23 @@ Split the comma-separated file list into individual file paths for processing.
 
 This stage applies the doc-help editing analysis to the PR changes — but non-interactively. You are producing a written review, not having a conversation.
 
-1. Run `gh pr diff $DOC_PR_NUMBER` to get the diff
-2. For each changed file, read the full file content
-3. Analyze ONLY the added or modified lines (lines starting with `+` in the diff) against these priorities:
+1. The PR diff is already saved at `/tmp/pr-diff.txt` — read it with the Read tool. Identify the added lines (starting with `+`, excluding `+++` file headers) and note which file each change belongs to.
+2. For each changed file, **read the full file content**. This gives you the context needed to judge whether new content fits logically, whether a new term was already defined earlier, and whether a new step assumes knowledge established elsewhere in the document.
+3. Using the full file as context, analyze the **added lines only** against these priorities:
 
-   **Structure** — Is the document organized so readers can find what they need? Can a reader scanning the page quickly find the section they need? For procedures, can someone follow it step by step? For explanatory content, does it build from simple to complex?
+   **Structure** — Does the new content fit logically in its position? Would a reader scanning the document find it where they expect it? If it introduces a new section or step, is the placement correct relative to surrounding content?
 
-   **Clarity** — Is the content easy to understand? Can the reader follow the explanation without having to reread, guess at meaning, or fill in gaps?
+   **Clarity** — Is the new content easy to understand on its own? Does it use a term or concept that hasn't been defined yet in the document?
 
-   **Completeness** — After reading, can the reader do what they came to do? Are there gaps that would force them to search elsewhere or open a support ticket?
+   **Completeness** — Does the new content leave the reader with an unanswered question? If it introduces a new concept, term, step, or instruction, does it provide enough context — or does the reader need to look elsewhere?
 
 For each issue found, note:
 - The file path and line number
 - The priority category (Structure, Clarity, or Completeness)
 - A specific description of the problem
 - A concrete suggested fix
 
-Only report issues on lines that were added or modified in this PR. Do not flag preexisting issues.
+**Report issues only on added lines.** The full file is context for your judgment — not a source of additional issues to flag. Do not report problems on lines that were unchanged in this PR.
 
 **Idiom tagging:** When the editorial review catches an idiom or figurative expression, tag it with `[idiom]` at the start of the bullet so the fixer can identify it and add it to the Vale `Idioms.yml` rule. Example:
 

.github/workflows/claude-doc-pr.yml

@@ -162,6 +162,18 @@ jobs:
           gh pr comment ${{ steps.pr-info.outputs.number }} --repo ${{ github.repository }} \
             --body "This PR is from a fork. Automated fixes cannot be pushed directly. I can still review and suggest changes — apply them manually from the comments."
 
+      - name: Post acknowledgment comment
+        id: ack-comment
+        if: steps.pr-info.outputs.is_fork == 'false' && steps.pr-info.outputs.targets_dev == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          COMMENT_ID=$(gh pr comment "${{ steps.pr-info.outputs.number }}" \
+            --repo "${{ github.repository }}" \
+            --body "**Acknowledged:** Analyzing your request — I'll update this comment with a task list shortly." \
+            --format json | jq -r '.id')
+          echo "comment_id=$COMMENT_ID" >> "$GITHUB_OUTPUT"
+
       - name: Checkout repository
         if: steps.pr-info.outputs.is_fork == 'false' && steps.pr-info.outputs.targets_dev == 'true'
         uses: actions/checkout@v4
@@ -176,6 +188,7 @@ jobs:
         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 }}