Feature/docs updater workflow#117
Open
csoceanu wants to merge 17 commits into
Open
Conversation
Add a new ACP workflow that analyzes code changes and discovers which documentation files need updating. Uses identifier matching and grep for discovery, with optional semantic indexing for large repos. Includes skills for discovery, generation, PR creation, and a controller for phase management. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Discovery: exclude auto-generated files (DO NOT EDIT markers, generator scripts) from candidates to reduce false positives. Generation: read source code for context when the diff alone is insufficient, flag for human review when behavior is unclear. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Use recursive find for hashing files in subdirectories - Split folders with 50+ files into sub-indexes (firm rule, not suggestion) - Support configurable output path for indexes - Use Agent tool explicitly for subagent dispatch (3+ folders) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Generation skill now explicitly shows the diff of each change in apply mode so users see what was modified without having to ask. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Controller: explain indexing trade-off upfront (takes time, only worth it if committed for reuse). Discovery: when indexes exist, use file summaries to narrow to specific files instead of reading all files or falling back to grep. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Strengthen controller instructions to require AskUserQuestion (not plain text) after setup. Add explanation of what indexing creates so users can make an informed choice. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add CRITICAL prefix and explicit instructions to read and follow the controller skill before doing anything else. Prevents Claude from improvising its own flow or using plain text instead of AskUserQuestion. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Indexing is only worth the cost on large repos (10+ doc folders). Update controller to explain the benefit clearly: faster future runs when indexes are committed, not just "takes time and tokens." Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add /index as a command so it shows up in ACP command picker and can be run independently - Remove index-build mode from discovery skill (now in the command) - Remove slash notation from controller phases — present as plain descriptive options in AskUserQuestion - Update all files for consistency Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Make the manifest schema explicit: must store individual file hashes, not just file counts. This enables incremental rebuilds — only folders with changed files get re-indexed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add /index to the startupPrompt so users know it exists. Explain benefits (faster, fewer tokens, conceptual matches) and note it's only recommended for large docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Change from "mention" to "include in the list" so /index appears as a bullet point alongside the other capabilities, not as a separate "About" section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Description no longer implies indexes are always used - Remove hardcoded format list (md/adoc/rst) — supports any text format - Generation skill uses "Review"/"Update" not slash notation - Troubleshooting no longer limits to specific file types Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove remaining slash notation from generation skill and README - Use "docs locations" instead of "repos" for consistency - Remove misplaced indexing advice from discovery skill Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Enterprise Run ID: 📒 Files selected for processing (4)
WalkthroughIntroduces a complete documentation automation workflow ("Docs Updater") with orchestration, discovery, generation, and PR-creation skills. Includes workflow specification, skill definitions, configuration, and supporting commands for discovering stale docs, updating them based on code changes, and creating pull requests. ChangesDocs Updater Workflow
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
workflows/docs-updater/.claude/commands/index.md (1)
6-53:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd required command sections (
Purpose,Prerequisites,Output).This command spec is missing required structural sections, and the output section should explicitly state artifact locations (for example
.doc-index/manifest.jsonand folder index files under.doc-index/).As per coding guidelines: “Command Markdown files must include: heading with command name and short description, Purpose section, Prerequisites section, Process section with numbered steps, and Output section specifying artifact locations”.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@workflows/docs-updater/.claude/commands/index.md` around lines 6 - 53, The command spec is missing required sections; add a Purpose section briefly describing what the command does, a Prerequisites section listing required context (e.g., repository access, target docs path, write permissions), and an Output section that explicitly states produced artifacts and locations (for example: .doc-index/manifest.json and per-folder index files under .doc-index/<folder>/...), while preserving the existing Process steps and ensuring the manifest format and per-file SHA256 requirement (.doc-index/manifest.json, "folders", and "doc_hashes") are mentioned in the Output description.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@workflows/docs-updater/.claude/commands/index.md`:
- Around line 37-51: The JSON fenced code block in the markdown (the
triple-backtick ```json ... ``` block) lacks blank lines before and after;
update the markdown in workflows/docs-updater/.claude/commands/index.md by
adding one blank line immediately before the opening ```json fence and one blank
line immediately after the closing ``` fence so the code block is separated from
surrounding text and satisfies Markdown linting rules.
- Around line 23-31: When .doc-index/manifest.json exists the incremental logic
only compares hashes for folders already listed and misses newly added doc
folders; after loading and comparing manifest entries (Step 2) run the same docs
scan used in Step 3 to collect current folders and add any folders not present
in manifest.json to the rebuild set so they are rebuilt, then proceed with
subfolder indexing (Step 4) and dispatching (Step 5); ensure the manifest
(manifest.json) is updated after rebuild to include the new folder entries and
their hashes.
In `@workflows/docs-updater/.claude/skills/discovery/SKILL.md`:
- Around line 74-76: The grep call inside the for loop (for id in "identifier1"
...) uses regex matching which misinterprets identifiers containing
metacharacters; update the grep invocation in that block (the line assigning
matches=$(grep -rl "$id" {docs_root} ... 2>/dev/null)) to use fixed-string
matching by adding -F (and add -w if you want to restrict to whole-word matches)
while preserving -r -l and the existing --include patterns and stderr
redirection.
In `@workflows/docs-updater/.claude/skills/generation/SKILL.md`:
- Around line 35-37: The decision gate text "Does the diff add something NEW
that should be documented?" and its NO_UPDATE_NEEDED branch is too narrow and
must be changed: update the gate logic (the decision label and any code that
references NO_UPDATE_NEEDED) to detect not only additive changes but also
removals, renames, and behavior/API changes that would make existing docs
incorrect; specifically, replace the check that only looks for added files/lines
with a broader predicate that flags deleted/renamed files, changed public APIs,
or behavioral changes referenced by docs, and ensure the downstream path that
currently skips updates (NO_UPDATE_NEEDED) only applies when the diff truly has
no impact on documentation accuracy.
In `@workflows/docs-updater/.claude/skills/pr/SKILL.md`:
- Around line 490-492: The PR body artifact path is hard-coded as
"docs/pr-description.md" which can resolve to the repo docs folder instead of
the workflow artifact directory; update all occurrences that reference the
literal "docs/pr-description.md" to construct the path from the workflow
artifact directory variable (e.g., artifactsDirectory or artifactDir) using a
normalized join (eg. path.join(artifactDir, 'pr-description.md') or
actions/core/normalizePath equivalent) so the code reads/writes the file inside
the workflow artifact directory; apply this change for every mention of
"docs/pr-description.md" (the instances called out and any others) and ensure
the code checks existence against the computed artifact path before appending.
- Around line 378-380: The fenced code block containing the text "refusing to
allow a GitHub App to create or update workflow `.github/workflows/foo.yml`
without `workflows` permission`" should be updated to include a language tag
(e.g., ```text or ```bash) and be surrounded by blank lines before and after the
fenced block; apply the same change to the other identical/unlabeled fenced
block later in the file (the one referenced at lines showing the same quoted
string) so both blocks conform to the markdown linting rules.
---
Outside diff comments:
In `@workflows/docs-updater/.claude/commands/index.md`:
- Around line 6-53: The command spec is missing required sections; add a Purpose
section briefly describing what the command does, a Prerequisites section
listing required context (e.g., repository access, target docs path, write
permissions), and an Output section that explicitly states produced artifacts
and locations (for example: .doc-index/manifest.json and per-folder index files
under .doc-index/<folder>/...), while preserving the existing Process steps and
ensuring the manifest format and per-file SHA256 requirement
(.doc-index/manifest.json, "folders", and "doc_hashes") are mentioned in the
Output description.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 7aff8f64-5cb0-4e9c-8b81-b0b29990591e
📒 Files selected for processing (8)
workflows/docs-updater/.ambient/ambient.jsonworkflows/docs-updater/.claude/commands/index.mdworkflows/docs-updater/.claude/skills/controller/SKILL.mdworkflows/docs-updater/.claude/skills/discovery/SKILL.mdworkflows/docs-updater/.claude/skills/generation/SKILL.mdworkflows/docs-updater/.claude/skills/pr/SKILL.mdworkflows/docs-updater/CLAUDE.mdworkflows/docs-updater/README.md
- index command: add Purpose/Prerequisites/Output sections, detect newly added folders not in manifest, fix blank lines around JSON block - discovery skill: use grep -rFl for fixed-string matching to avoid regex metacharacter issues - generation skill: broaden decision gate to cover removals, renames, and behavior changes (not just additions) - pr skill: add language tag to unlabeled code block Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
1 participant
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
Add a new workflow that analyzes code changes and discovers which documentation files need updating. It extracts identifiers from the diff, searches docs for matches, evaluates staleness through a two-pass review, generates minimal format-aware updates, and opens a docs PR.
/indexcommand builds semantic indexes for large docs locations so future runs are faster and use fewer tokensFiles
.ambient/ambient.json— workflow config.claude/skills/controller/SKILL.md— phase management (setup → review → update → PR).claude/skills/discovery/SKILL.md— identifier extraction, grep-based search, two-pass evaluation.claude/skills/generation/SKILL.md— format-aware content generation with decision logic.claude/skills/pr/SKILL.md— PR creation (copied from bugfix workflow).claude/commands/index.md— standalone command for building semantic indexesCLAUDE.md— behavioral guidelinesREADME.md— user documentationTesting
Load as a Custom Workflow in ACP:
https://github.com/csoceanu/workflows.gitfeature/docs-updater-workflowworkflows/docs-updater