Skip to content

docs(design): Ask for a person's attention only for a next step - #3841

Merged
dcramer merged 4 commits into
mainfrom
docs/notification-rule
Nov 20, 2026
Merged

dcramer merged 4 commits into
mainfrom
docs/notification-rule

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

This adds a core principle for how the agent works. A person's attention is the scarcest thing Junior spends. Junior asks for it only to give an answer, a result, or a step that only that person can take. It never asks a person to do or approve the obviously right thing; it does it. It asks only when it cannot act for a technical reason or when the choice is truly the person's. The principle covers anything that takes attention: the agent's own replies and questions, Slack posts and DMs, Review items, review requests, push, and Inbox counts. Work that Junior owns, such as merge conflicts, goes to the agent and tells nobody.

  • design/attention.md owns the principle, and every system follows it. It is listed first in design/README.md, and its Gaps say where the product breaks it today.
  • AGENTS.md adds the hard rule and points to the design doc.
  • TERMINOLOGY.md defines Attention, used instead of "notification", and Notice.
  • design/review-desk.md: a notice names a step for the person. Status and work that Junior owns are never items. The repeated lines are removed.
  • design/github.md: a re-review waits for the required checks to pass, and "Ready to merge" is listed as an item, because a person merges. The re-review before checks pass is recorded as a Gap.
  • design/automations.md: the creator hears about a failure only when they have a step to take. The Inbox count for failed runs with no step is recorded as a Gap.

This PR holds the principle only. Code that closes the gaps is in separate PRs: #3843 (system prompt and steering text), #3837 (merge conflict guidance), and #3709 (when fixes stop).

via @dcramer.

--

View Session [Sentry]

Add design/notifications.md, which owns when Junior interrupts a person
across Slack, the review desk, the Inbox, and plugins. Link it from
AGENTS.md and design/review-desk.md. Record where the product breaks it
today as gaps.

Co-Authored-By: David Cramer <23610+dcramer@users.noreply.github.com>
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
junior-docs Ready Ready Preview Nov 19, 2026 11:46pm UTC

Request Review

@dcramer
dcramer marked this pull request as ready for review November 19, 2026 23:18
@sentry-junior
sentry-junior Bot requested a review from dcramer November 19, 2026 23:18
@github-actions github-actions Bot added the risk: high PR risk score: high label Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

401 screenshot changes — 0 changed · 401 added · 0 removed

Review screenshots in Frameshift

Junior does the obvious next step itself and asks only when it cannot act
for a technical reason, or when the choice is truly the person's.

Co-Authored-By: David Cramer <23610+dcramer@users.noreply.github.com>
Define Notification and Notice in TERMINOLOGY.md. Point AGENTS.md at the
design doc, and restore the meaning of two shortened Reference lines.
Remove lines that repeat another design file. Fix review-desk, github, and
automations text that contradicted the rule, and move each product gap to
the system that owns it.

Co-Authored-By: David Cramer <23610+dcramer@users.noreply.github.com>
Rename design/notifications.md to design/attention.md. The rule covers
anything that takes a person's attention, including the agent's own
replies and questions, not only notification channels. List it first in
the design index, and define Attention in TERMINOLOGY.md.

Co-Authored-By: David Cramer <23610+dcramer@users.noreply.github.com>
@sentry-junior sentry-junior Bot changed the title docs(design): Notify a person only when they have a next step docs(design): Ask for a person's attention only for a next step Nov 19, 2026
@dcramer
dcramer enabled auto-merge (squash) November 19, 2026 23:48
@dcramer
dcramer merged commit 15b7bd6 into main Nov 20, 2026
77 of 79 checks passed
@dcramer
dcramer deleted the docs/notification-rule branch November 20, 2026 00:04

This branch was successfully deployed

1 active deployment
Preview – junior-docs — fe8355d3 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: high PR risk score: high

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant