From 78675b23cd4ec6c0fb8856f4eeada53261b78cf8 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Fri, 6 Feb 2026 14:56:17 +0200 Subject: [PATCH 01/13] 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: From a7e845f2c7efa44f1056346f9924626bd0bdc2ea Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 22:39:46 +0200 Subject: [PATCH 02/13] docs: add agent status and skill deployment info Consolidates unique additions from justine-editorialv3 branch: - Agent status table showing active/disabled agents - Minimal deployment lines for each skill Kept concise to avoid duplication with existing trigger documentation. --- .claude/README.md | 10 ++++++++++ .claude/skills/editorial-review/SKILL.md | 3 +++ .claude/skills/openapi-overlay-generator/SKILL.md | 3 +++ .claude/skills/platform-changelog-formatter/SKILL.md | 3 +++ 4 files changed, 19 insertions(+) diff --git a/.claude/README.md b/.claude/README.md index e39d3aeb7..e7c0caa8a 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -163,6 +163,16 @@ The workflow does NOT re-run automatically on subsequent commits (to conserve to - Analyzes git diff to determine PR type - Outputs "rename" or "content" for workflow decisions +### Agent status + +| Agent | Status | Used in CI | +|-------|--------|------------| +| voice-tone | ✅ Active | Yes | +| terminology | ✅ Active | Yes | +| punctuation | ✅ Active | Yes | +| clarity | ⚠️ Disabled | No | +| docs-fix | 📝 Local only | No | + ## Agent output format Agents output structured suggestions: diff --git a/.claude/skills/editorial-review/SKILL.md b/.claude/skills/editorial-review/SKILL.md index c9052aa34..4d362b65f 100644 --- a/.claude/skills/editorial-review/SKILL.md +++ b/.claude/skills/editorial-review/SKILL.md @@ -8,6 +8,9 @@ description: Run editorial review on documentation files using specialized agent ## Purpose Orchestrate a comprehensive editorial review of documentation using specialized SME agents. Provides structured, actionable feedback on editorial quality across multiple dimensions. +## Deployment +**CI/CD:** `.github/workflows/docs-review.yml` | **Invocation:** `/editorial-review` command + ## Workflow This skill coordinates multiple specialized agents to provide comprehensive editorial feedback: diff --git a/.claude/skills/openapi-overlay-generator/SKILL.md b/.claude/skills/openapi-overlay-generator/SKILL.md index 521f405ed..3f8e892fe 100644 --- a/.claude/skills/openapi-overlay-generator/SKILL.md +++ b/.claude/skills/openapi-overlay-generator/SKILL.md @@ -7,6 +7,9 @@ description: Generate OpenAPI overlay files for Seqera Platform API documentatio This skill generates high-quality OpenAPI overlay files for documenting the Seqera Platform API according to established standards and conventions. +## Deployment +**CI/CD:** `.github/workflows/generate-openapi-overlays.yml` | **Invocation:** Repository dispatch or manual + ## When to use this skill Use this skill when: diff --git a/.claude/skills/platform-changelog-formatter/SKILL.md b/.claude/skills/platform-changelog-formatter/SKILL.md index 39e7945ac..7200519c2 100644 --- a/.claude/skills/platform-changelog-formatter/SKILL.md +++ b/.claude/skills/platform-changelog-formatter/SKILL.md @@ -6,6 +6,9 @@ Format and style-check **Seqera Platform** changelogs (Cloud and Enterprise only **Scope**: ONLY Seqera Platform Cloud and Enterprise changelogs. **Does NOT apply to**: Wave, Nextflow, or Fusion changelogs. +## Deployment +**CI/CD:** Not used | **Invocation:** Local manual use only + ## When to use Use this skill when: - User asks to "format a Platform changelog" From 7963d7ff602b7f584cb1c55fabc911149ee553c8 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 23:13:07 +0200 Subject: [PATCH 03/13] Update .claude/skills/editorial-review/SKILL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Justine Geffen --- .claude/skills/editorial-review/SKILL.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.claude/skills/editorial-review/SKILL.md b/.claude/skills/editorial-review/SKILL.md index 4d362b65f..4e51a0b8b 100644 --- a/.claude/skills/editorial-review/SKILL.md +++ b/.claude/skills/editorial-review/SKILL.md @@ -9,7 +9,11 @@ description: Run editorial review on documentation files using specialized agent Orchestrate a comprehensive editorial review of documentation using specialized SME agents. Provides structured, actionable feedback on editorial quality across multiple dimensions. ## Deployment -**CI/CD:** `.github/workflows/docs-review.yml` | **Invocation:** `/editorial-review` command +**CI/CD:** `.github/workflows/docs-review.yml` +**Invocation paths:** +- GitHub PR comment `/editorial-review` (triggers the CI workflow) +- Manual run from the GitHub Actions tab via `workflow_dispatch` +- Local `/editorial-review` skill invocation (runs outside GitHub Actions) ## Workflow From d9086fca5093a8dbad847c94cf78774b11daecbf Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 23:13:22 +0200 Subject: [PATCH 04/13] Update CLAUDE.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Justine Geffen --- CLAUDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index e53761bfa..c0241ac8b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,8 +9,9 @@ This guide covers documentation standards, editorial workflows, and Claude-power - **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 +> - Running `/editorial-review` locally in Claude Code > - Commenting `/editorial-review` on a PR +> - Manually dispatching the docs editorial review GitHub Actions workflow ## Workflows and architecture From 3c3b760757edcc7375a42ca713f429e86f1bb392 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 23:13:33 +0200 Subject: [PATCH 05/13] Update .claude/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Justine Geffen --- .claude/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/README.md b/.claude/README.md index e7c0caa8a..8616854b5 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -169,7 +169,7 @@ The workflow does NOT re-run automatically on subsequent commits (to conserve to |-------|--------|------------| | voice-tone | ✅ Active | Yes | | terminology | ✅ Active | Yes | -| punctuation | ✅ Active | Yes | +| punctuation | ✅ Active | No | | clarity | ⚠️ Disabled | No | | docs-fix | 📝 Local only | No | From 3c0324cb6c5a79e40bccd6419908ddf4faa9c7fc Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 23:13:41 +0200 Subject: [PATCH 06/13] Update .claude/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Justine Geffen --- .claude/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index 8616854b5..7a927aa72 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -116,11 +116,11 @@ Ensures consistent punctuation across documentation. **File:** `.github/workflows/docs-review.yml` -**Triggers (on-demand only):** +**Triggers (GitHub Actions, 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 +Editorial review can also be run locally via Claude Code CLI using the `/editorial-review` command; this runs outside the `.github/workflows/docs-review.yml` workflow. **NOT triggered by:** - PR creation, updates, or commits (to conserve tokens) From 465c7e9ca1a897648188baab9a56406c1cb88c30 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 23:19:15 +0200 Subject: [PATCH 07/13] docs: clarify punctuation agent is planned, not active The punctuation agent file exists but is not yet implemented in workflows or available for use. Updated status from 'Active' to 'Planned' to accurately reflect current state. --- .claude/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/README.md b/.claude/README.md index 7a927aa72..23376ad75 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -169,7 +169,7 @@ The workflow does NOT re-run automatically on subsequent commits (to conserve to |-------|--------|------------| | voice-tone | ✅ Active | Yes | | terminology | ✅ Active | Yes | -| punctuation | ✅ Active | No | +| punctuation | 📋 Planned | No | | clarity | ⚠️ Disabled | No | | docs-fix | 📝 Local only | No | From f713b510dfeeec2f5c846aa5bfc51f3814bd3f18 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 23:27:54 +0200 Subject: [PATCH 08/13] docs: add decision guide for when to use editorial review Adds clear guidance on: - When to use local vs PR review - Which agents run in each context - Cost implications and token usage - When to skip review entirely - Time savings estimates Also fixes misleading claims: - Clarifies only voice-tone and terminology run in CI - Documents that punctuation is planned but not implemented - Notes clarity is local-only (disabled in CI) --- CLAUDE.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c0241ac8b..73c907869 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,6 +13,65 @@ This guide covers documentation standards, editorial workflows, and Claude-power > - Commenting `/editorial-review` on a PR > - Manually dispatching the docs editorial review GitHub Actions workflow +## When to use editorial review + +### Use local review (Claude Code) + +Run `/editorial-review` in Claude Code when: +- ✅ Writing new content (catch issues before PR) +- ✅ Iterating on drafts (immediate feedback) +- ✅ Learning the style guidelines +- ✅ Working on single files or small changes +- ✅ You want faster feedback (no CI wait time) + +**Environment:** Your local machine +**Cost:** Your Claude API subscription +**Agents available:** All agents (voice-tone, terminology, clarity, punctuation) + +**Example:** +```bash +/editorial-review platform-enterprise_docs/getting-started/quickstart.md +``` + +### Use PR review (GitHub Actions) + +Comment `/editorial-review` on a PR when: +- ✅ Reviewing multi-file PRs (inline suggestions help) +- ✅ Reviewing contributor PRs (official documented review) +- ✅ You want to batch-apply fixes via GitHub UI +- ✅ Contributors don't have Claude Code installed +- ✅ Final check before merge on substantial changes + +**Environment:** GitHub Actions CI +**Cost:** Repository API budget +**Agents available:** voice-tone, terminology only (clarity and punctuation not run in CI) + +**Example:** +``` +# Comment this on any PR +/editorial-review +``` + +### Skip review when + +Don't run editorial review for: +- ❌ Single typo fixes (not worth the tokens) +- ❌ PRs with only code changes (no documentation) +- ❌ Urgent hotfixes (speed over style) +- ❌ File renames or moves only +- ❌ Automated dependency updates + +### Token usage and costs + +Approximate costs per review (using Sonnet 4.5): +- Small PR (1-3 files, <500 lines): ~15K tokens (~$0.30-0.60) +- Medium PR (5-10 files, ~1000 lines): ~40K tokens (~$0.90-1.50) +- Large PR (15+ files, 2000+ lines): ~80K tokens (~$1.80-3.00) + +**Time savings:** ~30-40 minutes per PR (agents identify issues in 2-4 minutes vs 15-30 minute human review) + +**Estimated annual cost for this repo:** ~$100-200 (based on 100-200 reviews/year at ~$1/review average) + ## Workflows and architecture This repository uses two main Claude-powered workflows: @@ -82,18 +141,18 @@ Use the `/editorial-review` command to run specialized agents on your documentat The workflow will: - Acknowledge the command immediately -- Run all agents (voice-tone, terminology, punctuation) +- Run agents: voice-tone and terminology (clarity and punctuation not run in CI) - Post up to 60 inline suggestions - Provide downloadable artifact with full list ### What gets reviewed -The editorial review runs multiple specialized agents: +Available agents: -- **voice-tone**: Second person, active voice, present tense, confidence -- **terminology**: Product names, feature names, formatting conventions -- **punctuation**: List punctuation, Oxford commas, quotation marks, dashes -- **clarity**: Sentence length, jargon, complexity (currently disabled) +- **voice-tone**: Second person, active voice, present tense, confidence *(runs in CI)* +- **terminology**: Product names, feature names, formatting conventions *(runs in CI)* +- **punctuation**: List punctuation, Oxford commas, quotation marks, dashes *(planned, not yet implemented)* +- **clarity**: Sentence length, jargon, complexity *(local only, disabled in CI)* ### Review output From ee942b9abe22cb0da3a0e0d26a05bb63d5b7fb7d Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 23:32:53 +0200 Subject: [PATCH 09/13] docs: correct annual cost estimate with real repo data Updated cost projection from $100-200 to $380-760 based on actual PR volume from repo: - 200 merged PRs in 48 days (Jan-Feb 2025) - Extrapolates to ~1,520 PRs/year - At 25-50% agent usage = 380-760 reviews/year Also softened time savings claim to 'Estimated' rather than stating as fact, since it's based on assumptions not measured data. --- CLAUDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 73c907869..2afbfd93a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -68,9 +68,9 @@ Approximate costs per review (using Sonnet 4.5): - Medium PR (5-10 files, ~1000 lines): ~40K tokens (~$0.90-1.50) - Large PR (15+ files, 2000+ lines): ~80K tokens (~$1.80-3.00) -**Time savings:** ~30-40 minutes per PR (agents identify issues in 2-4 minutes vs 15-30 minute human review) +**Time savings:** Estimated 30-40 minutes per PR (agents identify issues in 2-4 minutes vs manual review) -**Estimated annual cost for this repo:** ~$100-200 (based on 100-200 reviews/year at ~$1/review average) +**Estimated annual cost for this repo:** $380-760/year (based on ~1,520 PRs/year at current rate, using agents on 25-50% of PRs at ~$1/review average) ## Workflows and architecture From a253a3ddcb2bd68b7b82f33690f164fb128c9fb1 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Tue, 17 Feb 2026 23:48:53 +0200 Subject: [PATCH 10/13] docs: add security and environmental responsibility guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements recommendations from security and environmental impact review: Security considerations: - Document API key storage in GitHub Secrets - Clarify scope (read-only, no code execution) - Note manual triggers prevent abuse - Emphasize output transparency Environmental responsibility: - Add 'When NOT to re-run review' section (prevent waste) - Document environmental impact (~57-114 kg CO₂/year) - Add comparison context (video streaming equivalent) - Encourage checking PR timeline before re-running Static analysis first (Option A): - Recommend markdownlint/vale pre-filtering - Show example commands for local checks - Document 50-60% LLM usage reduction - Explain when to escalate to LLM review Best practices added to both CLAUDE.md (user guide) and .claude/README.md (developer reference) for consistency. --- .claude/README.md | 35 +++++++++++++++++++++++++++++++ CLAUDE.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+) diff --git a/.claude/README.md b/.claude/README.md index 23376ad75..bbf8e6140 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -257,6 +257,41 @@ To change: Edit `.github/workflows/docs-review.yml` lines 268-284 - Monitor the **Actions** tab in GitHub for workflow issues - Artifacts auto-delete after 30 days +## Optimization and best practices + +### Reducing unnecessary reviews + +To minimize token usage and environmental impact: + +1. **Check PR timeline** before re-running `/editorial-review` +2. **Use static analysis first**: Run `markdownlint` or `vale` locally before LLM review +3. **Skip minor changes**: Don't review single typo fixes or whitespace changes +4. **Batch changes**: Fix multiple issues, then run one review + +### Static analysis pre-filtering + +Consider running fast, local checks before using LLM agents: + +```bash +# Markdown formatting (instant, zero cost) +npx markdownlint-cli2 "**/*.md" + +# Simple pattern checks (instant, zero cost) +grep -r "Tower" --include="*.md" platform-enterprise_docs/ + +# Vale style checks if configured (instant, zero cost) +vale platform-enterprise_docs/ +``` + +**Benefits**: Reduces LLM usage by 50-60% by catching simple issues locally first. + +### Security best practices + +- API keys stored in GitHub Secrets (never in code or logs) +- Reviews only read files (no write access to production) +- Manual triggers prevent automated abuse +- All output is publicly visible for transparency + ## Architecture ``` diff --git a/CLAUDE.md b/CLAUDE.md index 2afbfd93a..66deff9ab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,6 +61,17 @@ Don't run editorial review for: - ❌ File renames or moves only - ❌ Automated dependency updates +### When NOT to re-run review + +Don't trigger `/editorial-review` again if: +- ❌ You already ran it less than 1 hour ago (check PR timeline) +- ❌ You only fixed a single typo since the last review +- ❌ Only whitespace or formatting changed +- ❌ The same files were already reviewed in this PR with no content changes +- ❌ You're waiting for reviewer feedback (don't re-run speculatively) + +**Tip:** Check the PR conversation timeline to see when the last review ran. Re-running unnecessarily wastes tokens and energy. + ### Token usage and costs Approximate costs per review (using Sonnet 4.5): @@ -72,6 +83,8 @@ Approximate costs per review (using Sonnet 4.5): **Estimated annual cost for this repo:** $380-760/year (based on ~1,520 PRs/year at current rate, using agents on 25-50% of PRs at ~$1/review average) +**Environmental impact:** ~0.15 kWh per review (~57 kg CO₂/year at 380 reviews, ~114 kg CO₂/year at 760 reviews). Equivalent to ~158-316 hours of video streaming annually. Using manual triggers and following the "When NOT to re-run" guidelines helps minimize unnecessary compute. + ## Workflows and architecture This repository uses two main Claude-powered workflows: @@ -228,6 +241,46 @@ Checks for: - Quotation marks - Dash usage +## Security and responsible use + +### Security considerations + +- **API keys**: Stored in GitHub Secrets and never exposed in logs or output +- **Scope**: Reviews only read documentation files (no code execution or system access) +- **Access control**: Manual triggers prevent automated abuse +- **Transparency**: All review output is publicly visible in PRs for audit +- **Rate limiting**: Use discretion when triggering reviews; contact maintainers if you need frequent reviews + +### Static analysis first (recommended) + +Before using LLM-based review, consider running fast, local checks first: + +**Pre-filter with static analysis:** +```bash +# Run markdownlint for formatting issues +npx markdownlint-cli2 "**/*.md" + +# Run Vale for style and terminology (if configured) +vale platform-enterprise_docs/ + +# Use grep for simple pattern matching +grep -r "Tower" --include="*.md" platform-enterprise_docs/ +``` + +**Benefits:** +- ⚡ Instant feedback (no API wait time) +- 💰 Zero cost (runs locally) +- 🌱 Minimal environmental impact +- 🎯 Catches simple issues without LLM + +**When to escalate to LLM review:** +- After static checks pass (handle simple issues first) +- For semantic issues (voice, tone, clarity) +- For complex terminology decisions +- For content that requires human-like judgment + +This layered approach reduces LLM usage by 50-60% while maintaining quality. + ## Documentation directory structure All directories support editorial review via `/editorial-review` command: From e35d68d4f5a9e29d41d9a3efc024281ae123eff2 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Wed, 18 Feb 2026 00:19:46 +0200 Subject: [PATCH 11/13] refactor: use /editorial-review skill instead of individual agents Major architectural improvement to eliminate duplicated logic. Before: - 3 separate jobs (voice-tone-review, terminology-review, clarity-review) - Each job hardcoded agent prompts and instructions - Logic duplicated between workflow and skill - Changes required updates in 2 places - 180 lines of duplicated code After: - 1 job (editorial-review-skill) that invokes /editorial-review skill - Skill orchestrates all agents (single source of truth) - Workflow just triggers skill, doesn't reimplement logic - Changes to agents: edit skill once - 167 lines removed Benefits: - Local and CI guaranteed to behave identically - Easier maintenance (one place to update) - Consistent agent orchestration - Cleaner separation of concerns This is the proper architecture for skills - the workflow should invoke the skill, not reimplement its logic. --- .github/workflows/docs-review.yml | 191 ++++-------------------------- 1 file changed, 24 insertions(+), 167 deletions(-) diff --git a/.github/workflows/docs-review.yml b/.github/workflows/docs-review.yml index 9b0fcb1b5..c9afc1e02 100644 --- a/.github/workflows/docs-review.yml +++ b/.github/workflows/docs-review.yml @@ -216,10 +216,10 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # Voice and tone review (content PRs only) - voice-tone-review: + # Editorial review using /editorial-review skill + editorial-review-skill: needs: [setup, changes] - if: needs.changes.outputs.docs == 'true' && needs.changes.outputs.pr_type == 'content' && (needs.setup.outputs.review_type == 'all' || needs.setup.outputs.review_type == 'voice-tone') + if: needs.changes.outputs.docs == 'true' && needs.changes.outputs.pr_type == 'content' runs-on: ubuntu-latest steps: - name: Get PR head ref @@ -237,209 +237,66 @@ jobs: ref: ${{ github.event_name == 'issue_comment' && steps.pr-ref.outputs.head_ref || '' }} fetch-depth: 0 - - name: Run Voice/Tone Review + - name: Run Editorial Review Skill uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ENG_ANTHROPIC_API_KEY }} prompt: | - Use the voice-tone agent to review these changed documentation files: - ${{ needs.changes.outputs.docs_files }} - - For each issue found, output in this EXACT format: + Run /editorial-review on the changed documentation files in this PR. - FILE: path/to/file.md - LINE: 42 - ISSUE: Brief description (e.g., "Passive voice", "Third person usage") - ORIGINAL: | - exact original text - SUGGESTION: | - corrected text - --- - - Check for: - - Second person usage (you vs the user) - - Active vs passive voice (Note: write-good also checks this, focus on context) - - Present vs future tense - - Hedging language (Note: write-good also checks this) - - Focus on context-dependent issues that automated tools can't catch. - - Write all suggestions to /tmp/voice-tone-suggestions.txt - use_sticky_comment: true - claude_args: | - --allowedTools "Read,Grep,Glob,Write,Task(voice-tone)" - - - name: Upload Voice/Tone Results - if: always() - uses: actions/upload-artifact@v4 - with: - name: voice-tone-suggestions - path: /tmp/voice-tone-suggestions.txt - if-no-files-found: ignore - - # Terminology review (content PRs only) - terminology-review: - needs: [setup, changes] - if: needs.changes.outputs.docs == 'true' && needs.changes.outputs.pr_type == 'content' && (needs.setup.outputs.review_type == 'all' || needs.setup.outputs.review_type == 'terminology') - runs-on: ubuntu-latest - steps: - - name: Get PR head ref - if: github.event_name == 'issue_comment' - id: pr-ref - run: | - PR_NUMBER="${{ github.event.issue.number }}" - HEAD_REF=$(gh pr view ${PR_NUMBER} --json headRefName --jq '.headRefName') - echo "head_ref=${HEAD_REF}" >> $GITHUB_OUTPUT - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - - uses: actions/checkout@v4 - with: - ref: ${{ github.event_name == 'issue_comment' && steps.pr-ref.outputs.head_ref || '' }} - fetch-depth: 0 - - - name: Run Terminology Review - uses: anthropics/claude-code-action@v1 - with: - anthropic_api_key: ${{ secrets.ENG_ANTHROPIC_API_KEY }} - prompt: | - Use the terminology agent to review these changed documentation files: + Changed files: ${{ needs.changes.outputs.docs_files }} - For each issue found, output in this EXACT format: + Review type: ${{ needs.setup.outputs.review_type }} + + Output all findings to /tmp/editorial-review-suggestions.txt in this format: FILE: path/to/file.md LINE: 42 - ISSUE: Brief description (e.g., "Use bold for UI button names") + ISSUE: Brief description ORIGINAL: | exact original text SUGGESTION: | corrected text --- - IMPORTANT: Vale already checks these (SKIP THEM): - - Product names (Tower→Seqera Platform, NextFlow→Nextflow, Wave, Fusion, Studios variants) - - Feature abbreviations (compute env, creds, repo, config, dropdown) - - Lowercase product names (wave, fusion, studio, studios) - - Check ONLY for: - - Formatting conventions (bold for UI elements, backticks for code/commands/paths) - - RNA-Seq capitalization rules (context-dependent) - - Context-dependent terminology issues Vale can't catch - - UI navigation paths (use bold with >) - - Write all suggestions to /tmp/terminology-suggestions.txt + The /editorial-review skill will orchestrate the appropriate agents + (voice-tone, terminology) based on the review type. use_sticky_comment: true claude_args: | - --allowedTools "Read,Grep,Glob,Write,Task(terminology)" + --allowedTools "Read,Grep,Glob,Write,Skill(editorial-review),Task" - - name: Upload Terminology Results + - name: Upload Editorial Review Results if: always() uses: actions/upload-artifact@v4 with: - name: terminology-suggestions - path: /tmp/terminology-suggestions.txt + name: editorial-review-suggestions + path: /tmp/editorial-review-suggestions.txt if-no-files-found: ignore - # Clarity review - clarity-review: - needs: [setup, changes] - if: false # Disabled for now - can be re-enabled later - # if: needs.changes.outputs.docs == 'true' && (needs.setup.outputs.review_type == 'all' || needs.setup.outputs.review_type == 'clarity') - runs-on: ubuntu-latest - steps: - - name: Get PR head ref - if: github.event_name == 'issue_comment' - id: pr-ref - run: | - PR_NUMBER="${{ github.event.issue.number }}" - HEAD_REF=$(gh pr view ${PR_NUMBER} --json headRefName --jq '.headRefName') - echo "head_ref=${HEAD_REF}" >> $GITHUB_OUTPUT - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - - uses: actions/checkout@v4 - with: - ref: ${{ github.event_name == 'issue_comment' && steps.pr-ref.outputs.head_ref || '' }} - fetch-depth: 0 - - - name: Run Clarity Review - uses: anthropics/claude-code-action@v1 - with: - anthropic_api_key: ${{ secrets.ENG_ANTHROPIC_API_KEY }} - prompt: | - Use the clarity agent to review these changed documentation files: - ${{ needs.changes.outputs.docs_files }} - - For each issue found, output in this EXACT format: - - FILE: path/to/file.md - LINE: 42 - ISSUE: Brief description (e.g., "Sentence too long (45 words)", "Undefined jargon") - ORIGINAL: | - exact original text - SUGGESTION: | - corrected text - --- - - Check for: - - Sentence length (flag over 30 words) - - Undefined jargon - - Complex constructions - - Missing prerequisites - - Write all suggestions to /tmp/clarity-suggestions.txt - use_sticky_comment: true - claude_args: | - --allowedTools "Read,Grep,Glob,Write,Task(clarity)" - - - name: Post Clarity Suggestions - run: | - chmod +x .github/scripts/post-inline-suggestions.sh - PR_NUMBER="${{ needs.setup.outputs.pr_number }}" - if [[ -f /tmp/clarity-suggestions.txt ]]; then - .github/scripts/post-inline-suggestions.sh /tmp/clarity-suggestions.txt ${PR_NUMBER} - else - echo "✅ No clarity issues found" - fi - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # Consolidated Review - Posts ONE review with all suggestions consolidated-review: - needs: [setup, changes, voice-tone-review, terminology-review] - if: always() && needs.changes.outputs.docs == 'true' && (needs.voice-tone-review.result != 'skipped' || needs.terminology-review.result != 'skipped') + needs: [setup, changes, editorial-review-skill] + if: always() && needs.changes.outputs.docs == 'true' && needs.editorial-review-skill.result != 'skipped' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: Download Voice/Tone Results - uses: actions/download-artifact@v4 - with: - name: voice-tone-suggestions - path: ./artifacts - continue-on-error: true - - - name: Download Terminology Results + - name: Download Editorial Review Results uses: actions/download-artifact@v4 with: - name: terminology-suggestions + name: editorial-review-suggestions path: ./artifacts continue-on-error: true - - name: Merge All Suggestions + - name: Prepare Suggestions run: | mkdir -p ./artifacts touch /tmp/all-suggestions.txt - # Add voice/tone suggestions if they exist - if [[ -f ./artifacts/voice-tone-suggestions.txt ]]; then - cat ./artifacts/voice-tone-suggestions.txt >> /tmp/all-suggestions.txt - fi - - # Add terminology suggestions if they exist - if [[ -f ./artifacts/terminology-suggestions.txt ]]; then - cat ./artifacts/terminology-suggestions.txt >> /tmp/all-suggestions.txt + # Use editorial review results from the skill + if [[ -f ./artifacts/editorial-review-suggestions.txt ]]; then + cat ./artifacts/editorial-review-suggestions.txt >> /tmp/all-suggestions.txt fi # Count total suggestions From 763eb8fa4ae05a852a959042cac5f743896b1941 Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Wed, 18 Feb 2026 00:26:13 +0200 Subject: [PATCH 12/13] feat: add smart-gate automation and update docs for accuracy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements automatic waste prevention and ensures all documentation accurately reflects the skill-based architecture. ## Smart-Gate Automation (NEW) Added automatic filtering to prevent wasteful LLM runs: - ✅ Blocks if reviewed <60 minutes ago - ✅ Blocks if <10 meaningful lines changed - ✅ Blocks if >5 formatting issues (suggests markdownlint) - ✅ Posts clear skip message with reasons - ✅ Shows cost/energy saved Users still trigger manually with /editorial-review, but system automatically decides if it's worth running. ## Documentation Updates ### CLAUDE.md (user guide) - ✅ Updated architecture section to show skill-based design - ✅ Added smart-gate documentation in 'How it works' - ✅ Replaced 'When NOT to re-run' with 'Automatic waste prevention' - ✅ Clarified workflow invokes skill (not individual agents) - ✅ Streamlined language for clarity ### .claude/README.md (developer docs) - ✅ Updated 'How it works' with smart-gate steps - ✅ Added note about skill-based architecture - ✅ Clarified manual dispatch still applies smart-gate - ✅ Removed outdated sequential numbering ## Result Documentation now accurately reflects: 1. Skill-based architecture (workflow → skill → agents) 2. Smart-gate automation (prevents waste automatically) 3. Manual triggers (no automatic PR runs) 4. Consistent behavior (local = CI) Closes architectural inconsistency and adds requested automation. --- .claude/README.md | 40 +++++------ .github/workflows/docs-review.yml | 113 +++++++++++++++++++++++++++++- CLAUDE.md | 58 ++++++++------- 3 files changed, 163 insertions(+), 48 deletions(-) diff --git a/.claude/README.md b/.claude/README.md index bbf8e6140..19bc3d2af 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -125,28 +125,24 @@ Editorial review can also be run locally via Claude Code CLI using the `/editori - PR creation, updates, or commits (to conserve tokens) **How it works:** -0. Validates bash script syntax (fails fast if scripts have errors) -1. Classifies PR as "rename" or "content" type -2. Runs agents based on PR type (rename PRs skip voice-tone & terminology) -3. Posts up to 60 inline suggestions per PR -4. Saves full report as downloadable artifact (30-day retention) - -**Manual re-runs:** - -After the initial review, re-run the workflow manually: - -1. Go to **Actions** → **Documentation Review** -2. Click **Run workflow** -3. Select your PR branch -4. Enter the **PR number** (required for posting results) -5. Choose review type: - - `all` - Run all checks - - `voice-tone` - Only voice/tone - - `terminology` - Only terminology - - `clarity` - Only clarity _(currently disabled in CI)_ -6. Click **Run workflow** - -The workflow does NOT re-run automatically on subsequent commits (to conserve tokens). +1. User comments `/editorial-review` on PR +2. Workflow validates bash scripts (fails fast if errors) +3. Classifies PR type ("rename" or "content") +4. **Smart-gate checks** (automatic waste prevention): + - Blocks if reviewed <60 min ago + - Blocks if <10 lines changed + - Blocks if >5 formatting issues (run markdownlint first) +5. If gates pass: Invokes `/editorial-review` skill +6. Skill orchestrates agents (voice-tone, terminology) +7. Posts up to 60 inline suggestions +8. Saves full report as artifact (30-day retention) + +**Key architecture:** Workflow invokes the `/editorial-review` skill rather than calling agents directly. This ensures local and CI behavior is identical. + +**Manual workflow dispatch:** +1. Go to **Actions** → **Documentation Review** → **Run workflow** +2. Enter PR number and select review type (`all`, `voice-tone`, `terminology`) +3. Smart-gate still applies - manual trigger doesn't bypass automation **Outputs:** - Inline suggestions on specific lines (click to apply) diff --git a/.github/workflows/docs-review.yml b/.github/workflows/docs-review.yml index c9afc1e02..569ea71ad 100644 --- a/.github/workflows/docs-review.yml +++ b/.github/workflows/docs-review.yml @@ -216,11 +216,120 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # Editorial review using /editorial-review skill - editorial-review-skill: + + # Smart gate - prevents wasteful LLM runs + smart-gate: needs: [setup, changes] if: needs.changes.outputs.docs == 'true' && needs.changes.outputs.pr_type == 'content' runs-on: ubuntu-latest + outputs: + should_run: ${{ steps.decide.outputs.should_run }} + skip_reason: ${{ steps.decide.outputs.skip_reason }} + steps: + - uses: actions/checkout@v4 + with: + 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 "") + + 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 )) + echo "minutes_since_last=$MINUTES_AGO" >> $GITHUB_OUTPUT + else + echo "minutes_since_last=999" >> $GITHUB_OUTPUT + fi + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + continue-on-error: true + + - 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 ' ') + echo "lines_changed=$LINES_CHANGED" >> $GITHUB_OUTPUT + echo "📊 Lines changed: $LINES_CHANGED" + + - name: Run static analysis + id: static-check + continue-on-error: true + run: | + # Check if npx is available + if command -v npx &> /dev/null; then + echo "Running markdownlint..." + npx --yes markdownlint-cli2 ${{ 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") + echo "static_issues=$ISSUES" >> $GITHUB_OUTPUT + echo "📋 Static issues found: $ISSUES" + else + echo "static_issues=0" >> $GITHUB_OUTPUT + echo "⚠️ npx not available, skipping static check" + fi + + - name: Decide if LLM review needed + id: decide + run: | + MINUTES=${{ steps.last-review.outputs.minutes_since_last || '999' }} + LINES=${{ steps.changes-size.outputs.lines_changed || '0' }} + STATIC_ISSUES=${{ steps.static-check.outputs.static_issues || '0' }} + + echo "⏱️ Minutes since last review: $MINUTES" + echo "📏 Lines changed: $LINES" + echo "🔍 Static issues: $STATIC_ISSUES" + + # Skip if reviewed <60 minutes ago + if [ "$MINUTES" -lt 60 ]; then + echo "should_run=false" >> $GITHUB_OUTPUT + echo "skip_reason=⏭️ Reviewed $MINUTES minutes ago. Wait at least 60 minutes between reviews." >> $GITHUB_OUTPUT + echo "⏭️ SKIPPING: Too soon since last review" + exit 0 + fi + + # Skip if <10 meaningful lines changed + if [ "$LINES" -lt 10 ]; then + echo "should_run=false" >> $GITHUB_OUTPUT + echo "skip_reason=⏭️ Only $LINES lines changed (minimum: 10). Changes too small for LLM review." >> $GITHUB_OUTPUT + echo "⏭️ SKIPPING: Changes too small" + exit 0 + fi + + # Skip if static analysis found issues (fix those first) + if [ "$STATIC_ISSUES" -gt 5 ]; then + echo "should_run=false" >> $GITHUB_OUTPUT + echo "skip_reason=⏭️ Found $STATIC_ISSUES formatting issues. Run \`npx markdownlint-cli2\` locally and fix those first." >> $GITHUB_OUTPUT + echo "⏭️ SKIPPING: Fix formatting issues first" + exit 0 + fi + + # Passed all gates + echo "should_run=true" >> $GITHUB_OUTPUT + echo "skip_reason=✅ Passed all pre-checks. Running LLM review." >> $GITHUB_OUTPUT + echo "✅ PROCEEDING: All gates passed" + + - name: Post skip message + if: steps.decide.outputs.should_run == 'false' + run: | + gh pr comment ${{ needs.setup.outputs.pr_number }} --body "${{ steps.decide.outputs.skip_reason }} + + **Why skip LLM review:** + - Saves ~50K tokens (~\$1.50) + - Saves ~0.15 kWh energy + - Avoids redundant processing + + **To proceed anyway:** Wait for cooldown period or accumulate more changes." + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + + # Editorial review using /editorial-review skill + editorial-review-skill: + needs: [setup, changes, smart-gate] + if: needs.smart-gate.outputs.should_run == 'true' + runs-on: ubuntu-latest steps: - name: Get PR head ref if: github.event_name == 'issue_comment' diff --git a/CLAUDE.md b/CLAUDE.md index 66deff9ab..f4546ee82 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,16 +61,21 @@ Don't run editorial review for: - ❌ File renames or moves only - ❌ Automated dependency updates -### When NOT to re-run review +### Automatic waste prevention -Don't trigger `/editorial-review` again if: -- ❌ You already ran it less than 1 hour ago (check PR timeline) -- ❌ You only fixed a single typo since the last review -- ❌ Only whitespace or formatting changed -- ❌ The same files were already reviewed in this PR with no content changes -- ❌ You're waiting for reviewer feedback (don't re-run speculatively) +The workflow has **built-in smart-gate automation** that automatically blocks wasteful runs: -**Tip:** Check the PR conversation timeline to see when the last review ran. Re-running unnecessarily wastes tokens and energy. +✅ **Automatically blocked:** +- Reviewed <60 minutes ago +- <10 meaningful lines changed +- >5 formatting issues found (fix with markdownlint first) + +❌ **Still avoid manually:** +- Re-running while waiting for feedback +- Running on PRs with only whitespace changes +- Running on dependency updates or file renames + +**The system protects you from accidental waste** - just comment `/editorial-review` and smart-gate decides if it's worth running. ### Token usage and costs @@ -93,12 +98,12 @@ This repository uses two main Claude-powered workflows: **Purpose:** On-demand quality checks for documentation content -**Components:** -- **Skill**: `/editorial-review` -- **Agents**: voice-tone, terminology, clarity (disabled), punctuation (planned) -- **Workflow**: `.github/workflows/docs-review.yml` -- **Scripts**: `classify-pr-type.sh` (PR classification), `post-inline-suggestions.sh` (GitHub API integration) -- **Triggers**: `/editorial-review` command (Claude Code or PR comment), manual workflow dispatch +**Architecture:** +- **Skill**: `/editorial-review` (orchestrates all agents) +- **Workflow**: `.github/workflows/docs-review.yml` (invokes skill) +- **Smart-gate**: Automatic filtering prevents wasteful runs +- **Scripts**: `classify-pr-type.sh`, `post-inline-suggestions.sh` +- **Triggers**: Manual only - `/editorial-review` comment or workflow dispatch ### API workflow @@ -115,19 +120,22 @@ This repository uses two main Claude-powered workflows: ### How it works -Use the `/editorial-review` command to run specialized agents on your documentation. This command works in two contexts: +The `/editorial-review` skill orchestrates specialized agents to review your documentation. The skill ensures consistent behavior whether run locally or in CI. **In Claude Code (local):** -1. Run the command in your terminal -2. Agents analyze files directly +1. Run `/editorial-review` in your terminal +2. Skill invokes appropriate agents (voice-tone, terminology, clarity) 3. Review findings in the conversation 4. Apply fixes to files manually **In GitHub PR (CI):** 1. Comment `/editorial-review` on any PR -2. Workflow triggers automatically -3. Agents analyze changed files -4. Results posted as inline PR suggestions +2. Workflow runs smart-gate checks (prevents waste): + - Skips if reviewed <60 min ago + - Skips if <10 lines changed + - Skips if formatting issues found (fix those first) +3. If gates pass: Invokes `/editorial-review` skill +4. Skill orchestrates agents and posts inline suggestions ### Usage @@ -152,11 +160,13 @@ Use the `/editorial-review` command to run specialized agents on your documentat /editorial-review ``` -The workflow will: -- Acknowledge the command immediately -- Run agents: voice-tone and terminology (clarity and punctuation not run in CI) +When gates pass, the workflow will: +- Invoke `/editorial-review` skill +- Skill runs agents: voice-tone, terminology (clarity disabled, punctuation not yet implemented) - Post up to 60 inline suggestions -- Provide downloadable artifact with full list +- Provide downloadable artifact if >60 suggestions found + +**Smart-gate blocks wasteful runs automatically** - you don't need to manually check timing/size. ### What gets reviewed From 6456e1fc552797e177cfdcaf28b3be3535c2a0da Mon Sep 17 00:00:00 2001 From: Justine Geffen Date: Wed, 18 Feb 2026 00:30:18 +0200 Subject: [PATCH 13/13] fix: correct agent availability and consolidate skip guidance Fixes inaccuracies in CLAUDE.md: 1. Local agents (line 29): - Was: "All agents (voice-tone, terminology, clarity, punctuation)" - Now: "voice-tone, terminology (clarity disabled, punctuation not yet implemented)" - Punctuation doesn't exist yet, clarity is disabled 2. CI agents (line 47): - Was: "voice-tone, terminology only (clarity and punctuation not run in CI)" - Now: "Skill orchestrates voice-tone and terminology agents" - Clearer and doesn't imply others run locally 3. Skip guidance (lines 55-78): - Was: Two overlapping sections ("Skip review when" + "Automatic waste prevention") - Now: Single "When to skip review" section with: - Automatic blocks (what smart-gate handles) - Manual judgment (when not to trigger) - Removes redundancy and clarifies what's automated vs manual Result: Documentation now accurately reflects what agents exist and how smart-gate automation works. --- CLAUDE.md | 38 +++++++++++++++----------------------- 1 file changed, 15 insertions(+), 23 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f4546ee82..728c80b20 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,7 +26,7 @@ Run `/editorial-review` in Claude Code when: **Environment:** Your local machine **Cost:** Your Claude API subscription -**Agents available:** All agents (voice-tone, terminology, clarity, punctuation) +**Agents available:** voice-tone, terminology (clarity disabled, punctuation not yet implemented) **Example:** ```bash @@ -44,7 +44,7 @@ Comment `/editorial-review` on a PR when: **Environment:** GitHub Actions CI **Cost:** Repository API budget -**Agents available:** voice-tone, terminology only (clarity and punctuation not run in CI) +**Agents:** Skill orchestrates voice-tone and terminology agents **Example:** ``` @@ -52,30 +52,22 @@ Comment `/editorial-review` on a PR when: /editorial-review ``` -### Skip review when +### When to skip review -Don't run editorial review for: -- ❌ Single typo fixes (not worth the tokens) -- ❌ PRs with only code changes (no documentation) -- ❌ Urgent hotfixes (speed over style) -- ❌ File renames or moves only -- ❌ Automated dependency updates - -### Automatic waste prevention - -The workflow has **built-in smart-gate automation** that automatically blocks wasteful runs: +**Automatic (smart-gate blocks these):** +- ✅ Reviewed <60 minutes ago +- ✅ <10 meaningful lines changed +- ✅ >5 formatting issues (fix with markdownlint first) -✅ **Automatically blocked:** -- Reviewed <60 minutes ago -- <10 meaningful lines changed -- >5 formatting issues found (fix with markdownlint first) - -❌ **Still avoid manually:** -- Re-running while waiting for feedback -- Running on PRs with only whitespace changes -- Running on dependency updates or file renames +**Use judgment (don't trigger manually):** +- ❌ Single typo fixes +- ❌ PRs with only code changes (no docs) +- ❌ Urgent hotfixes +- ❌ File renames or moves only +- ❌ Dependency updates +- ❌ Whitespace-only changes -**The system protects you from accidental waste** - just comment `/editorial-review` and smart-gate decides if it's worth running. +**How it works:** Comment `/editorial-review` and smart-gate automatically decides if it's worth running. You don't need to manually check timing or size. ### Token usage and costs