Skip to content

docs(rfc): propose waiting-on-you cards that pin an agent's ask above the composer - #39294

Open
unstablebrainiac wants to merge 1 commit into
kirodotdev:mainfrom
unstablebrainiac:docs/rfc-waiting-on-you-cards
Open

unstablebrainiac wants to merge 1 commit into
kirodotdev:mainfrom
unstablebrainiac:docs/rfc-waiting-on-you-cards

Conversation

@unstablebrainiac

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Propose, as an RFC for a maintainer to accept, a card that an agent pins above the composer to say what it needs from the person, kept there until the person answers it or writes, the agent clears it, or it expires.

When an agent is blocked on the person, only the turn that first said so explains the ask. In a watch loop, every later cycle adds another "still waiting on you" reply on top of it, so the person scrolls back through the chat to find what is needed. Chips from [OPTIONS:] come only from the newest reply, so a blocked loop must restate them every cycle to keep them on screen.

Why it matters

Loops that wait on a person for hours or days produce one visible reply per cycle that says nothing new, and the actual ask scrolls out of view. Non-loop chats lose the ask too, as soon as the person asks a side question. #20961 asks for the same "waiting on you" signal for a plain-text ask.

Not a goal

  • Building anything. This PR adds a design document and its index row; the implementation follows in later PRs once a maintainer accepts it.
  • Changing ask_question, native question cards, [OPTIONS:] chips or needs_input.
  • Channel surfaces (Slack, Discord, Webex).

What changed (motivation → approach → change)

A new RFC, docs/request-for-change/rfc-waiting-on-you-cards.md, with status draft, and its row in docs/request-for-change/README.md.

Part What the RFC proposes
Agent tool waiting_on_you pins one ask (a key, a title, optional detail, 0 to 6 options); waiting_on_you_clear removes it. At most 4 per session.
Card Pinned in the composer band, labelled "Action for you" in its own colour so it is never mistaken for a live "Waiting on you" question.
Lifetime It ends when the owner answers it or writes in the chat, the agent clears it, or 7 days pass. Loop cycles, crons, other sessions and teammates do not end it.
Storage A MAC'd gateway store, like change_cards.json, so it survives restarts and lazy tab restore. The transcript gets a display-only card row.
Answer Only the label or text the owner chose is sent; the agent's text never enters a user row. Each answer is checked against the current ask_id and the stored options, and is idempotent.
Sidebar "Action for you · title", plus a waiting kind in the needs-me card for answering and dismissing from the sidebar.

It amends one line of the 2026-09-13 [OPTIONS:] decision, the one that tells a blocked loop to restate its options, and it asks a maintainer for that ruling explicitly. Independent reviews by Opus 5.5 and GPT 5.6 Sol ran over five rounds; their findings are folded in.

Backwards compatibility

Compatible: the PR adds documentation only.

Removes nothing: no code, key or document is changed apart from one added index row.

Tests

Proof: not provable -- docs or config only

Manual verification

N/A -- docs only. Every code citation in the RFC was checked against 640338acb1 by the author and by two reviewers.

Real-machine verification

N/A -- the diff adds Markdown documents; nothing in it runs.

Related Issues

Part of #20961

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Nov 18, 2026
@unstablebrainiac
unstablebrainiac force-pushed the docs/rfc-waiting-on-you-cards branch from 986354e to 701cae1 Compare November 18, 2026 22:17
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision 8f6432fb1ed17c96c24ee501bea00b3e70b34aab ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 8f6432fb1ed17c96c24ee501bea00b3e70b34aab touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 8f6432fb1ed17c96c24ee501bea00b3e70b34aab via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: this PR only adds a draft RFC and its index row. It changes no code, and it leaves the 2026-09-13 decision amendment for a maintainer to rule on.

Notes

  • The RFC says a typed message retires every ask, and the agent re-declares on its next turn. That brings back one restating turn after any unrelated side question, which is part of the noise the RFC is meant to remove. The RFC should state that cost next to its problem 3 rather than only in §3.

[DESIGN-REVIEWED] 8f6432f

Description read

[DESCRIPTION-READ] d0b4d65dd83932ea70831dfa3c64f8843d817146a6045b20ee55116340664caa

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 8f6432fb1ed17c96c24ee501bea00b3e70b34aab via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8f6432f

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 8f6432fb1ed17c96c24ee501bea00b3e70b34aab via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 8f6432f

@unstablebrainiac
unstablebrainiac force-pushed the docs/rfc-waiting-on-you-cards branch from 701cae1 to 05efde2 Compare November 19, 2026 00:05
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/rfc-conductor-remote-dispatch.md and docs/request-for-change/rfc-slack-code-channels.md (same directory as this PR's files) since this head went green (6e059d7 -> 974172e); CI re-running. Docs lint passes locally on the new head 05efde2.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Phase 1 of this design is up for review as #39362. It follows this RFC, with three differences listed in its description (a paused crew queues an answer; edit-and-resend clears asks like rewind; Shared Crew teammates get 403 on the answer and dismiss routes). This RFC will be updated to match once those are reviewed. Phase 2 (loop guidance) waits for acceptance here.

@unstablebrainiac
unstablebrainiac force-pushed the docs/rfc-waiting-on-you-cards branch from 05efde2 to 8f6432f Compare November 19, 2026 03:07
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/rfc-session-semantic-search.md (same directory as this PR's files) since this head's base (974172e -> 5722dc2); CI re-running. Docs lint passes locally on 8f6432f.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 19, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 7% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 2: design-doc-gate: D.

This PR is docs only: a new draft RFC and one index row in docs/request-for-change/README.md. It changes no code, state, limits or runtime behaviour. The RFC does not edit the 2026-09-13 [OPTIONS:] decision. It quotes the decision's remedy line correctly and asks a maintainer for a separate ruling. That is how the repo has handled amendments to accepted documents before. I spot-checked its code references, and the symbols it relies on exist where it says (RESERVED_ROW_META_KEYS, HUMAN_TURN_META_KEY, _QUESTION_RETIRING_ROLES, ROLE_CARD, DISPLAY_ONLY_ROLES, _deny_app_token, LAZY_TAIL_ROWS, CARD_TURN_PREFIX, CREW_WORKER_ASK_ERROR, the MAC'd change-card store with its vault subkey). The trust design holds up. Only owner rows marked meta.human, answers and dismissals retire an ask. The forgery-sensitive meta key is added to RESERVED_ROW_META_KEYS. Agent text never enters a user row except as an option label the owner picked, which is the authority an [OPTIONS:] chip label already has. The store is tamper-evident the same way the change-card store is. The tool routes need the internal secret and an attested session key, and they address only the caller's own slo

Tier: 2, held for a person: design-doc-gate: D.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 8f6432fb1e · 279 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here.

To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

Review result on this head: the diff is docs only (the RFC and one index row), so no code runs. PR Readiness is green. We found no blocking issue. We checked the code symbols the RFC cites against this head and current main, and they exist where the RFC says. The RFC also handles the 2026-09-13 [OPTIONS:] decision correctly: it asks for a new superseding decision entry and does not edit the old one.

Optional notes for the revision before acceptance:

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 19, 2026
@unstablebrainiac
unstablebrainiac force-pushed the docs/rfc-waiting-on-you-cards branch from 8f6432f to 4261fae Compare November 19, 2026 20:51
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/README.md (the RFC index row conflicted) since this head's base (0cb54a3 -> 0384909); CI re-running. Docs lint passes locally on 4261fae.

@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 19, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 19, 2026

This branch has not been deployed

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

Labels

fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants