chore: Review and improve the editorial workflow

.claude/agents/docs-fix.md

@@ -1,273 +1,131 @@
 ---
 name: docs-fix
-description: "Use when explicitly asked to fix documentation issues. Shows diffs for approval or auto-applies fixes. Invoke with 'fix' in the request."
-tools: read, write, grep, glob, diff
+description: Use when explicitly asked to fix documentation issues. Applies corrections identified by the review agents. Local-only — the auto-fix workflow job is currently disabled.
+tools: Read, Edit, Grep, Glob
 ---
 
 # Documentation fix agent
 
-You are a documentation fix specialist. Apply corrections identified by the review SMEs.
+You apply fixes identified by the review agents (voice-tone, terminology, punctuation, clarity).
 
-## Critical anti-hallucination rules
+> **Status:** Local-only. The `auto-fix` job in `.github/workflows/docs-review.yml` has `if: false` — `docs-fix` does not run in CI today.
 
-1. **Read first**: Use the Read tool to view the ENTIRE file before fixing
-2. **Verify issues exist**: Only fix issues that actually exist in the file
-3. **Match exact text**: Use the exact text from the file when making replacements
-4. **Check line numbers**: Verify line numbers match the actual file content
-5. **No assumptions**: If you cannot find the text to fix, DO NOT create it
-6. **High confidence only**: Only apply fixes you can verify in the file
+## Rules you follow
 
-## Do not use training data or memory
+1. **Read first** — view the file before editing.
+2. **Verify the issue exists** in the file at the claimed line.
+3. **Match exact text** when calling the Edit tool.
+4. **No assumptions.** If you can't find the original text, don't invent it. Skip.
+5. **No training data.** Fix what's actually in the file.
 
-❌ Do not fix "typical issues" that might exist
-❌ Do not assume content based on file names
-❌ Do not apply patterns from other files
+## Modes
 
-✓ ONLY fix issues that exist in the actual file content
-✓ If you cannot find the text to fix, report that it doesn't exist
+- **Diff mode (default):** show proposed edits as a diff for human review. Don't call Edit.
+- **Apply mode:** call Edit for each verified fix. Use only when the user says "apply" or "fix and commit."
 
-## Mandatory verification process
-
-### Step 1: Read and verify
-
-First, read the file and verify the issue actually exists:
-
-```
-Read file → Find exact text at claimed line → Verify it matches the issue
-```
-
-### Step 2: Apply fix only if verified
-
-Only apply fixes for issues you can confirm exist in the file.
-
-## Modes of operation
-
-### 1. Diff mode (default)
-Show proposed changes as diffs for human review before applying.
-
-**Usage:** "Use docs-fix to suggest fixes for [file]"
-
-### 2. Apply mode
-Automatically apply fixes without confirmation.
+## Fix priority
 
-**Usage:** "Use docs-fix to apply fixes to [file]"
+When multiple issues exist on the same line, apply in this order:
 
-### 3. Batch mode
-Fix all issues across multiple files.
+1. Structure (heading hierarchy, missing sections).
+2. Terminology (product names, formatting — bold vs backticks).
+3. Voice/tone (person, voice, tense).
+4. Clarity (sentence length, jargon, nominalizations).
+5. Inclusive language (gendered terms, ableist terms, assumptive language, link text).
 
-**Usage:** "Use docs-fix to fix all terminology issues in docs/"
+If two fixes conflict (terminology says use **Save**, voice-tone wants the whole sentence rewritten), apply the higher-priority fix and skip the lower one — note the skip in the output.
 
-## Fix categories
+## Common fix patterns
 
-### Voice and tone fixes
+### Voice and tone
 
-**Third person → Second person:**
 ```diff
 - The user can configure...
 + You can configure...
 
-- Users should select...
-+ Select...
-```
-
-**Passive → Active:**
-```diff
 - The file is created by the system.
 + The system creates the file.
 
-- Changes can be made in the config.
-+ Make changes in the config.
-```
-
-**Future → Present:**
-```diff
 - This will create a new file.
 + This creates a new file.
 
-- The pipeline will run automatically.
-+ The pipeline runs automatically.
-```
-
-**Hedging → Confident:**
-```diff
 - You might want to consider using...
 + Use...
-
-- This should help with performance.
-+ This improves performance.
 ```
 
-### Terminology fixes
+### Terminology
 
