Skip to content

📝 [v5 RFC] Reduce notification fatigue: actionable requests, cross-producer deduplication, and maintainer attention budgets #16075

Closed
5 of 5 issues completed

Description

@hanthor

Summary

Extend the shipped PR quiet mode into an end-to-end maintainer attention policy: routine progress stays in durable status; a notification interrupts a person only when there is a new, owned, actionable request. Deduplicate by the underlying condition, not by head SHA, producer, or agent cycle.

Discussion RFC, not implementation approval. Target v5. No changes to CI requirements, review authority, security holds, or merge protections. Please discuss the policy before decomposing it into implementation issues.

Problem and evidence

At the user's request, I sampled their GitHub notification inbox on 2026-10-31 using read-only API calls. The bounded sample contains 150 unique threads, last updated between 12:11:48Z and 16:46:31Z; 131 were unread. This is a recent-thread sample, not an exhaustive inbox audit, an arrival-rate measurement, or a count of delivered emails.

Notification reason Threads
review_requested 57
mention 40
subscribed 36
state_change 7
author 6
comment 4

Of 25 sampled threads in hivecommons/hive, 24 had reason mention, one review_requested. GitHub's thread reason does not identify the sender of every update or establish that its latest comment caused that reason. The counts motivate investigation; the public comment examples below establish concrete redundant/non-actionable writes. Inbox contents from other projects are deliberately omitted.

  1. Progress pings without a decision. RFC #15861 status update explicitly says no rollout/settings changed, but ends with an author mention “for visibility.” Its thread has 21 comments, 14 by the Hive App, created on October 31. Routine tracker progress should not repeatedly consume the author's attention.
  2. One failure, multiple reports. PR #16046's consolidated status coexists with two standalone Hive reports of the same ARM64 Antigravity-download HTTP/2 failure: first and second. These three reports disagree about whether the failed job was rerun or could be rerun. Consolidation needs a current action owner and recorded attempt state, not just less text.
  3. Several writers narrate one lifecycle. On [scanner] Prepare a disabled-by-default independent hivecommonsfleet broadcast of a public-safe hub activity view #15966: partial remainder, verified-open note, and Actions refs reminder separately explain why the same partial work leaves the issue open.
  4. Duplicate completion narration. 📝 RFC: Activity Monitor Matrix mode — ambient code rain of the lines hive is pushing #15862 has parent-autoclose explanation, then a second Actions comment mentioning the author. GitHub's close event already changes the thread state. Keep reopen/release guidance accessible without an unconditional second ping.
  5. Per-head informational security chatter. 🌱 ci: reduce PR critical path without dropping checks #16026 has standalone informational sentinel notices on one head and a later head. Evidence must remain visible, but an unchanged finding should not page again merely because SHA changed. A materially new security risk still warrants immediate attention.

These examples include agent prose, runtime comments, and repository workflows. They are not all governed by one existing sender. Review requests are also a major inbox category, but the sample alone does not prove they are inappropriate or all Hive-generated.

Existing work: preserve and complete it

#15875 was addressed by merged #15876, which introduced default github.notifications.mode: quiet, one edited hive:status comment for selected PR notes, no clean-perspective acknowledgement reviews, at most one Hive review per head, and mentions once per cause. Its PR body explicitly leaves issue-side notes out of scope.

This RFC extends that work; it is not a claim that quiet mode is missing. Also preserve the existing persistent Discord factory-feed event dedupe and bot/event filters documented in notifications.md. Those outbound webhook controls are distinct from comments and review requests that drive GitHub inbox/email notifications. #2752 already established that advisory digests should not mention humans.

Proposed policy

1. Separate durable status from attention events

Class Default delivery Human interruption
Claims, releases, decomposition, dependency progress, partial PR links, queued/pending CI, routine retries One bounded, edited status card per issue/PR; full history in audit/activity None
Real decision, permission/auth repair, exhausted automated recovery, required human review Current status card plus one explicit attention event Named responsible person, once per distinct unresolved condition
Material new security risk or imminent destructive action Immediate attention event with evidence Never hidden by a routine digest budget; same-incident duplicates still collapse
Merge/closure/recovery Update status and use native lifecycle signal where sufficient No extra “thanks”/“for visibility” ping by default; one resolution notice only when requested or necessary

Removing an @ alone is insufficient: creating a fresh comment can still notify subscribed users. Conversely, do not depend on editing an old comment to notify someone about a genuinely new action. Treat a new attention event as an intentional notification-capable write. GitHub controls actual delivery according to recipient settings; Hive cannot promise exact email semantics.

Status sections should show current truth, bounded in size, with stale requests explicitly resolved/superseded. Do not grow an infinite edited transcript or erase the separate audit history.

2. Use a durable condition identity

Proposed logical key: (repository, issue-or-PR, action class, responsible recipient, normalized condition); include destination for delivery bookkeeping. For example, a failed required unit job after three pushes is one unresolved condition, not three author requests. Preserve SHA/run IDs as evidence, not the default dedupe key.

An episode moves through observed → actionable → notified → acknowledged → resolved. A later genuine recurrence may notify again after recorded recovery; transient recovery/pending flaps do not reset the episode. A material risk/action/owner change can create a new event. Condition matching must distinguish unrelated failures rather than collapse every red check forever.

Persist this state across process restarts, rolling upgrades and multiple Hive instances. Use one authoritative writer or atomic admission per item/episode. Retry delivery without minting a new episode; reconcile after uncertain GitHub POST outcomes to avoid duplicate comments. State loss must not replay historical pings; reseed without sending routine history and expose uncertain active incidents for reconciliation.

3. Give every request an action contract

An attention event must contain:

  • Who: one responsible human/team, not every owner by default.
  • What changed / why now: the new condition, not the whole timeline.
  • Requested action: exact decision or supported command, with safe options and tradeoffs.
  • Evidence: current SHA/run/findings and a direct link to the relevant failure or decision.
  • What Hive tried: attempts and outcomes; whether recovery is running, unavailable, or exhausted.
  • What happens next: how the response is detected, who resumes work, and how to acknowledge, snooze, or resolve the request.

Example: “Author action required: approve or reject the native ARM runner trust change. Required CI is green; this is not a request to rerun tests. Evidence: …. Reply with your decision here; Hive retains the hold until an authorized decision is recorded.”

Do not page maintainers for work Hive itself can perform. Do not imply a rerun was completed unless there is execution evidence. A snooze suppresses reminders, not the underlying security/review hold. An ordinary acknowledgement is not approval.

4. Route review requests and reminders deliberately

Request a human review when it is actually needed and ready: required policy owner, unresolved judgment call, or human review explicitly requested by a contributor. Do not request every maintainer for routine agent progress. Preserve CODEOWNERS and mandatory independent/security review; avoid duplicate Hive requests where GitHub/Prow already owns that request. Do not repeatedly remove/re-add reviewers to manufacture reminders. New-head reviews can still be required without repinging the same person for the same unresolved ask.

Proposed starting defaults for discussion: no reminder while acknowledged or snoozed; no more than one reminder per unresolved condition in 24 hours; nonurgent outstanding requests can be summarized in one opt-in daily digest. Urgent security escalation follows its own explicit policy. Quiet hours and routing are preferences, never approval shortcuts.

5. Enforce at the write boundary, not only in prompts

Cover runtime producers, agent-written comments/reviews, and Hive-maintained Actions workflows. Extend/reuse the existing status/writeback path; do not build a parallel notification framework. Classify each existing write site as status, attention, required review, protocol command, or security event. Consolidate overlapping partial-work, closure, claim/release, sentinel and CI notes.

Suppress incidental mentions in copied titles, quotes, evidence, signatures and attribution. Mention admission must be explicit and recipient-authorized. Keep protocol commands such as /ok-to-test and required GitHub review submissions working; quiet mode must not silently discard machine-consumed writes. External bots such as Prow are separate producers: coordinate templates/configuration where possible and document what Hive cannot control rather than claiming a global mute.

Rollout and acceptance

  1. Inventory writers and instrument would notify decisions in shadow mode. Attribute by producer, cause and repository; do not collect private comment bodies or recipient inbox contents as telemetry.
  2. Pilot issue-side consolidation and agent/Actions write admission on one opted-in hive. Keep a visible action queue usable through GitHub links as well as dashboard/CLI; maintainers must not need to babysit another dashboard to discover work.
  3. Expand after comparing matched observation windows and per-active-item rates. Expose counters for new comments/reviews/review requests/mentions, suppressed repeats, delivery failures, acknowledgement time, and unresolved/missed action requests. Count API writes as proxies, not delivered emails.

