refactor: simplify pulse.md — 622 to 127 lines, trust intelligence over deterministic rules#2465
Conversation
…e over deterministic rules The pulse was getting stuck for 8+ hours because 622 lines of deterministic guidance (recursive blocker-chain validation, AI-powered stuck detection with confidence thresholds, CodeRabbit orchestration, strategic review dispatch) created too many paths for the agent to get lost in. Replaced with 127 lines of clear intent that trusts the agent's judgment: - Removed: Step 2c (advisory stuck detection with milestone helpers) - Removed: Step 7b (90 lines of CodeRabbit daily review orchestration) - Removed: Step 8 (strategic review dispatch) - Removed: recursive blocker-chain validation (replaced with 'check if blocked-by refs are resolved') - Removed: duplicate OPEN-state checks - Removed: verbose bash code blocks the agent copies verbatim - Added: 5-minute time budget to prevent runaway pulses - Added: 'How to Think' section emphasizing judgment over rules - Kept: circuit breaker, worker counting, dispatch mechanics, hard safety rules The key insight: an intelligent agent that dispatches 3 workers in 60 seconds beats a script-following agent that does perfect analysis for 8 hours and dispatches nothing.
WalkthroughThis change restructures the pulse agent's behavioral policy in Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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 |
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Fri Feb 27 14:09:33 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
Adds back PR triage (fix failing CI, flag stale/duplicate PRs, detect worker failures), auto-unblocking resolved issues, task decomposition guidance, and label lifecycle awareness. Each as a one-line judgment call, not 30-80 lines of bash.
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request addresses a critical issue where the supervisor pulse was frequently getting stuck due to an overly complex and deterministic guidance script. The changes drastically simplify the Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Fri Feb 27 14:11:20 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
|
![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 significantly reduces the size of pulse.md by replacing deterministic rules with intelligent judgment, adding a time budget, and focusing on speed over thoroughness. The review ensures the new instructions are clear, actionable, and maintain necessary safety checks, with an emphasis on providing critical context and examples for important operational rules.
| For each dispatchable issue: | ||
| 1. Skip if a worker is already running for it (check `ps` output for the issue number) | ||
| 2. Skip if an open PR already exists for it (check PR list) | ||
| 3. Read the issue body briefly — if it has `blocked-by:` references, check if those are resolved (merged PR exists). If not, skip it. |
There was a problem hiding this comment.
It's crucial to ensure that the brief description includes the URL to the issue. This is important for traceability and context when workers pick up the task. Suppressing stderr with 2>/dev/null can hide important diagnostic information about malformed files or write failures; avoid doing this, per general rules.
References
- When reporting errors for failed file operations in shell scripts, such as 'jq' writes, include the file path in the error message. Avoid suppressing stderr with '2>/dev/null' to ensure that diagnostic information about malformed files or write failures is visible.
| ~/.aidevops/agents/scripts/circuit-breaker-helper.sh record-success # or record-failure | ||
|
|
There was a problem hiding this comment.
The instruction to check the issue state before modification is a critical safety rule. Failing to do so could lead to agents working on stale or invalid issues, wasting resources and potentially causing conflicts. Consider adding a code example to illustrate how to implement this check, as was done in the previous version of this document, to ensure the agent adheres to this rule and understands its importance.
References
- When documenting critical rules like worktree ownership, include a warning about the consequences of violating the rule (e.g., 'removing them destroys another agent's working directory mid-work').
| Run the session miner pulse. It has its own 20-hour interval guard, so this is a no-op on most pulses: | ||
|
|
||
| ```bash | ||
| # Session miner (has its own 20h interval guard — usually a no-op) |
There was a problem hiding this comment.
The instruction to verify the issue state with gh issue view is crucial for preventing dispatching to closed issues. Violating this rule could result in agents attempting to work on already resolved or invalid tasks, leading to wasted effort and incorrect reporting. Consider adding a code example to illustrate how to implement this check, as was done in the previous version of this document, to ensure the agent adheres to this rule and understands its importance.
References
- When documenting critical rules like worktree ownership, include a warning about the consequences of violating the rule (e.g., 'removing them destroys another agent's working directory mid-work').
| You are the supervisor pulse. You run every 2 minutes via launchd — **there is no human at the terminal.** | ||
|
|
||
| **AUTONOMOUS EXECUTION REQUIRED:** You MUST execute every step including dispatching workers. NEVER present a summary and stop. NEVER ask "what would you like to action/do/work on?" — there is nobody to answer. Your output is a log of actions you ALREADY TOOK (past tense), not a menu of options. If you finish without having run `opencode run` or `gh pr merge` commands, you have failed. | ||
| **AUTONOMOUS EXECUTION REQUIRED:** You MUST execute actions. NEVER present a summary and stop. NEVER ask "what would you like to do?" — there is nobody to answer. Your output is a log of actions you ALREADY TOOK (past tense). If you finish without having run `opencode run` or `gh pr merge` commands, you have failed. |
There was a problem hiding this comment.
The phrase "You MUST execute actions" is somewhat vague. Consider rephrasing to provide more specific guidance on what constitutes 'executing actions'.
| 5. Smaller/simpler tasks over large ones (faster throughput) | ||
| 6. Oldest issues | ||
|
|
||
| 1. **Read the issue body** with `gh issue view <number> --repo <owner/repo> --json body,title` to find the blocker reason. Look for patterns like `blocked-by: tXXX`, `**Blocked by:** tXXX`, `depends on #NNN`, or `blocked-by:tXXX` in the body text. | ||
| **Label lifecycle** (for your awareness — workers manage their own transitions): `available` → `queued` (you dispatch) → `in-progress` (worker starts) → `in-review` (PR opened) → `done` (PR merged) | ||
|
|
There was a problem hiding this comment.
The commit message includes [skip ci]. Ensure this is intentional and doesn't bypass necessary CI checks. If CI is required, remove [skip ci].
![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
🧹 Nitpick comments (1)
.agents/scripts/commands/pulse.md (1)
120-122: Make circuit-breaker recording deterministic.“record-success # or record-failure” is ambiguous for headless automation. Define an explicit rule (e.g., failure on unhandled command errors; success on clean completion) so breaker metrics are trustworthy.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/scripts/commands/pulse.md around lines 120 - 122, Clarify and codify deterministic rules for the circuit-breaker helper: update the documentation entry that references ~/.aidevops/agents/scripts/circuit-breaker-helper.sh record-success / record-failure to state that the CI/automation should call record-failure when the preceding command exits non‑zero or throws an unhandled error, and call record-success only when the preceding command exits zero (clean completion); update the circuit-breaker-helper.sh command handlers (record-success and record-failure) to enforce and return proper exit codes (0 for success, non‑zero for failure) and to provide a clear, parseable status message on stdout/stderr so automation can deterministically decide which command to invoke; reference the script name and the record-success / record-failure command names in the docs so callers implement the rule.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/scripts/commands/pulse.md:
- Around line 9-10: Update the completion criteria in pulse.md so a pulse is not
marked "failed" solely because it didn't run the literal commands `opencode run`
or `gh pr merge`; instead, change the rule at the lines mentioning those
commands (the clause around "opencode run" / "gh pr merge") to require failure
only when there were dispatchable/mergeable actions available but no command was
executed. Concretely, rewrite the wording at the existing criteria (the sentence
containing `opencode run` and `gh pr merge` and the related lines 36-37) to
allow a successful/valid pulse when there was no dispatch capacity or nothing
mergeable, and add an explicit condition that a pulse is considered failed only
if actionable tasks existed and no execution commands were issued.
- Around line 111-115: The current commit block hides failures by redirecting
stderr and swallowing errors with `2>/dev/null || true` around the `git -C
"$path" add/commit/push` sequence; change it to surface and handle errors:
remove the `2>/dev/null || true` suppression, capture git command exit codes
(the `git -C "$path" diff --quiet TODO.md` and subsequent `git -C "$path" add
TODO.md && git -C "$path" commit ... && git -C "$path" push` pipeline), log any
stdout/stderr output on failure, and fail the script (non-zero exit) or
explicitly record the failure so CI/automation notices the sync did not complete
rather than silently continuing.
---
Nitpick comments:
In @.agents/scripts/commands/pulse.md:
- Around line 120-122: Clarify and codify deterministic rules for the
circuit-breaker helper: update the documentation entry that references
~/.aidevops/agents/scripts/circuit-breaker-helper.sh record-success /
record-failure to state that the CI/automation should call record-failure when
the preceding command exits non‑zero or throws an unhandled error, and call
record-success only when the preceding command exits zero (clean completion);
update the circuit-breaker-helper.sh command handlers (record-success and
record-failure) to enforce and return proper exit codes (0 for success, non‑zero
for failure) and to provide a clear, parseable status message on stdout/stderr
so automation can deterministically decide which command to invoke; reference
the script name and the record-success / record-failure command names in the
docs so callers implement the rule.
| **AUTONOMOUS EXECUTION REQUIRED:** You MUST execute actions. NEVER present a summary and stop. NEVER ask "what would you like to do?" — there is nobody to answer. Your output is a log of actions you ALREADY TOOK (past tense). If you finish without having run `opencode run` or `gh pr merge` commands, you have failed. | ||
|
|
There was a problem hiding this comment.
Conflicting completion criteria can force false failures.
Line 9 says a pulse “failed” unless it ran opencode run or gh pr merge, but Line 36 explicitly allows a valid cycle with no dispatch capacity and possibly nothing mergeable. This can misclassify healthy pulses as failures and destabilize breaker behavior.
Suggested policy fix
-**AUTONOMOUS EXECUTION REQUIRED:** You MUST execute actions. NEVER present a summary and stop. NEVER ask "what would you like to do?" — there is nobody to answer. Your output is a log of actions you ALREADY TOOK (past tense). If you finish without having run `opencode run` or `gh pr merge` commands, you have failed.
+**AUTONOMOUS EXECUTION REQUIRED:** You MUST execute actions. NEVER present a summary and stop. NEVER ask "what would you like to do?" — there is nobody to answer. Your output is a log of actions you ALREADY TOOK (past tense). If no safe dispatch or merge was available after checks, record a no-op pulse with reasons and exit successfully.Also applies to: 36-37
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/scripts/commands/pulse.md around lines 9 - 10, Update the completion
criteria in pulse.md so a pulse is not marked "failed" solely because it didn't
run the literal commands `opencode run` or `gh pr merge`; instead, change the
rule at the lines mentioning those commands (the clause around "opencode run" /
"gh pr merge") to require failure only when there were dispatchable/mergeable
actions available but no command was executed. Concretely, rewrite the wording
at the existing criteria (the sentence containing `opencode run` and `gh pr
merge` and the related lines 36-37) to allow a successful/valid pulse when there
was no dispatch capacity or nothing mergeable, and add an explicit condition
that a pulse is considered failed only if actionable tasks existed and no
execution commands were issued.
| # Commit any ref changes | ||
| git -C "$path" diff --quiet TODO.md 2>/dev/null || { | ||
| git -C "$path" add TODO.md && git -C "$path" commit -m "chore: sync GitHub issue refs to TODO.md [skip ci]" && git -C "$path" push | ||
| } 2>/dev/null || true | ||
| ``` |
There was a problem hiding this comment.
TODO sync git automation hides failures and risks silent drift.
This block suppresses commit/push errors (2>/dev/null || true), so sync failures become invisible and state can silently diverge. For unattended DevOps loops, this hurts reliability and incident triage.
Suggested hardening
-(cd "$path" && ~/.aidevops/agents/scripts/issue-sync-helper.sh push --repo "$slug" 2>&1) || true
-# Commit any ref changes
-git -C "$path" diff --quiet TODO.md 2>/dev/null || {
- git -C "$path" add TODO.md && git -C "$path" commit -m "chore: sync GitHub issue refs to TODO.md [skip ci]" && git -C "$path" push
-} 2>/dev/null || true
+(cd "$path" && ~/.aidevops/agents/scripts/issue-sync-helper.sh push --repo "$slug" 2>&1) || {
+ echo "TODO sync failed for $slug"
+}
+# Commit any ref changes (report failures)
+if ! git -C "$path" diff --quiet TODO.md 2>/dev/null; then
+ git -C "$path" add TODO.md &&
+ git -C "$path" commit -m "chore: sync GitHub issue refs to TODO.md [skip ci]" &&
+ git -C "$path" push ||
+ echo "TODO.md commit/push failed for $slug"
+fi🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/scripts/commands/pulse.md around lines 111 - 115, The current commit
block hides failures by redirecting stderr and swallowing errors with
`2>/dev/null || true` around the `git -C "$path" add/commit/push` sequence;
change it to surface and handle errors: remove the `2>/dev/null || true`
suppression, capture git command exit codes (the `git -C "$path" diff --quiet
TODO.md` and subsequent `git -C "$path" add TODO.md && git -C "$path" commit ...
&& git -C "$path" push` pipeline), log any stdout/stderr output on failure, and
fail the script (non-zero exit) or explicitly record the failure so
CI/automation notices the sync did not complete rather than silently continuing.
1 participant
Summary
Problem
The pulse supervisor was consistently getting stuck for 8+ hours, never reaching the dispatch step. Root cause: 622 lines of deterministic guidance created too many analysis paths for the agent to get lost in — recursive blocker-chain validation, AI-powered stuck detection with confidence thresholds, CodeRabbit orchestration, strategic review dispatch, duplicate state checks.
Meanwhile, 3 webapp issues sat idle with
status:availablefor 12+ hours because the pulse never reached Step 4 (dispatch).Evidence
When a human looked at the same issues, the fix took 30 seconds:
The pulse couldn't do this because it was stuck executing 500 lines of analysis before it was allowed to dispatch.
What was removed
What was kept
opencode runsyntax, backgrounding, sleep between dispatches)What was added
Design philosophy
This is the "Intelligence Over Scripts" principle applied to the pulse itself. The framework replaced 37,000 lines of fragile bash with intelligence-guided agents — but pulse.md had grown back into exactly the kind of deterministic scaffolding it was supposed to replace.
Summary by CodeRabbit