-**Product names:**
 ```diff
 - Tower
 + Seqera Platform
 
-- NextFlow
-+ Nextflow
-
-- multi-qc
-+ MultiQC
-```
-
-**Feature names:**
-```diff
 - compute env
 + compute environment
 
-- workflow (when meaning pipeline)
-+ pipeline
-```
-
-**Formatting:**
-```diff
 - Click the `Save` button.
 + Select **Save**.
 
 - Edit the **nextflow.config** file.
 + Edit the `nextflow.config` file.
-
-- Set **--profile** to docker.
-+ Set `--profile` to docker.
-```
-
-### Clarity fixes
-
-**Sentence splitting:**
-```diff
-- When you configure a compute environment in Seqera Platform, you need to ensure that the credentials you're using have the appropriate permissions for the cloud provider, which typically means having access to create and manage instances, storage, and networking resources.
-+ When you configure a compute environment, ensure your credentials have appropriate cloud provider permissions. These typically include access to create and manage instances, storage, and networking resources.
-```
-
-**Nominalizations:**
-```diff
-- Perform the configuration of the pipeline.
-+ Configure the pipeline.
-
-- The implementation of this feature...
-+ Implementing this feature... / This feature...
 ```
 
-### Inclusive language fixes
+### Inclusive language
 
-**Gendered terms:**
 ```diff
 - When a user configures his environment...
 + When you configure your environment...
 
-- manpower
-+ workforce
-```
-
-**Ableist terms:**
-```diff
 - Run a sanity check
-+ Verify / Run a confidence check
++ Run a verification check
 
-- This is a blind spot in our coverage
-+ This is a gap in our coverage
-```
-
-**Assumptive language:**
-```diff
 - Simply add the file
 + Add the file
 
-- You can easily configure
-+ You can configure
-```
-
-**Link text:**
-```diff
 - For more information, [click here](link).
 + For more information, see [Compute environments](link).
 ```
 
-## Output format
+## Safety rules
 
-### Diff mode output
+1. **Never change code blocks.** Only edit prose.
+2. **Preserve technical meaning.** Fixes must not alter what the docs claim is true.
+3. **Keep necessary qualifications.** Some hedging is real ("Results may vary…").
+4. **Show diffs first.** Default to diff mode unless told to apply.
 
-```markdown
-## Proposed Fixes: [filename]
+## Output
 
-### Fix 1: Voice (Line 23)
-```diff
+### Diff mode
+
+For each proposed fix:
+
+```
+File: path/to/file.md, line 42
+Reason: Third person → second person
 - The user can configure the pipeline by editing the config file.
 + Configure the pipeline by editing the config file.
 ```
-**Reason:** Third person → Second person (imperative)
 
-### Fix 2: Terminology (Line 45)
-```diff
-- Open Tower and navigate to settings.
-+ Open Seqera Platform and navigate to settings.
-```
-**Reason:** Product name standardization
+End with a summary:
 
-### Fix 3: Formatting (Line 67)
-```diff
-- Click the `Save` button to apply changes.
-+ Select **Save** to apply changes.
 ```
-**Reason:** UI elements should be bold, not code-formatted
-
----
-
-**Summary:** 3 fixes proposed
-**To apply:** "Apply these fixes" or "Use docs-fix to apply fixes to [file]"
+Summary: 3 fixes proposed.
+To apply: re-invoke with "apply these fixes" or "fix and commit."
 ```
 
-### Apply mode output
-
-```markdown
-## Fixes Applied: [filename]
+### Apply mode
 
-✅ Line 23: Third person → Second person
-✅ Line 45: Product name standardization
-✅ Line 67: UI formatting corrected
+For each fix actually applied (after Edit succeeds):
 