Proposed success target: at least 80% fewer repeat/non-actionable Hive notification-capable writes per active item, without missing or delaying newly actionable human requests. This is a target, not a measured result. Report total volume and rates so reduced throughput cannot masquerade as success.

Acceptance scenarios must include: same failure across pushes; duplicate scanner/runtime/Actions reports; restart and concurrent writers; uncertain POST retry; new urgent finding; same-day recovery flapping versus genuine recurrence; newly required action arriving after the status card already exists; acknowledgement/snooze not releasing holds; mandatory review preserved; no stale asks after closure; and outbound mention-injection prevention. Verify notification behavior with consenting test accounts because GitHub delivery is platform-controlled.

Alternatives and discussion questions

  • Unsubscribe/mute the repo: quick personal relief, but hides real decisions and shifts the cost to maintainers. Not the product fix.
  • Only prompt agents to be quiet: useful guidance, not durable dedupe or cross-producer coordination.
  • Edit everything and never notify: avoids chatter but loses newly actionable requests.
  • Digest everything: appropriate for progress, unsafe for urgent decisions/security.

Questions: Should issue status reuse hive:status? Is 24h a suitable default reminder interval? Who owns cross-instance admission? Which lifecycle workflows should retire their redundant comments? How should operators inspect active attention requests without relying on a proprietary dashboard session?

Activity

  1. added
    kind/designCreated by Hive for agent-filed issue provenance
    proposalRFC / design proposal for discussion
    on Oct 31, 2026
  2. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Oct 31, 2026
  3. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    🔒 Claimed by @mrbobbytables (contributor on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 30m0s without activity and renews while the work continues. Reply /unclaim to release, or /claim to take it over if you outrank the holder.

  4. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    🔓 Claim by @mrbobbytables released (lease revoked).

  5. added
    stage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Oct 31, 2026
  6. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    Parking for a maintainer ruling — this RFC says it is a discussion RFC, not implementation approval, and asks for policy discussion before decomposition, so the hive will not start implementation or split it into child issues on its own.

    Risk: public-facing behaviour (every option changes which notification-capable writes reach humans) and governance (it sets a maintainer attention policy across producers).

    What to decide

    Reply with /hive decision A|B|C (or /hive approve for A). Until then this stays out of the work queue.

    — hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

  7. 46 remaining items

  8. github-actions commented on Nov 3, 2026

    @github-actions
    Contributor

    PR #16395 has merged (#16395) and referenced this issue with a non-closing Refs #16075 rather than a closing keyword.

    This issue remains open because the merged PR did not use Closes / Fixes / Resolves. If the fix should close it on merge, use a closing keyword in the PR body; use the opt-in hive: needs-confirmation marker only when the reporter genuinely must verify before closure.

  9. hivecommons-hive commented on Nov 3, 2026

    @hivecommons-hive
    Contributor

    PR #16426 covers this issue: #16426

    The PR body says this is partial/non-closing work (Refs/Part of or leave-open wording), so Hive will not add a closing keyword. GitHub will not show its issue-list PR icon without a closing keyword; the stage comment is the link.

  10. hivecommons-hive commented on Nov 3, 2026

    @hivecommons-hive
    Contributor

    All children delivered: #16263 → PR #16319, #16264 → PR #16321, #16267 → PR #16328, #16270, #16271 → PR #16426.

    Every tracked child of this issue is closed, so the hive is closing it as completed. Reopen it if something it asked for is still missing.

  11. github-actions commented on Nov 3, 2026

    @github-actions
    Contributor

    @hanthor this issue was closed by @hivecommons-hive[bot] as completed.

    If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.

    If you are still seeing the problem, comment /reopen and it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.

  12. clubanderson commented on Nov 16, 2026

    @clubanderson
    Member

    Phase 2 tracker: #18450. It has a fresh 39 h sample: the hive bot posts ~249 new comments/day, and scanner CI-triage re-posts, auto-merge notes and trusted-author sentinel notices are the biggest avoidable sources. The tracker breaks down every source, proposes children, and sets the target of under 100/day.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    approved-directionhelp wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.hive/partially-addressedA merged PR addressed only part of this issue; remainder still actionablehive/verified-openHive verified that a likely/already-done claim did not finish this issue; keep open for more workkind/designCreated by Hive for agent-filed issue provenanceproposalRFC / design proposal for discussion

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions