Recommendations v2 (PR 5a): three noisy rules deleted, the rest cite their rows by peyton-alt · Pull Request #2391 · entireio/cli

peyton-alt · 2026-09-12T02:14:07Z

https://entire.io/gh/entireio/cli/trails/1317

Task 1–4 of docs/superpowers/plans/2026-09-11-pr5-recommendations-v2.md.

This PR: +616/-222. Cumulative across the stack (PR1+PR2+this vs main): +63158/-13182.

What changed

entire checkpoint tokens on a real 286.3M-token checkpoint printed seven recommendations, two of which said the same thing and none of which named a number a reader could find. It now prints two:

Token usage
Total:  286.3M tokens
  Input: 110.2k | Cache read: 269.4M | Cache write: 16M | Output: 824.2k | API calls: 509 | Per call: 562.6k

How it was billed
  ...
  Of the total, subagents used        29.1M      10%

Recommendations
- 509 API calls at about 562.6k each, of which 269.4M was replayed cached context.
  Batch the next diagnosis: each further call replays the context again.
- Subagents used 29.1M of 286.3M tokens (10%). Give each a narrower objective and expected output.

Every figure traces to a row above it.

Why these rules

Measured over 135 distinct committed checkpoints (a sweep of three clones, rule conditions re-derived from source and cross-checked against the IDs the binary emitted):

rule	fired on
`context-replay-hotspot`	91%	deleted
`output-pressure`	39%	deleted
`cache-write-pressure`	31%	deleted
`summarize-before-boundary`	30%	deleted (needs the hotspot)

A rule firing on most sessions describes the baseline. The spec says so for the first: cache read is the largest class in ~90% of checkpoints (96% here), and no threshold rescues it — at a 97% share it still fires on 62%.

Checkpoints printing nothing: 0% → 75%. Printing three or more: 35% → 0%.

The spec's own figures for the two rules it names are 64%/65% over 4,442 checkpoints; this corpus gives 39%/31%. Different corpus, same conclusion — cite the measured number, not mine, if you re-run it.

Deliberate decisions a reviewer should check

cacheReadHotspot survives as a qualifier, not a recommendation. It still selects the API-call message's replay wording.
The agent brief's replay arm now keys on usage, not the deleted rule. On the ~61% of checkpoints where replay dominates but the call count doesn't, deleting the rule would otherwise have silently changed an agent's next action to "no high-signal risk detected". Pinned by TestAgentBriefSurvivesRuleDeletion.
The cap is at the render layer, never on report.Recommendations — the brief picks its action and builds its signals from that slice. --json keeps the full list.
A high-severity line is never trimmed. The limit applies only below the last high one.
tokens profile is untouched (passes no limit). Its rules count recurrence across checkpoints, it aggregates many agents, and one of its rules always prints. Its own api-call-amplification signal still fires at ≥20 where these now use ≥40 — that divergence is PR 6's, and is called out in the code.
Rule IDs are typed constants. hasTokenRecommendation matches by string, so a deletion compiles clean and stale references go silently false.

Behaviour changes worth disagreeing with

A 50k session with 6k cache write and 4 API calls used to be told "use at most 3 batched reads and avoid broad new context". It now says nothing. That advice came from a rule firing on 31% of real checkpoints.
TestSessionTokens_SubagentFigureAppearsOnlyOnce counted occurrences of "ubagents" and carried a "do not fix this" comment. Its premise — that the advice line says "subagent" singular — expired here: a recommendation citing a row necessarily repeats its number. It now counts the row itself, so the double-count it guarded is still caught.

Two mistakes caught by running the command, not the suite

The message first divided cache read by the call count. That reads as replay-per-call and appears in no row — the usage line's Per call is total over calls. The test asserted the wrong number and passed. It now asserts that figure is absent.
"each extra call costs another full replay" cited an average to describe the marginal call, which is larger in a growing session.

Not in this PR