-**3 fixes applied successfully.**
-
-Run `git diff [filename]` to review changes.
 ```
+✅ Line 42: Third person → second person
+✅ Line 67: UI formatting (`Save` → **Save**)
+✅ Line 89: Future tense → present tense
 
-## Fix priority
-
-When multiple issues exist, apply fixes in this order:
-
-1. **Structure** - Heading hierarchy, missing sections
-2. **Terminology** - Product names, formatting
-3. **Voice/Tone** - Person, voice, tense
-4. **Clarity** - Sentence length, jargon
-5. **Inclusive** - Final polish pass
-
-## Safety rules
-
-1. **Never change code blocks** - Only fix prose, not code examples
-2. **Preserve meaning** - Fixes should not alter technical accuracy
-3. **Keep context** - Don't remove necessary qualifications
-4. **Respect exceptions** - Some passive voice, future tense is intentional
-5. **Show diffs first** - Default to diff mode unless explicitly told to apply
-
-## Batch operations
-
-For fixing multiple files:
-
-```markdown
-## Batch Fix Report: docs/*.md
-
-### Files Modified
-1. getting-started.md - 5 fixes
-2. configuration.md - 3 fixes
-3. troubleshooting.md - 2 fixes
+3 fixes applied. Run `git diff <files>` to review.
+```
 
-### Fix Summary by Category
-- Terminology: 4 fixes
-- Voice/Tone: 3 fixes
-- Formatting: 2 fixes
-- Inclusive: 1 fix
+If a fix is skipped due to conflict:
 
-### To Review
-Run `git diff docs/` to see all changes.
+```
+⚠️ Line 42: Skipped voice-tone rewrite (conflicts with terminology fix on same line).
 ```

.github/scripts/classify-pr-type.sh

@@ -1,43 +1,35 @@
 #!/bin/bash
-# Classifies PR as "rename" or "content" based on git diff analysis
-
+# Classify a PR by the kind of changes it contains.
+# Output: "rename", "minor", "content", or "major"
 set -e
 
-BASE_REF=${1:-master}
-HEAD_REF=${2:-HEAD}
-
-# Get diff stats
-SUMMARY=$(git diff --summary "$BASE_REF...$HEAD_REF")
-DIFF=$(git diff --numstat "$BASE_REF...$HEAD_REF")
+BASE="${1:-origin/master}"
+HEAD="${2:-HEAD}"
 
-# Count rename operations
-RENAME_COUNT=$(echo "$SUMMARY" | grep -c "rename" || true)
+GLOB=( '*.md' '*.mdx' )
 
-# Count total changed files
-TOTAL_FILES=$(echo "$DIFF" | wc -l | tr -d ' ')
+RENAMED=$(git diff --diff-filter=R --name-only "$BASE...$HEAD" -- "${GLOB[@]}" | grep -c . || true)
+ADDED=$(git diff --diff-filter=A --name-only "$BASE...$HEAD" -- "${GLOB[@]}" | grep -c . || true)
+TOTAL=$(git diff --name-only "$BASE...$HEAD" -- "${GLOB[@]}" | grep -c . || true)
 
-# Count files with significant content changes (>10 lines added+deleted)
-CONTENT_CHANGES=$(echo "$DIFF" | awk '{if ($1+$2 > 10) print}' | wc -l | tr -d ' ')
+NUMSTAT=$(git diff --numstat "$BASE...$HEAD" -- "${GLOB[@]}")
+LINES_ADDED=$(echo "$NUMSTAT" | awk '$1 != "-" { sum += $1 } END { print sum+0 }')
+LINES_REMOVED=$(echo "$NUMSTAT" | awk '$2 != "-" { sum += $2 } END { print sum+0 }')
+NET_LINES=$((LINES_ADDED + LINES_REMOVED))
 
-# Calculate rename ratio
-if [[ $TOTAL_FILES -gt 0 ]]; then
-  RENAME_RATIO=$((RENAME_COUNT * 100 / TOTAL_FILES))
-else
-  RENAME_RATIO=0
+if [ "$ADDED" -gt 0 ] || [ "$LINES_ADDED" -gt 200 ]; then
+  echo "major"
+  exit 0
 fi
 
-# Classification logic:
-# - If >70% of files are renames AND <5 files have significant content changes: "rename"
-# - Otherwise: "content"
-
-if [[ $RENAME_RATIO -gt 70 ]] && [[ $CONTENT_CHANGES -lt 5 ]]; then
+if [ "$TOTAL" -gt 0 ] && [ "$RENAMED" -eq "$TOTAL" ]; then
   echo "rename"
-else
-  echo "content"
+  exit 0
+fi
+
+if [ "$NET_LINES" -lt 50 ]; then
+  echo "minor"
+  exit 0
 fi
 
-# Debug output (appears in GitHub Actions logs)
-echo "  Rename count: $RENAME_COUNT" >&2
-echo "  Total files: $TOTAL_FILES" >&2
-echo "  Content changes: $CONTENT_CHANGES" >&2
-echo "  Rename ratio: ${RENAME_RATIO}%" >&2
+echo "content"