docs: Clarify on-demand trigger model and use sentence case#1113
Open
justinegeffen wants to merge 16 commits intomasterfrom
Open
docs: Clarify on-demand trigger model and use sentence case#1113justinegeffen wants to merge 16 commits intomasterfrom
justinegeffen wants to merge 16 commits intomasterfrom
Conversation
- 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 <noreply@anthropic.com>
✅ Deploy Preview for seqera-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates repository documentation to accurately describe the editorial review system as explicitly triggered (on-demand) rather than automatic, and aligns headings to sentence case for consistency.
Changes:
- Clarifies that
/editorial-reviewruns only when explicitly invoked (local command, PR comment, or manual workflow dispatch) and is not triggered by PR events/commits. - Improves contributor guidance by separating local pre-PR steps from PR-based review steps.
- Normalizes heading capitalization in documentation READMEs.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
CLAUDE.md |
Adds an on-demand-only callout and updates a heading to sentence case. |
.claude/README.md |
Corrects trigger semantics (removes “automatic” PR triggers) and clarifies local vs PR workflows. |
.github/scripts/README.md |
Converts headings to sentence case for consistency. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
justinegeffen
added
1. Dev/PM/SME
gavinelder
approved these changes
Feb 16, 2026
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.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Justine Geffen <justinegeffen@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Justine Geffen <justinegeffen@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Justine Geffen <justinegeffen@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Justine Geffen <justinegeffen@users.noreply.github.com>
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.
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)
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.
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.
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.
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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes incorrect documentation claims about "automatic" triggers and clarifies that the editorial review system is on-demand only.
Changes
.claude/README.mdCLAUDE.md.github/scripts/README.mdWhy this matters
Previously, the documentation incorrectly stated that agents "automatically review changes" when PRs are opened. This caused confusion about:
The updated documentation makes it crystal clear:
/editorial-reviewcommand (local or PR comment)Related
Builds on #1110 (anti-hallucination improvements) which was already merged to master.