Recalibrating the surviving thresholds and the unpriced-report fallback (plan Decisions 5, 6). The corpus is 124 Claude Code, 10 Codex, 1 Pi and zero Gemini or OpenCode — the agents the spec says differ most. Doing per-agent gating on that data would be guessing.
Add-to-memory — spec Open Decision 3 ("print-the-line or Entire writes it") is unconfirmed.
tokens profile — dated conflict resolved in the spec on 2026-09-11: it belongs to PR 6.

Stack

main → tokens (#2155) → pr1-token-class-breakdown (#2210) → pr2-session-tokens-block (#2269) → this. Retarget to main once the stack lands. Spec Rule 4 (off main, not stacked) is deviated from because this edits the same functions #2210 and #2269 rewrote.

🤖 Generated with Claude Code

Note

Medium Risk
Changes user-visible CLI guidance and agent-brief next actions for session/checkpoint token reports; logic is well-tested but alters when optimization advice appears (many sessions now print nothing).

Overview
Token recommendations v2 trims noise from session tokens and checkpoint tokens while making the advice that remains traceable to printed numbers.

Rules removed as baseline noise (e.g. context-replay-hotspot on ~91% of checkpoints): context-replay-hotspot, cache-write-pressure, output-pressure, and summarize-before-boundary. cacheReadHotspot stays as a non-printed qualifier for API-call wording and agent-brief logic so deleting a line does not silently change next actions.

Surviving messages cite rows above them: API-call advice uses call count, Per call (new on the usage line), and cache-read total; subagent-heavy quotes token totals and share via the same formatters as the billed block. sessionTokenRecommendationSignals unifies rule input for both commands and passes Classes. Recommendation IDs are named constants (recNoTokenData, etc.).

Display shows at most two recommendations (severity-sorted; all high kept), only in text rendering—report.Recommendations, --json, and the agent brief still see the full set. tokens profile keeps unlimited recommendations and a separate profileSignalReplayHotspot id.

Tests lock in cap behavior, citation invariants, brief behavior after rule deletion, and removed rules staying gone.

^{Reviewed by Cursor Bugbot for commit 3592887. Configure here.}

… baseline `checkpoint tokens` and `session tokens` printed up to seven recommendations, none of which named a number a reader could find in a row above it. Measured over 135 distinct committed checkpoints (a sweep of three clones with a PR 2 build, rule conditions re-derived from source and cross-checked against the IDs the binary emitted): context-replay-hotspot 91% output-pressure 39% cache-write-pressure 31% summarize-before-boundary 30% A rule that fires on most sessions describes the baseline, not a finding. The spec's own calibration says so for the first: cache read is the largest class in ~90% of checkpoints (96% here), so it can never be a finding on its own, and no threshold rescues it — at a 97% share it still fires on 62%. Deleted context-replay-hotspot, cache-write-pressure, output-pressure, and summarize-before-boundary (its condition requires the hotspot). Checkpoints printing nothing go from 0% to 75%; none now prints three or more. Two things deliberately kept: - cacheReadHotspot survives as a qualifier, not a recommendation. It still selects the API-call message's replay wording, which asserts replay and needs it to be true. - The agent brief's replay arm now keys on usage instead of the deleted recommendation. The brief returns exactly one next action and always returned something there; on the ~61% of checkpoints where replay dominates but the call count does not, deleting the rule would otherwise have silently changed an agent's instruction to "no high-signal risk detected". Rule IDs are now typed constants. hasTokenRecommendation matches by string, so a stale reference compiles clean and goes permanently false — this makes the next deletion a build failure. tokens_profile.go keeps its own same-spelled signal id under a file-local constant: it counts recurrence across checkpoints through independent machinery and is not this rule. Its api-call signal still fires at >= 20 where the shared rules use >= 40; that divergence is PR 6's. Tests: three deleted outright (their whole subject was a deleted rule); one retargeted at cacheReadHotspot, because the invariant it pinned outlives the rule — the share must be measured against the top-level total, not one inflated by nested subagent tokens; five updated for the two removed signal lines. Added TestAgentBriefSurvivesRuleDeletion, which pins both brief consequences above, and TestRecommendationRules_NoiseRulesAreGone. One behaviour change worth review: a 50k session with 6k cache write and 4 API calls used to be told "use at most 3 batched reads and avoid broad new context". It now says nothing. That advice came from a rule firing on 31% of real checkpoints; silence is the fix, and it is asserted rather than left to a golden diff. Task 1 of docs/superpowers/plans/2026-09-11-pr5-recommendations-v2.md. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Entire-Checkpoint: 01M29K2HHJ32213W4P69206NEB

Task 1 removed the rules that fired on most sessions. This bounds what is left, so the list stays short when future rules are added or thresholds move. The cap is applied in the renderer, never to report.Recommendations. agentBriefOptimizationAction picks the agent's next action from that slice and agentBriefSignals builds its diagnostic list from it, so truncating the slice would shorten what an agent is told as a side effect of a display decision. --json keeps the full list for the same reason: it is the machine-readable surface, not the one being decluttered. Both are asserted. A high-severity recommendation is never trimmed. The limit applies only to what follows the last high one, so three serious findings all print even though the limit is two — capping by position alone would let two medium lines hide a high one on the day three fire at once. The limit is a parameter rather than a constant inside the renderer, because all three token commands share it. `checkpoint tokens` and `session tokens` pass two; `tokens profile` passes no limit, deliberately: its rules count recurrence across many checkpoints rather than describing one session, and revisiting them belongs to PR 6. Capping it here would have changed a deferred command's output as a side effect. Ordering is by severity, stable within a severity, with unknown severities sorting last so a typo demotes a line instead of promoting it. Ranking by the magnitude of the number cited waits for Task 4, which is what puts those numbers on the struct. Severity strings reuse the package's existing trailReviewSeverity* constants rather than re-spelling the literals. Task 2 of docs/superpowers/plans/2026-09-11-pr5-recommendations-v2.md. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Entire-Checkpoint: 01M29KE8Q34NA59WM48DT4H4Y0

…ust cite A recommendation is only actionable if every number it quotes appears in a row above it. The rules could not do that: tokenRecommendationSignals carried Tokens, Context and two counts, and nothing else — PR 1's billing-class breakdown was unreachable from inside recommendationRules. Adds Classes to the signals. The breakdown was already built before both call sites, so this is a field and a wiring change with no behaviour of its own; the rules that quote it land in the next commit. Classes also answers the capability question a rule must ask before firing, and answers it on the right axis: Priced says whether cost shares mean anything at all, and a class's CostZero says the provider bills none of it. Both are properties of the model's price family rather than of the agent, which matters because an agent running a non-native model would otherwise be judged by its vendor's price sheet. Both commands now build their rule input through one constructor, sessionTokenRecommendationSignals. `session tokens` and `checkpoint tokens` previously wrote separate struct literals, which is how one of them could quietly stop passing a field and stop citing rows on that command alone. The guard test greps both files to assert neither bypasses the constructor. Task 3 of docs/superpowers/plans/2026-09-11-pr5-recommendations-v2.md. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Entire-Checkpoint: 01M29NQCJ550HRVB5MCEMEZDVC

…ve it Before: "Large context was replayed across 509 API calls; batch the next diagnosis and reduce iterative tool calls." and "Scope subagent tasks tightly; give each subagent a narrow objective and expected output." Neither names a number a reader can find. After, on a real 286.3M-token checkpoint: Token usage Total: 286.3M tokens Input: 110.2k | Cache read: 269.4M | ... | API calls: 509 | Per call: 562.6k ... Of the total, subagents used 29.1M 10% Recommendations - 509 API calls at about 562.6k each, of which 269.4M was replayed cached context. Batch the next diagnosis: each further call replays the context again. - Subagents used 29.1M of 286.3M tokens (10%). Give each a narrower objective and expected output. Every figure traces to a row directly above it. Adds "Per call" to the usage line. The API-call recommendation cites it, and a cited number has to be visible; it is also the figure that distinguishes a session worth batching from a chatty one, which the raw call count does not. Omitted when no calls were recorded rather than dividing by zero. Two mistakes worth recording, both found by running the command rather than by the suite: - The message first divided cache read by the call count. That reads as the replay cost per call and appears in NO row: the usage line's Per call is the whole total over calls. The test asserted the wrong number and passed. It now asserts the opposite — that the per-call replay figure is absent. - "each extra call costs another full replay" cited an average to make a claim about the marginal call, which is larger in any growing session. The sentence now says only that a further call replays the context again. The subagent share comes from the row's own formatter (formatSharePercent over roundedPercent), not a recomputation: the classes block prints an int percent with a "<1%" case, so a float recomputation renders "87.6%" beneath a row saying "88%". TestSessionTokens_SubagentFigureAppearsOnlyOnce counted occurrences of "ubagents" to count the figure's row, on the premise that the advice line said "subagent" singular, and carried a comment warning against "fixing" it. That premise expired here: a recommendation that cites a row necessarily repeats its number, and repeating it is the point. It now counts the row itself, so the double-count it was written for is still caught while the intentional citation is not. Task 4 of docs/superpowers/plans/2026-09-11-pr5-recommendations-v2.md. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Entire-Checkpoint: 01M29P3ZWTM89TQABAM50GSAFD

Copilot

🟡 Changes recommended

Unresolved threshold, citation, and subagent-share issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates token recommendations to remove noisy rules, cite displayed metrics, and cap human-readable output while preserving profile behavior.

Changes:

Removes four low-signal recommendation rules.
Adds shared signals, named IDs, citation checks, and a two-item display cap.
Keeps tokens profile recommendations uncapped and updates tests.

File summaries

File	Review findings
`cmd/entire/cli/session_tokens.go`	Moderate issues remain with subagent-share gating, the shared API-call threshold, recommendation citation ordering, and use of the `no-token-data` constant.
`cmd/entire/cli/tokens_profile.go`	The documented `>=40` shared threshold is not implemented; the shared threshold remains 20.
`cmd/entire/cli/sessions_test.go`	Recommendation behavior and citation coverage reviewed.
`cmd/entire/cli/session_tokens_classes_test.go`	Subagent rendering assertions reviewed.
`cmd/entire/cli/checkpoint_tokens.go`	Checkpoint recommendation integration reviewed.

Review details

Suppressed comments (1)

cmd/entire/cli/tokens_profile.go:59

This new comment says the shared recommendation threshold is now >=40, but recommendationHighAPICalls is still 20 and recommendationRules uses it for both session tokens and checkpoint tokens. As a result, 20–39-call reports still emit the recommendation, contrary to the PR's stated threshold split from tokens profile. Update the shared threshold and its tests, or correct this claimed behavior.

// someone who sees a matching string. `tokens profile`'s thresholds (its
// api-call signal still fires at >= 20, where the shared rules now use >= 40)
// are PR 6's to revisit.
const profileSignalReplayHotspot = "context-replay-hotspot"

Files reviewed: 5/5 changed files
Comments generated: 4
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

-		}
-	}
+	hotspot := cacheReadHotspot(signals.Tokens)
 	if signals.Tokens != nil && signals.Tokens.APICalls >= recommendationHighAPICalls {


 	if signals.Tokens != nil && tokenShareAtLeastOneTenth(signals.Tokens.SubagentTotal, signals.Tokens.Total) {
 		recs = append(recs, sessionTokensRecommendation{
-			ID:       "subagent-heavy",
-			Severity: "medium",
-			Message:  "Scope subagent tasks tightly; give each subagent a narrow objective and expected output.",
-			Signals:  []string{"subagent_tokens"},
-		})
-	}
-	if signals.Tokens != nil && signals.Tokens.Total > 0 &&
-		tokenClassPressure(signals.Tokens.CacheWrite, signals.Tokens.Total, 5000, 10, 50_000) {
-		recs = append(recs, sessionTokensRecommendation{
-			ID:       "cache-write-pressure",
-			Severity: "medium",
-			Message:  "Cache write is elevated; avoid broad new context and narrow the next read before continuing.",
-			Signals:  []string{"cache_write_tokens"},
-		})
-	}
-	if signals.Tokens != nil && signals.Tokens.Total > 0 &&
-		tokenClassPressure(signals.Tokens.Output, signals.Tokens.Total, 3000, 2, 10_000) {
-		recs = append(recs, sessionTokensRecommendation{
-			ID:       "output-pressure",
-			Severity: "medium",
-			Message:  "Output tokens are elevated; keep the next answer tight and avoid restating evidence.",
-			Signals:  []string{"output_tokens"},
+			ID:       recSubagentHeavy,
+			Severity: trailReviewSeverityMedium,
+			Message: fmt.Sprintf(
+				"Subagents used %s of %s tokens (%s). Give each a narrower objective and expected output.",
+				formatTokenCount(signals.Tokens.SubagentTotal),
+				formatTokenCount(signals.Tokens.Total),
+				// The row's own share, through the row's own formatter, so the
+				// two strings match rather than merely agreeing to a rounding.
+				formatSharePercent(signals.Tokens.SubagentTotal,
+					roundedPercent(signals.Tokens.SubagentTotal, signals.Tokens.Total)),
+			),


+			ID:       recHighContextPressure,
 			Severity: "medium",
 			Message:  fmt.Sprintf("Context pressure is %d%% of the window; preserve only relevant context before continuing.", signals.Context.Percent),


+	if hasTokenRecommendation(report, recLongSession) {
 		signals = append(signals, "Session has crossed a long-session or checkpoint boundary.")
 	}
 	if hasTokenRecommendation(report, "no-token-data") {


An Entire Gates finding caught a raw "no-token-data" left at session_tokens.go:724 after the rest were converted to constants. That is exactly the bug the constants exist to prevent — hasTokenRecommendation matches by string, so a missed site compiles clean and goes silently false — so the finding is fair and the miss is worth recording rather than quietly patching. Also finishes tokens_profile.go, where one of its three own signal ids had been named and two had not. These stay separate from the recommendation constants deliberately: they are that command's own cross-checkpoint signals that happen to share a spelling, not the same rules. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Entire-Checkpoint: 01M29Q422GM1FHWK5FH95ZSWSB

peyton-alt and others added 4 commits September 11, 2026 18:17

Copilot AI lite review requested due to automatic review settings September 12, 2026 02:14

peyton-alt requested a review from a team as a code owner September 12, 2026 02:14

Copilot started reviewing on behalf of peyton-alt September 12, 2026 02:14 View session

Copilot AI reviewed Sep 12, 2026

View reviewed changes

peyton-alt added this pull request to stack #2392 September 12, 2026 02:36

Navigation Menu

Uh oh!

Recommendations v2 (PR 5a): three noisy rules deleted, the rest cite their rows - #2391

Recommendations v2 (PR 5a): three noisy rules deleted, the rest cite their rows#2391
peyton-alt wants to merge 5 commits into
pr2-session-tokens-blockfrom
pr5a-recommendations-v2

peyton-alt commented Sep 12, 2026 •

edited by entire Bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

peyton-alt commented Sep 12, 2026 • edited by entire Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Why these rules

Deliberate decisions a reviewer should check

Behaviour changes worth disagreeing with

Two mistakes caught by running the command, not the suite

Not in this PR

Stack

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Suppressed comments (1)

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

peyton-alt commented Sep 12, 2026 •

edited by entire Bot

Loading