Skip to content

docs: Clarify on-demand trigger model and use sentence case #1113

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 1 commit into
base: master
Choose a base branch
from
Open

docs: Clarify on-demand trigger model and use sentence case #1113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
27 changes: 19 additions & 8 deletions .claude/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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 <file>` 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

Expand Down
4 changes: 2 additions & 2 deletions .github/scripts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ Converts Claude agent review findings into GitHub inline suggestions that can be
./post-inline-suggestions.sh <review-file> <pr-number>
```

### Input Format
### Input format

The script expects a review file with this format:

Expand Down Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ This guide covers documentation standards, editorial workflows, and Claude-power
- **Local review** → Use `/review <file-or-directory>` → 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:
Expand Down Expand Up @@ -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:

Expand Down