Repository navigation
docs(design): Ask for a person's attention only for a next step - #3841
Merged
Merged
Conversation
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>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
dcramer
approved these changes
Nov 19, 2026
Contributor
|
401 screenshot changes — 0 changed · 401 added · 0 removed |
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>
dcramer
approved these changes
Nov 19, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdowns the principle, and every system follows it. It is listed first indesign/README.md, and its Gaps say where the product breaks it today.AGENTS.mdadds the hard rule and points to the design doc.TERMINOLOGY.mddefines 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]