Skip to content

docs(rfc): Mate gets one landing, then the ordinary landing applies - #18903

Merged
buluoray merged 1 commit into
mainfrom
docs/rfc-mate-landing-first-run
Oct 11, 2026
Merged

buluoray merged 1 commit into
mainfrom
docs/rfc-mate-landing-first-run

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the decision that Mate gets one landing on the Crewmates page, for fresh and existing users alike, and then the ordinary landing applies.

A user was moved onto Mate on every bare Crewmates visit. When Mate's welcome lands this already ends (the welcome row sets has_dm_message). It never ends when the welcome fails: claim_greeting_marker is claimed before the welcome is dispatched, a failed turn leaves the thread empty, and pendingMate answers Mate on every visit.

Why it matters

A user whose welcome failed (signed-out CLI, no backend) is pinned on an empty Mate for good and never reaches the crewmate they last chatted with.

Not a goal

What changed (motivation → approach → change)

Edited 2026-10-11 to the rule buluoray asked for in the review (the first draft yielded whenever another crewmate was chatted with; that is now §4's rejected alternative).

  • docs/request-for-change/rfc-mate-landing-once.md (draft): Mate lands once; once its welcome marker is claimed or its thread has a row, the ordinary landing applies; an unreadable state falls back to the ordinary landing; ?member= wins, default does not count, Mate stays on the roster. §4 picks "yields once its welcome is sent or attempted" over "first until the user replies" and "never for a returning user". §5 lists the tests. Claims checked at 73d44b420b.
  • docs/request-for-change/README.md: index row and audit line.

Backwards compatibility

Compatible: docs only.

Removes nothing: adds one RFC document and one index row.

Tests

N/A — docs only. scripts/docs-lint.sh passes.

Manual verification

N/A — docs only. The code claims (claim_greeting_marker before dispatch in maybe_start_first_greeting; has_dm_message counts live rows; pendingMate reads only rows) were read at 73d44b420b.

Related Issues

Amends rfc-crewmate-guides-and-mate.md (#18326, implemented in #18406). Implementation: #18904.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

Contributed under the project's Apache-2.0 license.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

@buluoray this amends your rfc-crewmate-guides-and-mate "When it opens": a never-chatted Mate stays the first-visit landing, but only while the user has no other crewmate they chatted with (last_chat_ts) or last opened. Today a returning user is moved onto Mate on every bare visit. Could you accept (or adjust) it? The implementation PR follows and links here.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 9d23c57fc4487be7d23a2d7e0d903b6e269d26ae ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 9d23c57fc4487be7d23a2d7e0d903b6e269d26ae touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 9d23c57fc4487be7d23a2d7e0d903b6e269d26ae — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The "Seen" rule (marker claimed or thread has a row) misses a Mate whose welcome is never owed. That Mate stays empty and unclaimed, so it pins the user on every visit, as today.

Watch

  • There is a fourth welcome state, and the table doesn't have it. §2 defines "Seen = the welcome marker has been claimed (claim_greeting_marker), or Mate's thread has any row". It sends "not sent yet" to Mate.
    • Cause: maybe_start_first_greeting returns NOT_OWED before it claims the marker whenever members.welcome_owed is False (mate_welcome.py:208).
    • Mechanism: welcome_owed is False when welcome_owed.json is missing, unreadable or names another member. Only first_crewmate._owe_first_welcome writes that file, and only when it creates Mate fresh. Its docstring says a write failure "only costs the welcome". So a Mate that already existed, or whose record failed to write, never gets a welcome: the marker stays unclaimed and the thread stays empty.
    • Consequence: under the RFC's rule that Mate reads as "not sent yet" forever. pendingMate keeps answering Mate on every bare visit, which is the harm §1 sets out to remove, reached by a different path. The §5 tests never build this state.
    • The NO_THREAD and NOT_CREWMATE refusals leave Mate in the same unclaimed, empty state.

Clears when: §2 counts "welcome not owed" (or any refusal that leaves the welcome unclaimed) as seen, or the roster reports the owed state so the rule can use it, and §5 adds a test for an empty Mate with no owed record and no marker that lands on the ordinary landing.

Suggestions

  • §4 should name the root-cause option and say why it was rejected: release the marker when the welcome turn fails, so the welcome is retried. Without that, choosing to treat a failed welcome as seen reads as unexamined.

[DESIGN-REVIEWED] 9d23c57

Description read

[DESCRIPTION-READ] 161524e8d44d98f7e5594cf9a2e679ff94c1c291647a14ec351c5792cf3c36f6

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 Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 9d23c57fc4487be7d23a2d7e0d903b6e269d26ae — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9d23c57

Verdict parsed from the review's SHA-scoped output markers for commit 9d23c57fc4487be7d23a2d7e0d903b6e269d26ae.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 9d23c57fc4487be7d23a2d7e0d903b6e269d26ae: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 9d23c57fc4487be7d23a2d7e0d903b6e269d26ae and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9d23c57

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9d23c57fc4487be7d23a2d7e0d903b6e269d26ae: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 10, 2026

@buluoray buluoray left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting one change before I accept this as the author of rfc-crewmate-guides-and-mate. Reviewed at 79a58e3291d37604b723ed01ffe6a206e96b79e0.

The rule I want: Mate gets one landing, for fresh and existing users alike. Once Mate has sent its welcome, it counts as seen, and the ordinary landing applies. The original decision put Mate first "on fresh and existing installs alike" on purpose, so existing users get introduced to it. A rule where a returning user is never shown Mate unless they go looking drops that.

As far as I can read main, that is already what happens when the welcome lands, which the Problem section should say:

  • The welcome is a real assistant row in Mate's thread (dashboard/mate_welcome.py, "The greeting itself is the crewmate's own assistant row").
  • has_dm_message counts it, including a live row that has not flushed yet (dashboard/handlers/members.py:648-653).
  • So pendingMate (website/src/lib/assistantMember.ts:22-27) stops answering Mate after the welcome, and resolveMateLanding yields to lastChattedMember / the remembered crewmate on the next bare visit.

The case that does pin a user on Mate every visit is a welcome that never lands. The once-only marker is claimed before dispatch (claim_greeting_marker), so a failed welcome turn (signed-out CLI, no backend) leaves the thread empty for good, and pendingMate keeps answering Mate on every bare visit with no welcome coming.

What I'd accept this RFC as:

Mate's welcome Lands on
not sent yet Mate (one introduction, fresh and existing users)
sent the ordinary landing (last-chatted, then remembered crewmate)
attempted and failed the ordinary landing (counts as seen)
  • "Seen" = the welcome marker has been claimed, or Mate's thread has any row. That is server-side state, so it holds across browsers and restarts with no new client marker.
  • If that state cannot be read, fall back to the ordinary landing, so a read failure never pins the user on Mate.
  • ?member= still wins, default still does not count, and the user can always open Mate from the roster.
  • §4 should list "Mate yields once its welcome is sent or attempted" and why it is chosen over both "Mate first until the user replies" and "never land on Mate for a returning user".
  • §5's tests: an existing user lands on Mate once; after the welcome row exists, the next bare visit lands on their last-chatted crewmate; with a claimed marker and an empty thread, the bare visit also lands on the last-chatted crewmate.

Once the document says this, I'll accept it here and the status can flip to accepted.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 11, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-mate-landing-first-run branch from 79a58e3 to db3ef22 Compare October 11, 2026 00:26
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 11, 2026
Amends rfc-crewmate-guides-and-mate "When it opens" in its own document,
on the rule buluoray asked for in the #18903 review: Mate lands once for
fresh and existing users; once its welcome marker is claimed or its
thread has a row, the ordinary landing applies. Draft; acceptance asked
of buluoray.
@iamwhatever
iamwhatever force-pushed the docs/rfc-mate-landing-first-run branch from db3ef22 to 9d23c57 Compare October 11, 2026 06:08
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 11, 2026
@iamwhatever iamwhatever changed the title docs(rfc): Mate's landing is for a first visit only docs(rfc): Mate gets one landing, then the ordinary landing applies Oct 11, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

@buluoray thanks, updated to your rule at 9d23c57 (one commit, docs-lint passes). The file is renamed to rfc-mate-landing-once.md, since "first run only" no longer fits.

Point by point:

  1. The rule. §2: Mate gets one landing, for fresh and existing users alike. Once its welcome is sent, or attempted and failed, it counts as seen and the ordinary landing applies (last-chatted, then remembered). Your three-row table is in §2 as written.
  2. Problem section. §1 now says main already yields when the welcome lands (the welcome is an assistant row; has_dm_message counts it, live rows included; pendingMate stops answering Mate). The real pin is a failed welcome: claim_greeting_marker runs before dispatch, the thread stays empty, and pendingMate answers Mate on every visit.
  3. "Seen". Marker claimed OR the thread has any row. Both are server-side, with no new client marker. The roster row will carry the claimed state beside has_dm_message.
  4. Unreadable state. Falls back to the ordinary landing, never Mate.
  5. ?member=, default, roster. ?member= wins, default does not count, and Mate stays openable from the roster.
  6. §4. Chosen: "Mate yields once its welcome is sent or attempted", because it keeps the introduction for everyone and ends the pin. Rejected: "first until the user replies", because a reader who leaves keeps landing on Mate, and a failed welcome still pins. Rejected: "never land on Mate for a returning user" (my first draft), because existing users would never be introduced.
  7. §5 tests. An existing user lands on Mate once. After the welcome row, the next visit lands on last-chatted. A claimed marker with an empty thread also lands on last-chatted. Also covered: an unreadable state, a fresh user, ?member=/default, and a backend test for the roster field.

#18904 is being reworked to match: the "another crewmate was chatted with" rule is dropped.

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is the rule I asked for, and §1's diagnosis of the failed-welcome pin matches main. One gap before I accept it, the one the Design lane raised, which I checked at origin/main:

A Mate whose welcome is never owed stays "not sent yet" forever. maybe_start_first_greeting returns NOT_OWED before it claims the marker (mate_welcome.py:208-209), and welcome_owed is only written by first_crewmate._owe_first_welcome when Mate is created fresh (first_crewmate.py:180-184, whose docstring says a write failure "only costs the welcome"). So a Mate that predates the owed record, or whose record failed to write, never claims the marker and never gets a row. Under §2 that Mate reads as "not sent yet", and pendingMate answers Mate on every bare visit: the same pin §1 removes, through a different path. NO_THREAD and NOT_CREWMATE leave the same unclaimed, empty state.

Ask:

  • §2: "not sent yet" means a welcome is still coming: owed, unclaimed, and the thread is empty. Anything else (not owed, refused, claimed, or a row exists) counts as seen and gets the ordinary landing. The roster row carries the owed state beside the claimed state.
  • §5: add a test for an empty Mate with no owed record and no marker, which lands on the ordinary landing.

Not blocking: §4 could name "release the marker when the welcome turn fails, so it is retried" and say why it was not chosen.

Once that lands I'll accept the RFC.

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving, and this supersedes my request-changes review on this head. As the author of rfc-crewmate-guides-and-mate, I accept this amendment: Mate gets one landing, and once its welcome is sent (or attempted and failed) the ordinary landing applies. Please flip status to accepted when you merge.

On the "welcome never owed" case I raised: Mate is the single built-in assistant and always sends its welcome, so that state is not one this rule needs to cover. No change needed to §2 or §5 for it.

@buluoray
buluoray enabled auto-merge (squash) October 11, 2026 06:45
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 11, 2026
@buluoray
buluoray merged commit a84f616 into main Oct 11, 2026
106 of 113 checks passed
@buluoray
buluoray deleted the docs/rfc-mate-landing-first-run branch October 11, 2026 07:00
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
iamwhatever pushed a commit that referenced this pull request Oct 11, 2026
…r a failed welcome

Mate's landing (#18406) answered Mate while its thread was empty. The
once-only welcome marker is claimed before the welcome is dispatched, so
a failed welcome left the thread empty for good and every bare visit
landed on Mate. The roster row now reports whether Mate's marker is
claimed (welcome_claimed), and resolveMateLanding yields once the marker
is claimed or the thread has a row; an unknown state uses the ordinary
landing (rfc-mate-landing-once, #18903).
iamwhatever pushed a commit that referenced this pull request Oct 11, 2026
…r a failed welcome

Mate's landing (#18406) answered Mate while its thread was empty. The
once-only welcome marker is claimed before the welcome is dispatched, so
a failed welcome left the thread empty for good and every bare visit
landed on Mate. The roster row now reports whether Mate's marker is
claimed (welcome_claimed), and resolveMateLanding yields once the marker
is claimed or the thread has a row; an unknown state uses the ordinary
landing (rfc-mate-landing-once, #18903).
chenmingwei23 pushed a commit that referenced this pull request Oct 11, 2026
…ion (#19064)

buluoray approved #18903 and asked for the status to be flipped. Folds in
the one gap that review raised: a Mate whose welcome was never owed is
refused before the marker claim, so "still coming" now means owed,
unclaimed and no row; anything else gets the ordinary landing. Adds the
"release the marker on failure" alternative to section 4.

Co-authored-by: Joe Guo <zejiangg@amazon.com>
iamwhatever pushed a commit that referenced this pull request Oct 11, 2026
…r a failed welcome

Mate's landing (#18406) answered Mate while its thread was empty. The
once-only welcome marker is claimed before the welcome is dispatched, so
a failed welcome left the thread empty for good and every bare visit
landed on Mate. The roster row now reports whether Mate's marker is
claimed (welcome_claimed), and resolveMateLanding yields once the marker
is claimed or the thread has a row; an unknown state uses the ordinary
landing (rfc-mate-landing-once, #18903).
iamwhatever pushed a commit that referenced this pull request Oct 11, 2026
…r a failed welcome

Mate's landing (#18406) answered Mate while its thread was empty. The
once-only welcome marker is claimed before the welcome is dispatched, so
a failed welcome left the thread empty for good and every bare visit
landed on Mate. The roster row now reports whether Mate's marker is
claimed (welcome_claimed), and resolveMateLanding yields once the marker
is claimed or the thread has a row; an unknown state uses the ordinary
landing (rfc-mate-landing-once, #18903).
bolichen97 pushed a commit that referenced this pull request Oct 12, 2026
…r a failed welcome (#18904)

Mate's landing (#18406) answered Mate while its thread was empty. The
once-only welcome marker is claimed before the welcome is dispatched, so
a failed welcome left the thread empty for good and every bare visit
landed on Mate. The roster row now reports whether Mate's marker is
claimed (welcome_claimed), and resolveMateLanding yields once the marker
is claimed or the thread has a row; an unknown state uses the ordinary
landing (rfc-mate-landing-once, #18903).

Co-authored-by: Joe Guo <zejiangg@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants