Skip to content

docs(decisions): record seven settled decisions the history kept correcting back to - #18409

Merged
chenmingwei23 merged 1 commit into
mainfrom
docs/record-seven-mined-decisions
Oct 9, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
docs/record-seven-mined-decisions

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record, under docs/decisions/, seven product decisions a maintainer already made on record, so the next pull request that reverses one is blocked instead of merged.

A scan of every PR on main (2026-06..2026-10) for patterns that were changed and then put back found 41 settled patterns that have an on-record maintainer statement but no docs/decisions/ entry. Each has already cost at least one revert or correction round. The maintainer picked these seven to record first (#18408).

Why it matters

recorded-decisions-are-not-regressions and issue triage read only docs/decisions/. A decision that lives in a PR comment or a revert body is invisible to them, so the same reversal can land again (the SidePanel tabs did: #6491 → #10119 → #10626). Recording it once ends that cycle.

Not a goal

  • No code or behaviour change; every entry describes what main already does.
  • Not recording the other 34 confirmed candidates; they stay in the maintainer's queue.
  • Not splitting decision 5 into a separate PR: the maintainer asked for one PR.

What changed (motivation → approach → change)

Seven new immutable entries, each citing where the decision was made and the comment where its maintainer restates it on this PR (docs/decisions/README.md rule 4), plus seven rows in the README index.

Entry Decision Decided Where
2026-10-03-every-agent-turn-ends-with-text-or-nothing-to-do.md A turn ends with closing text or nothing_to_do, never a bare tool stop Zezhen Xu, 10-03 #16392 comment
2026-09-29-glass-pane-does-not-change-on-focus.md A glass pane is identical at rest and focused; the caret is the cue Zezhen Xu, 09-29 #14992 comment
2026-09-14-side-panel-tabs-are-fused-and-the-activity-toggle-is-on-the-title-row.md Fused browser-style tabs; activity toggle on the chat title row Zezhen Xu, 09-14 #10626 body, #10619
2026-09-13-crew-members-message-through-session-send-not-an-inbox.md Members message via session_send; no inbox subsystem Zezhen Xu, 09-13 #10527 comment
2026-09-13-options-are-read-from-the-newest-reply-only.md [OPTIONS:] from the newest reply only; no backward scan Joe Guo, 09-13 #10173 verdict, #10615
2026-09-05-sidebar-lanes-end-with-a-show-all-older-sessions-row.md In-flow "Show all older sessions" row stays alongside the footer Zezhen Xu, 09-05 #8710, #8720
2026-10-08-crewmate-profile-card-tabs-are-sessions-schedules-goals-profile.md Tabs Sessions, Schedules, Goals, Profile; opens on Sessions Zezhen Xu, 10-08 #18245 comment

The Why sections quote the maintainer's own words where a conclusion is his; the remaining lines describe diffs and dates.

Merge order: this PR is merged only after both restatement comments are on it — @CrysisDeu for decisions 1, 2, 3, 4, 6, 7 and @iamwhatever for decision 5 — because entries are immutable once merged and each one cites those comments.

Backwards compatibility

Compatible: documentation only; no code, config or data shape changes.

Removes nothing: seven files added, one README table extended.

Tests

N/A — no code. DECISIONS_BASE_REF=origin/main scripts/check_decisions_history.py confirms the six existing entries are byte-identical; scripts/docs-lint.sh passes.

Manual verification

Each cited comment URL opened and read; each quoted sentence copied from the comment or PR body it is attributed to.

Related Issues

Closes #18408

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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.

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 9, 2026 08:52
@CrysisDeu
CrysisDeu requested a review from cruisercohen October 9, 2026 08:52
@CrysisDeu
CrysisDeu force-pushed the docs/record-seven-mined-decisions branch from 9e6ef3b to 8cc34dd Compare October 9, 2026 08:52
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 6c4e79bc98f28c19969dadc129ad0a14ba279b06 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6c4e79b

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

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 6c4e79bc98f28c19969dadc129ad0a14ba279b06 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 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 6c4e79bc98f28c19969dadc129ad0a14ba279b06 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 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Before merge, check that the @CrysisDeu and @iamwhatever restatement comments are on #18409. Entries can't be edited after merge, and all seven cite those comments.

[DESIGN-REVIEWED] 6c4e79b

Description read

[DESCRIPTION-READ] 2276b84c83e1835847cd283f7ccc2898fc2286320002f1280d9d163d6f0d92c2

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 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 6c4e79bc98f28c19969dadc129ad0a14ba279b06 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6c4e79b

Verdict parsed from the review's SHA-scoped output markers for commit 6c4e79bc98f28c19969dadc129ad0a14ba279b06.

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 9, 2026
…ecting back to

A scan of every PR on main for patterns that were changed and then put
back found 41 settled patterns with an on-record maintainer statement
and no entry under docs/decisions/. The maintainer picked these seven
to record first: the turn-end contract, glass panes not changing on
focus, the SidePanel's fused tabs and title-row toggle, member
messaging through session_send without an inbox subsystem, [OPTIONS:]
read from the newest reply only, the in-flow "Show all older sessions"
row, and the crewmate Profile card's tab order.

Each entry cites the pull request or issue where the decision was made
and the comment where the maintainer restates it on this pull request.

Refs #18408
@CrysisDeu
CrysisDeu force-pushed the docs/record-seven-mined-decisions branch from 8cc34dd to 6c4e79b Compare October 9, 2026 09:05
@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Merging before the restatements locks in an incomplete record (span=03afcfa086d7) — accepted

Outcome: accepted as a merge-order constraint. This PR is not merged until both restatement comments are on it (@CrysisDeu for 1, 2, 3, 4, 6, 7; @iamwhatever for 5). The PR body now states that under "Merge order"; nothing to change in the diff.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Some unquoted lines in Why read as maintainer conclusions but were written by the agent (span=7b1aefe0f91e) — fixed

Outcome: fixed in 6c4e79b. The glass entry no longer says the trade-off "is accepted"; it says the maintainer's restatement on this PR is the record of it. The inbox entry now quotes the owner's own "Considered, not adopted (owner: trust the agents)" paragraph from #10527 instead of paraphrasing it. The SidePanel entry describes what #10119's diff removed and quotes the full revert sentence instead of calling the reversal undeclared.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Split decision 5 into its own PR (span=9b787300cbdf) — rebutted

Outcome: rebutted. The maintainer asked for these seven in one PR ("写成一个PR"), and the PR body lists the split as a non-goal. The merge-order constraint above already covers the risk: the PR waits for both maintainers, and a dispute on decision 5 is handled by dropping that one file from the commit rather than by a second PR.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 9, 2026
@chenmingwei23
chenmingwei23 merged commit f2ba74a into main Oct 9, 2026
102 checks passed
@chenmingwei23
chenmingwei23 deleted the docs/record-seven-mined-decisions branch October 9, 2026 10:18
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 9, 2026
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.

docs(decisions): record seven settled decisions the PR history keeps correcting back to

2 participants