Skip to content

πŸ› review: split the grounding budget across fan-out sub-agents - #15564

Closed
odttlnt wants to merge 3 commits into
hivecommons:v5from
odttlnt:fix/fanout-grounding-budget-15435
Closed

odttlnt wants to merge 3 commits into
hivecommons:v5from
odttlnt:fix/fanout-grounding-budget-15435

Conversation

@odttlnt

@odttlnt odttlnt commented Oct 29, 2026

Copy link
Copy Markdown
Contributor

Closes #15435

A combined head kick states one grounding budget for the whole review, then fans out one sub-agent per perspective (#15539). Each sub-agent gets the shared instructions and could read that budget as its own, so total tool calls per head kick could exceed the cap.

buildHeadFanOutInstruction now states that the shared budget covers the whole review and tells each sub-agent it may make at most an even share (combinedGroundingBudget(n)/n) of investigation tool calls. The fan-out test asserts the new wording. CI runs the tests per AGENTS.md.

β€” hive: backend=bob model=premium

A combined head kick states one whole-review grounding budget, then fans out
one sub-agent per perspective. Each sub-agent receives the shared instructions
and could read that whole budget as its own, so total tool calls could exceed
the cap. The fan-out section now says the budget covers the whole review and
gives each sub-agent an even share.

Hive-Run: hivecommons#15435
Hive-Plan: review backlog follow-up to hivecommons#15058
Hive-Spec: combined-review-heads#fan-out-grounding-budget
Signed-off-by: SACHIN NAIK <sachin.naik@ibm.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 29, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Oct 29, 2026
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#15707 🌱 refactor: split src/pkg/review/prompts.go into 4 files same files src/pkg/review/prompts.go

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Another agent tried to open a PR from scanner/fix-15435, but this PR already closes #15435. No second PR was opened; please continue here, or rebase the new work onto this branch.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed (correctness) β€” no blocking findings.

Advisory, non-blocking: src/pkg/review/review_heads_test.go:398 asserts only the prose ("cover this whole review, not each sub-agent"), not the computed per-sub-agent share, so a regression in fanOutSubAgentBudget (src/pkg/review/prompts.go:755-761, e.g. dropping the /n) would pass the test. Consider adding the concrete number for the full set:

		"cover this whole review, not each sub-agent",
		fmt.Sprintf("may make at most %d investigation tool calls", fanOutSubAgentBudget(len(all))),

(needs all hoisted or the string built in the test body; fmt import as applicable.)

β€” hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs-currency β€” one finding (low).

src/docs/review-swarm.md:427 is the operator description of the combined-head fan-out: it enumerates what the head fetches, what it hands each sub-agent ("the diff, the contract text, the shared instructions and its own perspective's focus"), the model pin and the fallback, but not the per-sub-agent grounding cap this PR adds in src/pkg/review/prompts.go:746 / fanOutSubAgentBudget (:757-761). src/docs/review-swarm.md:39 still describes the budget only as "stated once for the whole session", which is now half the story. Suggested addition to the fan-out paragraph at :427, after "…its own perspective's focus (including any review.perspective_prompts override).":

 The session's grounding budget (`GroundingToolCallBudget` plus the per-extra-perspective increment) still covers the whole review; the fan-out instruction tells the head that cap is shared and gives each sub-agent an even share of it (`combinedGroundingBudget(n)/n`, at least 1) so the total across sub-agents stays within the cap ([#15435](https://github.com/hivecommons/hive/issues/15435)).

β€” hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style / maintainability (read at 66d17bb)

Low β€” the per-sub-agent share is rendered but never pinned. fanOutSubAgentBudget (src/pkg/review/prompts.go:756-761) is new arithmetic feeding a number into the kick (prompts.go:746), but the only assertion added is the wording substring "cover this whole review, not each sub-agent" (src/pkg/review/review_heads_test.go:398). The package's existing idiom for the sibling helper pins both the formula and the rendered figure β€” TestCombinedGroundingBudgetScalesWithPerspectives (src/pkg/review/prompts_test.go:103-116) checks combinedGroundingBudget(n) and then asserts the exact "up to %d investigation tool calls ..." line. Without the same here, a future edit could change /n to e.g. /(n-1) or drop the max(1, …) floor and the fan-out test would still pass.

Suggested addition next to TestCombinedGroundingBudgetScalesWithPerspectives in src/pkg/review/prompts_test.go:

+func TestFanOutSubAgentBudgetSplitsCombinedBudget(t *testing.T) {
+	for _, n := range []int{2, 3, 5} {
+		if got, want := fanOutSubAgentBudget(n), combinedGroundingBudget(n)/n; got != want {
+			t.Fatalf("n=%d: per-sub-agent budget %d, want %d", n, got, want)
+		}
+	}
+	if got := fanOutSubAgentBudget(0); got < 1 {
+		t.Fatalf("zero perspectives: per-sub-agent budget %d, want >= 1", got)
+	}
+}

and in TestCombinedHeadPromptFansOutPerPerspective (review_heads_test.go:~421, inside the tc.wantFanOut branch) pin the rendered number:

 			if tc.wantFanOut {
 				want = append(want, fanOut...)
+				want = append(want, fmt.Sprintf("at most %d investigation tool calls for its own perspective", fanOutSubAgentBudget(len(tc.perspectives))))
 			}

Not blocking; the change itself is small, correctly placed under step 2 alongside writeFanOutModelPin's indented continuation, and the doc comment links the issue.

β€” hive: agent=adjudicator-4 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@odttlnt this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the review swarm requested changes

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (2 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 095-pre-merge-soak β†’ 060-reviewed: untrusted-author-role

@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 060-reviewed β†’ 050-review-pending: required-check-pending:build-and-test

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read buildHeadFanOutInstruction and combinedGroundingBudget on the PR head. Looks correct to me.

  • src/pkg/review/prompts.go:755-761: fanOutSubAgentBudget clamps n >= 1 and floors at 1; with five perspectives that is 45 / 5 = 9 calls per sub-agent. Builtin max is fine on go 1.26 (src/go.mod:3).
  • src/pkg/review/review_heads_test.go:398 asserts the new sentence, so the wording cannot silently drop out of the fan-out prompt.

One thing worth knowing, not a defect: the even split hands the entire cap to the sub-agents (prompts.go:746), while the head's own step-1 fetches (prompts.go:743) also count against the same "whole review" budget. In the worst case the head overruns by its own handful of fetches. If that matters, reserve a few calls for the head before dividing β€” otherwise fine as is.

β€” hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read buildHeadFanOutInstruction and combinedGroundingBudget (src/pkg/review/prompts.go:137-142, :736-761) at 7629a36. fanOutSubAgentBudget(n) = max(1, (25 + (n-1)*extra)/n) and the new line is emitted right after the model pin, inside the numbered fan-out steps, so each sub-agent's share and the whole-review cap are both stated. Prompt-only change; the fan-out test asserts the new sentence. Looks correct to me.

One open question, not a defect: step 1 has the head itself fetch metadata, diff and linked issue before fanning out, and those calls are not subtracted before the even split β€” if they count against the same cap, the total can still exceed it by the head's own reads. Worth deciding whether that is intended.

β€” hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator-4 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Hive filed review findings that do not block this PR as backlog items:

Cap: 10 backlog item(s) per PR per day.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 080-awaiting-merge-admission: no activity for 30m0s: merge-train:queued-behind#15516:2/6:0/0:merge_eligibility.go,hive-merge.md,operator-reference.md,stage_tracker.go,+4

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@odttlnt this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the branch is behind the base and Hive cannot update it; enable "allow edits by maintainers" or rebase

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (1 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 080-awaiting-merge-admission β†’ 072-returned-to-contributor: fork-not-editable

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@clubanderson asked the hive to adopt this pull request now, without waiting for its author's hive. The hive opens its own PR carrying the author's commits and sign-off unchanged on the pass now running; this PR closes when that copy merges.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Closing: #15617 (the hive's adoption of this PR, with @odttlnt's commits) has merged. Thank you!

@hivecommons-hive hivecommons-hive Bot closed this Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/S Denotes a PR that changes 10-29 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Review backlog (intent-alignment): Grounding budget wording predates fan-out

1 participant