Skip to content

Fix docs-review smart-gate bugs and reduce PR comment spam #1536

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
justinegeffen wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Fix docs-review smart-gate bugs and reduce PR comment spam #1536

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a030d47
Fix docs-review smart-gate bugs and reduce PR comment spam
justinegeffen Jun 8, 2026
28b1362
Merge branch 'master' into justine-smart-gate-fixes
justinegeffen Jun 8, 2026
1526f26
Merge branch 'master' into justine-smart-gate-fixes
justinegeffen Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 18 additions & 56 deletions .github/workflows/docs-review.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,13 +228,17 @@ jobs:
steps:
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # ratchet:actions/checkout@v6.0.3
with:
# Check out the PR head, not the default branch — required for the
# diff against base to be meaningful.
ref: ${{ steps.pr-refs.outputs.head_ref }}
fetch-depth: 0

- name: Check last review time
id: last-review
run: |
# Get timestamp of last /editorial-review comment
LAST_REVIEW=$(gh api repos/${{ github.repository }}/issues/${{ needs.setup.outputs.pr_number }}/comments --jq '[.[] | select(.body | startswith("/editorial-review")) | .created_at] | last' || echo "")
LAST_REVIEW=$(gh api "repos/${{ github.repository }}/issues/${{ needs.setup.outputs.pr_number }}/comments" \
--jq '[.[] | select(.body | startswith("/editorial-review")) | .created_at] | last' || echo "")

if [ -n "$LAST_REVIEW" ]; then
MINUTES_AGO=$(( ($(date +%s) - $(date -d "$LAST_REVIEW" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$LAST_REVIEW" +%s)) / 60 ))
Expand All @@ -249,10 +253,12 @@ jobs:
- name: Calculate meaningful changes
id: changes-size
run: |
# Count lines changed (excluding whitespace)
LINES_CHANGED=$(git diff --ignore-all-space --ignore-blank-lines origin/${{ github.base_ref }}...HEAD -- '*.md' '*.mdx' | wc -l | tr -d ' ')
BASE_REF="${{ steps.pr-refs.outputs.base_ref }}"
git fetch --no-tags --depth=1 origin "$BASE_REF" || git fetch --no-tags origin "$BASE_REF"
# Count lines changed (excluding whitespace) between PR base and head
LINES_CHANGED=$(git diff --ignore-all-space --ignore-blank-lines "origin/${BASE_REF}...HEAD" -- '*.md' '*.mdx' | wc -l | tr -d ' ')
echo "lines_changed=$LINES_CHANGED" >> $GITHUB_OUTPUT
echo "📊 Lines changed: $LINES_CHANGED"
echo "📊 Lines changed against origin/$BASE_REF: $LINES_CHANGED"

- name: Run static analysis
id: static-check
Expand All @@ -262,7 +268,10 @@ jobs:
if command -v npx &> /dev/null; then
echo "Running markdownlint..."
npx --yes markdownlint-cli2@0.22.0 ${{ needs.changes.outputs.docs_files }} 2>&1 | tee /tmp/static-results.txt || true
ISSUES=$(grep -c ":" /tmp/static-results.txt 2>/dev/null || echo "0")
# Count lines that contain a markdownlint rule code (MDxxx),
# not raw colons — markdownlint output has multiple colons per
# line and prints success lines too.
ISSUES=$(grep -cE 'MD[0-9]{3}' /tmp/static-results.txt 2>/dev/null || echo "0")
echo "static_issues=$ISSUES" >> $GITHUB_OUTPUT
echo "📋 Static issues found: $ISSUES"
else
Expand Down Expand Up @@ -471,57 +480,10 @@ jobs:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Summary report
summary:
needs: [setup, changes, vale-lint, editorial-review-skill, consolidated-review]
if: always() && needs.changes.outputs.docs == 'true'
runs-on: ubuntu-latest
steps:
- name: Post Summary
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # ratchet:actions/github-script@v9.0.0
with:
script: |
const jobs = [
{ name: 'Terminology (Vale)', status: '${{ needs.vale-lint.result }}' },
{ name: 'Editorial Review (AI)', status: '${{ needs.editorial-review-skill.result }}' },
{ name: 'Consolidated Review', status: '${{ needs.consolidated-review.result }}' }
];

const statusEmoji = {
'success': '✅',
'failure': '❌',
'skipped': '⏭️',
'cancelled': '🚫'
};

const prType = '${{ needs.changes.outputs.pr_type }}';
const prTypeEmoji = prType === 'rename' ? '🏷️' : '📝';

let summary = `## ${prTypeEmoji} Documentation Review Summary (PR type: ${prType})\n\n`;

if (prType === 'rename') {
summary += '> This PR is primarily file renames/moves. Only critical checks were run.\n\n';
}

summary += '| Check | Status |\n|-------|--------|\n';

for (const job of jobs) {
const emoji = statusEmoji[job.status] || '❓';
summary += `| ${job.name} | ${emoji} ${job.status} |\n`;
}

summary += '\n---\n';
summary += '*Review powered by Claude Code editorial agents*\n';
summary += '\n**To apply suggestions:**\n';
summary += '- Click "Commit suggestion" on individual inline comments\n';
summary += '- Select multiple suggestions and batch commit them together';

await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: ${{ needs.setup.outputs.pr_number }},
body: summary
});
# NOTE: a "summary" job that posted a status-table PR comment used to live
# here. Removed because it duplicated information already visible on the
# consolidated-review comment and the workflow run UI — three comments per
# /editorial-review made PR threads noisy.

# Auto-fix workflow (triggered by /fix-docs comment)
auto-fix:
Expand Down
Loading