From 79ae000606db1228aff98e6527cbd864fb621520 Mon Sep 17 00:00:00 2001 From: jth-nw Date: Mon, 16 Mar 2026 11:44:35 -0500 Subject: [PATCH] feat: add progress tracking and improve @claude comment footers - doc-pr-fix now posts a live progress comment with Todo-driven checklist - Task list scoped to only what the writer asked for - PR review footer shows diverse example @claude commands - Vale summary footer frames fix command as one example Co-Authored-By: Claude Opus 4.6 --- .claude/skills/doc-pr-fix/SKILL.md | 66 ++++++++++++++++++++++++----- .github/workflows/claude-doc-pr.yml | 8 ++-- .github/workflows/vale-linter.yml | 2 +- 3 files changed, 62 insertions(+), 14 deletions(-) diff --git a/.claude/skills/doc-pr-fix/SKILL.md b/.claude/skills/doc-pr-fix/SKILL.md index 162429ca8d..c555f1672e 100644 --- a/.claude/skills/doc-pr-fix/SKILL.md +++ b/.claude/skills/doc-pr-fix/SKILL.md @@ -43,7 +43,44 @@ Parse the writer's comment to determine what they want. Common patterns: ``` This gives you the Vale results table with file paths, line numbers, and rule violations. -## Step 3: Apply fixes +## Step 3: Plan your work and post a progress comment + +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. + +Example tasks for a "fix all issues" request: +- Fix Vale issues in `path/to/file.md` (N issues) +- Fix Vale issues in `path/to/other.md` (N issues) +- Fix Dale issues in `path/to/file.md` (N issues) +- Apply editorial suggestions +- Verify changes +- Commit and push + +Only include tasks for what the writer actually asked for. If they said "fix only the Dale issues," your task list should contain Dale fixes, verify, and commit — no Vale tasks, no editorial tasks. 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: + +```bash +PROGRESS_COMMENT_ID=$(gh pr comment "$PR_NUMBER" --body "$(cat <<'EOF' +**Working on it...** ✏️ + +- [ ] Fix Vale issues in `path/to/file.md` (N issues) +- [ ] Fix Vale issues in `path/to/other.md` (N issues) +- [ ] Verify changes +- [ ] Commit and push +EOF +)" --format json | jq -r '.id' 2>/dev/null || echo "") +``` + +As you complete each Todo task, also update the PR comment to check off the corresponding item: + +```bash +gh api repos/{owner}/{repo}/issues/comments/$PROGRESS_COMMENT_ID \ + -X PATCH -f body="" +``` + +Update the PR comment at natural milestones (after finishing each file, after committing, etc.) — not after every single edit. + +## Step 4: Apply fixes Work through the requested fixes methodically: @@ -58,11 +95,11 @@ When editing: - Preserve the author's meaning and intent — fix the style, don't rewrite the content - Only change what was requested; don't fix other categories of issues even if they're on the same line (e.g., if asked to fix Vale issues, don't also fix Dale or editorial issues) -## Step 4: Verify +## Step 5: Verify Review your edits to ensure they don't introduce new issues. Do NOT run Dale or any other skills during verification. -## Step 5: Commit and push +## Step 6: Commit and push Stage only the files you changed: @@ -76,20 +113,29 @@ Co-Authored-By: Claude " git push ``` -## Step 6: Report +## Step 7: Final update + +Replace the progress comment with a completion summary. Don't post a separate comment — update the same one: -Post a PR comment summarizing what you did: +```bash +gh api repos/{owner}/{repo}/issues/comments/$PROGRESS_COMMENT_ID \ + -X PATCH -f body="$(cat <<'EOF' +**Fixes applied** ✅ -```markdown -**Fixes applied:** +- [x] Read PR diff and review comments +- [x] Fix Vale issues in `path/to/file.md` (N issues) +- [x] Fix Vale issues in `path/to/other.md` (N issues) +- [x] Verify changes +- [x] Commit and push +**Summary:** - `path/to/file.md`: - `path/to/other.md`: - -Dale checks pass on all edited files. +EOF +)" ``` -If you were asked to explain something rather than fix it, your comment IS the deliverable — no summary needed. +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 diff --git a/.github/workflows/claude-doc-pr.yml b/.github/workflows/claude-doc-pr.yml index 8d7237e1d0..23c03a838b 100644 --- a/.github/workflows/claude-doc-pr.yml +++ b/.github/workflows/claude-doc-pr.yml @@ -192,9 +192,11 @@ jobs: --- **What to do next:** - Comment `@claude` on this PR followed by your instructions to get help: - - `@claude fix all issues` — fix all Dale and editorial issues - - `@claude help improve the flow of this document` — get writing assistance + Comment `@claude` on this PR followed by your instructions. For example: + - `@claude fix all issues` + - `@claude fix only the Dale issues` + - `@claude reorganize the prerequisites section` + - `@claude help improve the flow of this document` > Automated fixes are only available for branches in this repository, not forks. Step 4: Post the comment by running this exact command: diff --git a/.github/workflows/vale-linter.yml b/.github/workflows/vale-linter.yml index c8cf6460f1..8dafc57cea 100644 --- a/.github/workflows/vale-linter.yml +++ b/.github/workflows/vale-linter.yml @@ -152,7 +152,7 @@ jobs: cat /tmp/vale-body.md echo "---" echo "" - echo 'Fix these issues locally with `vale ` and push again. Comment `@claude fix only the Vale issues` to have them fixed automatically.' + echo 'Fix these issues locally with `vale ` and push again, or comment `@claude` followed by your instructions (e.g., `@claude fix only the Vale issues`).' echo "" echo '> Automated fixes are only available for branches in this repository, not forks.' } > /tmp/vale-comment.md