Repository navigation
docs(decisions): record seven settled decisions the history kept correcting back to - #18409
Conversation
9e6ef3b to
8cc34dd
Compare
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of 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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
…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
8cc34dd to
6c4e79b
Compare
|
|
|
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 nodocs/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-regressionsand issue triage read onlydocs/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
mainalready does.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.mdrule 4), plus seven rows in the README index.2026-10-03-every-agent-turn-ends-with-text-or-nothing-to-do.mdnothing_to_do, never a bare tool stop2026-09-29-glass-pane-does-not-change-on-focus.md2026-09-14-side-panel-tabs-are-fused-and-the-activity-toggle-is-on-the-title-row.md2026-09-13-crew-members-message-through-session-send-not-an-inbox.mdsession_send; no inbox subsystem2026-09-13-options-are-read-from-the-newest-reply-only.md[OPTIONS:]from the newest reply only; no backward scan2026-09-05-sidebar-lanes-end-with-a-show-all-older-sessions-row.md2026-10-08-crewmate-profile-card-tabs-are-sessions-schedules-goals-profile.mdThe
Whysections 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.pyconfirms the six existing entries are byte-identical;scripts/docs-lint.shpasses.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
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.