docs(agent-coordination): spend model tokens on judgement, not on waiting - #2178
Conversation
…ting Agents working this repo pay per turn. Reserve turns for what only a model can do (review, diagnosis, acceptance criteria, deciding whether green is trustworthy) and hand waiting and mechanics to the platform. Concretely: allow_auto_merge is already enabled on this repo and was going unused, so every approved PR cost two extra wake-ups, one when it turned green and one to merge it. 'gh pr merge --auto --squash --delete-branch' removes both. The constraint matters as much as the technique: auto-merge triggers on GREEN, and this repo has merged a feature that passed 17 checks having never executed, and shipped a 10MB download cap that buffered the whole body first. Auto-merge replaces the waiting, never the reading. Also documents that the 'automerge' check reporting 'skipping' comes from dependabot-automerge.yml and is Dependabot-only, which reads like general auto-merge exists when it does not.
|
Warning Review limit reached
Next review available in: 12 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: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdded documentation guidance to reduce CI polling and repeated manual verification, favor targeted checks, stop on approval-blocked runs, and use auto-merge after review. ChangesTurn-spend guidance
Estimated code review effort: 1 (Trivial) | ~3 minutes Possibly related PRs
🚥 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 |
|
|
Contributor-facing half of the token-discipline guidance. Deliberately omits the auto-merge advice from docs/agent-coordination.md, because a fork contributor cannot merge; what they CAN act on is not burning turns on polling and repetition. Notes the real failure behind the watch advice: a malformed CI watch once exited early and reported success while shards were still pending, so the fix is to read the final status rather than trust that the command returned.
PR Summary by QodoDocs: Add token-discipline guidance and reviewed-only auto-merge workflow
AI Description
Diagram
High-Level Assessment
Files changed (1)
|
Code Review by Qodo
1. Workflow path ambiguous
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| (The `automerge` check reporting `skipping` on your PR comes from | ||
| `dependabot-automerge.yml` and applies to Dependabot only. It is not general | ||
| auto-merge.) |
There was a problem hiding this comment.
1. Workflow path ambiguous 🐞 Bug ⚙ Maintainability
The new section says the automerge check comes from dependabot-automerge.yml, but the actual workflow file lives under .github/workflows/; omitting the path makes it harder to find quickly. This is a minor docs clarity issue that can cause avoidable lookup time.
Agent Prompt
## Issue description
`docs/agent-coordination.md` references `dependabot-automerge.yml` without its repository path. In this repo the workflow lives at `.github/workflows/dependabot-automerge.yml`, so the current wording can send readers searching in the wrong place.
## Issue Context
The `automerge` check is produced by a GitHub Actions workflow named “Dependabot auto-merge” and a job named `automerge`, which is skipped for non-Dependabot PRs.
## Fix Focus Areas
- docs/agent-coordination.md[120-122]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
… default @taOS-website-dev tested the auto-merge advice on its own repo rather than assuming it transferred, and found it does not. Two preconditions were missing from the original text, and the second is a genuine footgun. 1. allow_auto_merge is a paid feature for private repos. On a repo where it is unavailable, PATCHing it returns 200 and silently does nothing, so the field must be re-read rather than the response trusted. 2. The one that bites: auto-merge waits for the gates a branch ACTUALLY has. With no branch protection there are no required checks, so a PR is mergeable the moment it opens and --auto degrades to 'merge now, ignore CI'. Measured across our repos: taOS dev has 4 required checks (the only reason it is safe there) while two sibling repos have no protection on dev at all. Without this, following the original advice on an unprotected branch would merge untested code instantly.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@docs/agent-coordination.md`:
- Line 107: Update the fenced code block in agent-coordination documentation to
declare the bash language using a bash fence, preserving the block’s existing
commands and content.
- Around line 92-102: Update the “Spend model tokens on judgement, not on
waiting” section to explicitly state that approval-blocked CI with an
action_required status must be surfaced to a human. Instruct agents not to
re-push, recreate the pull request, or poll again while waiting for approval,
preserving the existing distinction between judgement and platform-managed
waiting.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: e9825566-d894-4689-8408-31b7a89ca108
📒 Files selected for processing (2)
.claude/skills/taos-development-skill/SKILL.mddocs/agent-coordination.md
| ## Spend model tokens on judgement, not on waiting | ||
|
|
||
| An agent working this repo pays for every turn it takes. Reserve those turns for | ||
| work only a model can do, and hand the rest to the platform. | ||
|
|
||
| - **Judgement is worth a turn**: reviewing a diff, diagnosing a failure, writing | ||
| the acceptance criteria for a task, deciding whether a green check is | ||
| trustworthy. | ||
| - **Waiting and mechanics are not**: watching CI finish, merging a PR you have | ||
| already approved, polling for a state change, re-checking something you have | ||
| already verified. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Carry the explicit action_required stop rule into this guide.
Unlike .claude/skills/taos-development-skill/SKILL.md Lines 177-179 and 199-200, this section only gives general anti-polling advice. Add that approval-blocked CI should be surfaced to a human without re-pushing, recreating the PR, or polling again.
🤖 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 `@docs/agent-coordination.md` around lines 92 - 102, Update the “Spend model
tokens on judgement, not on waiting” section to explicitly state that
approval-blocked CI with an action_required status must be surfaced to a human.
Instruct agents not to re-push, recreate the pull request, or poll again while
waiting for approval, preserving the existing distinction between judgement and
platform-managed waiting.
| **Use auto-merge once you have reviewed.** Rather than waiting for checks and | ||
| coming back to merge, arm it and let GitHub finish the job: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Specify the fenced code block language.
Use ```bash instead of an unlanguaged fence so Markdown linting and syntax highlighting work correctly.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 107-107: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 `@docs/agent-coordination.md` at line 107, Update the fenced code block in
agent-coordination documentation to declare the bash language using a bash
fence, preserving the block’s existing commands and content.
Source: Linters/SAST tools
1 participant
Adds a token-discipline section to the agent coordination guide, so the practice reaches every agent and contributor working this repo rather than living only in my head.
The substance: reserve model turns for judgement (reviewing a diff, diagnosing a failure, writing acceptance criteria, deciding whether a green check is trustworthy) and hand waiting and mechanics to the platform.
The concrete win:
allow_auto_mergeis already enabled on this repo and was going unused. Every approved PR was costing two extra wake-ups, one when it turned green and one to merge it.gh pr merge <n> --auto --squash --delete-branchremoves both.The constraint, which matters as much: auto-merge triggers on green, and green is a claim rather than proof. This repo has merged a feature that passed every check having never once executed, and shipped a "10 MB" cap that buffered the entire body into memory first. So auto-merge replaces the waiting, never the reading, and should only be armed on a PR already reviewed.
Also documents a real trap: the
automergecheck that reportsskippingon human PRs comes fromdependabot-automerge.ymland fires for Dependabot only. It reads like general auto-merge exists when it does not.Docs-only change to an existing guide.
Summary by CodeRabbit