docs(readme-refresh): fix README taxonomy — rename agent sections, dedup PR-review, ground tagline - #1274
Conversation
…dup PR-review, ground tagline The generated .github-private README had four taxonomy smells the section naming couldn't justify: - "Agents" vs "Agentic Workflows" read as the same thing. They are actually two mechanisms: interactive @mention profiles (agents/*.md) vs autonomous GitHub Actions. Rename to "@-Mention Agents" and "Automated Workflows" so the heading states the mechanism. - dev-lead landed under workflows only because it has no @mention profile, while pr-reviewer appeared in BOTH sections — exposing that the split is really "has-a-profile / has-a-workflow / both". Rule 6 now says: describe a dual-surface capability once per section with a cross-reference, not twice. - The stand-alone "PR Review Automation" section was legacy prose that redundantly re-described pr-review-trigger.yml (already an Automated Workflows row). Rule 6 now forbids that spotlight section and folds the detail into the row. - The tagline claimed "Claude Code skills" with nothing in the facts bundle feeding skills — a rule-3 (never-invent) violation. Rule 3 now explicitly covers the tagline/capability-types and bans the unsupported "skills" claim. Prompt-template change only (prompts/ is lint-excluded); takes effect on the next weekly refresh, which will rewrite the four meta READMEs accordingly. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T8R1YNuBzojLtKbX7azp9m
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 55 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe README refresh prompt now prohibits unsupported capability claims and distinguishes interactive ChangesREADME refresh prompt
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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 |
Dev-Lead — waiting on PR blockers (intent: review-changes)PR: #1274 |
|
Note @don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically. |
There was a problem hiding this comment.
Pull request overview
Updates the README refresh generator prompt to fix taxonomy and grounding issues in the generated .github-private and org profile READMEs, so future refreshes consistently produce non-duplicative, mechanism-named sections and avoid unsupported capability claims.
Changes:
- Expands the “Never invent” rule to cover the opening tagline and explicitly forbids claiming “skills”/“Claude Code skills” absent supporting facts.
- Replaces the “Agentic Workflows” rule with a clearer “two agent surfaces” rule that renames sections by mechanism and prevents duplicated/spotlighted PR review content.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the LLM prompt instructions in prompts/aw/readme-refresh.md to prevent the invention of unauthorized capability types (like 'Claude Code skills') and to clarify the documentation of interactive '@-Mention Agents' versus autonomous 'Automated Workflows'. The review comments provide valuable suggestions to prevent LLM ambiguity: first, by clarifying that allowed artifact types can come from either the repository or the facts bundle, and second, by explicitly instructing the LLM to describe cross-referenced capabilities in both sections rather than using the potentially confusing phrase 'once per section'.
…and per-section duplication - Rule 3: the allowed artifact list (prompts, scripts) isn't enumerated in the facts bundle, so "types the facts actually contain" was self-contradictory. Reword to "actually present in the repository or facts bundle" (Gemini medium). - Rule 6: "describe it once per section" could be read as "once overall". Make it "in both sections (once in each)" to remove LLM ambiguity (Gemini low). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T8R1YNuBzojLtKbX7azp9m
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@prompts/aw/readme-refresh.md`:
- Around line 62-65: Update the README-refresh guidance for the “Automated
Workflows” section to describe these as autonomous GitHub Actions workflows,
using only each workflow’s discovered filename and marker description. Remove
the blanket Claude/Copilot attribution, and mention either provider only when
explicitly supported by the facts.
🪄 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: Pro
Run ID: 51c55020-10db-4647-84bf-ab10dc62ebda
📒 Files selected for processing (1)
prompts/aw/readme-refresh.md
Auto-dismissed (#617): coderabbitai[bot] CHANGES_REQUESTED on a superseded commit. The bot re-reviews the new head automatically — a valid concern will return as a fresh review.
Dev-Lead — fix-bot-comment (no-changes)Agent reasoning |
…ts don't identify CodeRabbit (major): the discovery emits each workflow's filename and marker description but not its engine, so calling them "Claude/Copilot agents" in rule 6 invites the exact attribute-beyond-facts error this PR closes. Reword to "autonomous GitHub Actions workflows" and add an explicit instruction not to name a provider unless the facts state it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T8R1YNuBzojLtKbX7azp9m
|
donpetry-bot
left a comment
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: 91f830d3b37b07da5d518365f28fa1fe42d7975b
Review mode: triage-approved (single reviewer)
Summary
Docs-only change to the readme-refresh generator prompt (prompts/aw/readme-refresh.md, +23/-7, 1 file). Extends never-invent rule 3 to cover the tagline/capability types (bans ungrounded 'skills' claim) and rewrites rule 6 to name the two agent surfaces by mechanism ('@-Mention Agents' vs 'Automated Workflows'), require cross-references instead of duplication, and forbid the redundant stand-alone 'PR Review Automation' section. Triage assessment (low-risk) confirmed. All CI green; both gemini review threads resolved by follow-up commit 91f830d.
Linked issue analysis
No linked issues. The PR is a self-contained follow-up to the README Refresh work; the body documents four concrete taxonomy problems observed in the rendered README and maps each to a specific rule change in the generator prompt. The diff matches the stated scope exactly.
Findings
- No security-relevant changes: single markdown prompt file, no scripts, workflows, auth, or secrets touched.
- Secret scanning MCP tool not available in this environment (noted, non-blocking); gitleaks CI check passed.
- Prompt-injection review of the added prompt text: instructions are constraining (never-invent, dedup, naming), not privilege-expanding — no concerns.
- One unresolved (outdated) CodeRabbit thread objects to the 'Claude/Copilot agents' phrasing in rule 6. Non-blocking: that attribution is carried over verbatim from the pre-existing text, the CodeRabbit review itself was dismissed, and rules 3 and 7 already bind README content strictly to the facts bundle, so no ungrounded provider attribution can reach the generated README rows.
- Both gemini-code-assist threads were addressed and resolved by commit 91f830d ('address review — clarify facts-vs-repo wording').
CI status
All substantive checks SUCCESS: Lint, ShellCheck, CodeQL (actions, python), Secret scan (gitleaks), SonarCloud, agent-shield, Agent Security Scan, holdout-guard, guard, unit-tests, Compile agentic workflows, CodeRabbit. Cancelled entries are superseded dev-lead/dismiss automation runs; dependency-audit jobs skipped (no matching ecosystems); the in-progress 'review / review' check is this review run itself.
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
Dev-Lead — waiting on PR blockers (intent: review-changes)PR: #1274 |
|
Note @don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically. |
What & why
Follow-up to the README Refresh work. Reviewing the rendered
.github-privateREADME surfaced fourtaxonomy problems where the section naming couldn't justify itself. This fixes them in the
generator prompt (not the README directly) so they hold on every future refresh.
@mentionprofiles inagents/*.md) and "Automated Workflows" (autonomous GitHub Actions) — headings now state the mechanismpr-reviewerappears in both sectionspr-review-trigger.yml(already an Automated Workflows row)Changes
prompts/aw/readme-refresh.mdonly:the ungrounded "skills"/"Claude Code skills" claim.
don't duplicate": renames both sections, requires cross-reference (not duplication) for
dual-surface capabilities, and forbids the stand-alone "PR Review Automation" spotlight.
Scope & validation
prompts/**is excluded from markdownlint (see.markdownlint-cli2.jsonc), so no lint impact; longest touched line is 106 chars anyway.workflow_dispatch), which will rewritethe four meta READMEs with the corrected section names and no redundant/hallucinated content.
🤖 Generated with Claude Code
https://claude.ai/code/session_01T8R1YNuBzojLtKbX7azp9m
Summary by CodeRabbit