From 78675b23cd4ec6c0fb8856f4eeada53261b78cf8 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Fri, 6 Feb 2026 14:56:17 +0200 Subject: [PATCH] docs: Clarify on-demand trigger model and use sentence case - Fix incorrect "automatic" trigger claims in .claude/README.md - Clarify that editorial reviews are on-demand only (not automatic) - Add explicit callout in CLAUDE.md explaining trigger model - Separate local vs PR workflow steps for clarity - Update headings to sentence case in all documentation - Emphasize manual nature: triggered by /editorial-review command only Co-Authored-By: Claude Sonnet 4.5 --- .claude/README.md | 27 +++++++++++++++++++-------- .github/scripts/README.md | 4 ++-- CLAUDE.md | 6 +++++- 3 files changed, 26 insertions(+), 11 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 324c22a1c..e39d3aeb7 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -116,9 +116,13 @@ Ensures consistent punctuation across documentation. **File:** `.github/workflows/docs-review.yml` -**Triggers:** -- **Automatic:** PR creation or reopen for `platform-*` directories -- **Manual:** Workflow dispatch (see below) +**Triggers (on-demand only):** +- **PR comment:** Comment `/editorial-review` on any PR +- **Manual workflow dispatch:** Via GitHub Actions UI (see below) +- **Local:** Use `/editorial-review` command in Claude Code CLI + +**NOT triggered by:** +- PR creation, updates, or commits (to conserve tokens) **How it works:** 0. Validates bash script syntax (fails fast if scripts have errors) @@ -187,11 +191,18 @@ When working on API documentation: ### Working with editorial content -When working on documentation content: -1. Open PR → Agents automatically review changes -2. Review inline suggestions on affected lines -3. Apply fixes individually or batch-apply multiple -4. Re-run workflow manually from Actions tab if needed +**Local development (before PR):** +1. Make doc changes locally +2. Run `/editorial-review ` in Claude Code +3. Review findings and apply fixes +4. Commit and push + +**PR review (on-demand):** +1. Open PR with documentation changes +2. Comment `/editorial-review` to trigger review +3. Review inline suggestions on affected lines +4. Apply fixes individually or batch-apply multiple +5. Comment `/editorial-review` again to verify fixes ### Testing changes locally diff --git a/.github/scripts/README.md b/.github/scripts/README.md index 8b867a169..fde01f695 100644 --- a/.github/scripts/README.md +++ b/.github/scripts/README.md @@ -93,7 +93,7 @@ Converts Claude agent review findings into GitHub inline suggestions that can be ./post-inline-suggestions.sh ``` -### Input Format +### Input format The script expects a review file with this format: @@ -131,7 +131,7 @@ corrected text here Users can then click "Commit suggestion" to apply the fix directly from the PR interface. -### How It Works +### How it works 1. Parses the structured review file 2. Groups suggestions by file and line diff --git a/CLAUDE.md b/CLAUDE.md index 8463ad63e..e53761bfa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,6 +8,10 @@ This guide covers documentation standards, editorial workflows, and Claude-power - **Local review** → Use `/review ` → See issues before committing - **Apply fixes** → Address issues directly in files based on agent feedback +> **Important:** Editorial reviews are **on-demand only**. They do NOT run automatically on PR creation or commits. You must explicitly trigger them by: +> - Running `/editorial-review` locally in Claude Code, OR +> - Commenting `/editorial-review` on a PR + ## Workflows and architecture This repository uses two main Claude-powered workflows: @@ -118,7 +122,7 @@ The agents provide a structured report with: 3. Review full list in `all-suggestions-full.txt` 4. Apply remaining suggestions manually -## Local Review with `/review` +## Local review with `/review` Run editorial reviews locally before opening a PR: