Skip to content

docs(sidebar): describe the first-load pinned-order seed accurately - #22936

Closed
mbriones98 wants to merge 2 commits into
mainfrom
fix/22182-pinned-order-seed-docs
Closed

mbriones98 wants to merge 2 commits into
mainfrom
fix/22182-pinned-order-seed-docs

Conversation

@mbriones98

@mbriones98 mbriones98 commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the pinned-order contract text describe what the sidebar actually does on first load.

The docstring in website/src/utils/pinnedSessionOrder.ts says pinned rows stay unranked until someone reorders, so the pinned section keeps its plain sort. In the list view that is not what happens: the sidebar's first load saves the order it is showing (only_if_unset), so every pinned row gets a pin_rank without anyone reordering, and a later pin appends instead of sorting in. Several other comments repeat the same claim.

Why it matters

The docstring reads as the contract for pinned ordering. Anyone changing the sidebar or the gateway route from that text would expect unranked rows that are in fact ranked, and could "fix" the intended seed or build on behaviour that does not exist.

Not a goal

What changed (motivation → approach → change)

Symptom: the contract text promises a plain sort the sidebar does not keep. Cause: the first-load seed is deliberate (its own comment says so, and ChatSidebar.hapticTaps / ChatSidebar.slotSearchOrder tests name it), so the text is what is wrong. Change, comments and docstrings only:

  • website/src/utils/pinnedSessionOrder.ts: describe the first-load seed, and list when pinned rows do stay unranked: a board view with no old local order, an empty roster, before the seed succeeds, after a failed seed until the next page load, and a refused seed taking the stored order from the next slots frame.
  • website/src/pages/chat-sidebar/pinnedOrder.ts: align the usePinnedSessionOrder comment, and correct the usePinnedOrderAuthority note (a board view with an old local order does seed).
  • src/kiro_crew/dashboard/chat_folders.py: the only_if_unset note now says the first-load seed uses it, including for a browser that never kept a local order.
  • src/kiro_crew/dashboard/pinned_session_order.py: replace the "never reordered keeps the plain sort" lines with "no saved order".

Backwards compatibility

Compatible: only comments and docstrings change; no code path, route, or stored format is touched.

Removes nothing: the diff edits text in comments and docstrings only.

Tests

No tests added (no behaviour change). Ran:

  • pytest test/test_pinned_session_order.py test/test_pinned_order_real_sandbox.py: 132 passed, 6 skipped
  • vitest run src/test/ChatSidebar.hapticTaps.test.tsx src/test/ChatSidebar.slotSearchOrder.test.tsx: 17 passed
  • tsc --noEmit; eslint on the two touched TS files; black, flake8 and isort on the two touched Python files
  • scripts/check_file_line_cap.py and scripts/docs_lint.py: pass

Manual verification

N/A — docs/comments only, no runtime behaviour to exercise.

Screenshots / video

Why no screenshot: docs/comments only, no UI change; the only edit under website/src/pages/ is a code comment.

Related Issues

Fixes #22182

Follow-up: #25075 (deferred seed change, option 2 in #22182)

Replaces #22919 (reopened from a repo branch)

Pattern harvest

Not generalizable: the drift came from one deliberate seed path widening a narrow "until someone reorders" sentence, which no lint or rule could tell apart from intended prose.

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.

@mbriones98
mbriones98 requested review from a team and KiroCrewCaptain as code owners October 21, 2026 22:42
@mbriones98
mbriones98 enabled auto-merge (squash) October 21, 2026 22:42
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 2a53403b51b16a3cdfda6f88311e46b2e71f2eba — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing to check. The diff only changes comments and docstrings, so users see nothing new or different. That's why having no blind read and no screenshot leaves nothing unreviewed.

[UX-REVIEWED] 2a53403

Description read

[DESCRIPTION-READ] 8dbf885933eb9d40e09f512777d3d12c70d6be1dc2181dfaea4647e40ba84490

That sha256 names everything this verdict read: the PR description, plus the 3 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 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 2a53403b51b16a3cdfda6f88311e46b2e71f2eba — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Only comments change, and the new text matches the code: usePinnedOrderAuthority seeds the natural order with only_if_unset, and a board view seeds only when the browser kept an old local order.

[DESIGN-REVIEWED] 2a53403

Description read

[DESCRIPTION-READ] b4286bea86a37d0a6b1042d1c1eadad789e76ed575d36c8d529be1d5ca251a43

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2a53403b51b16a3cdfda6f88311e46b2e71f2eba — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Comments only, and each edit matches code that already exists: the only_if_unset seed of the natural order in usePinnedOrderAuthority, and its board-view branch for an old local order (boardProjection && legacy.length === 0).

What this change ships

Inventory (5 items) — 5 justified

Intent: make the comments that state the pinned-order rules match what the sidebar does on first load (#22182). This is a FIX.

  1. The pinned-order docstring in the frontend utils now says the first-load seed ranks pinned rows, and lists when rows stay unranked — justified
  2. The usePinnedSessionOrder comment no longer promises the plain sort to a person who never reordered — justified
  3. The usePinnedOrderAuthority note now says a board view still seeds when this browser kept an old local order — justified
  4. The backend api_chat_pinned_order docstring says the first-load seed, including the natural order, uses only_if_unset — justified
  5. The backend store's rules and the after_pin_change docstring say "no saved order" instead of "never reordered" — justified

[FIRST-PRINCIPLES-REVIEWED] 2a53403

Description read

[DESCRIPTION-READ] c9c6cc5d42533d6e841d75f2f33f116d64ea81fd020ade649d07dd50f1917fa4

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 2a53403b51b16a3cdfda6f88311e46b2e71f2eba — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2a53403

Verdict parsed from the review's SHA-scoped output markers for commit 2a53403b51b16a3cdfda6f88311e46b2e71f2eba.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2a53403b51b16a3cdfda6f88311e46b2e71f2eba false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 2a53403b51b16a3cdfda6f88311e46b2e71f2eba and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2a53403

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2a53403b51b16a3cdfda6f88311e46b2e71f2eba false-positive: <reason, 20 to 500 characters>

Matt Briones added 2 commits October 27, 2026 19:09
The pinned-order contract said pinned rows stay unranked until someone
reorders. The sidebar's first list-view load seeds the order it shows,
so rows gain a rank without a reorder. Say so, and list the cases where
rows do stay unranked. Align the only_if_unset note on the gateway side.

Fixes #22182
Say that rows stay unranked until the seed succeeds, that a failed seed
waits for the next page load, and that a refused seed takes the stored
order. Note that a board view with an old local order also seeds, and
drop the remaining 'never reordered keeps the plain sort' lines.
@iamwhatever
iamwhatever force-pushed the fix/22182-pinned-order-seed-docs branch from 6a01a17 to 2a53403 Compare October 27, 2026 19:09
@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 27, 2026
@iamwhatever iamwhatever self-assigned this Oct 27, 2026

@iamwhatever iamwhatever 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 changes for one tracking item only; the edits themselves are correct.

Reviewed head: 2a53403

The new comments match the code. usePinnedOrderAuthority seeds the old local order plus the natural order with only_if_unset, skips a board view only when no local order exists, waits on an empty roster, does not retry a failed seed until reload, and takes the stored order after a 409. The new contract text lists exactly those cases. CI and all AI lanes are green.

What needs a change: the description's Not a goal says changing the seed itself (seeding only when a browser kept an old local order, option 2 in #22182) is "left to a separate issue", but no issue is linked, and Fixes #22182 closes the only place that question is written down. Please either open an issue for that behaviour question and link it in the description, or, if option 2 is rejected rather than deferred, say so in Not a goal instead of promising a separate issue.

— crew-pr-reviewer (r130)

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 27, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thanks for the review. Option 2 from #22182 is deferred, not rejected: opened #25075 to track the seed change and linked it in the description (Not a goal and Related Issues). No code change.

@bolichen97

Copy link
Copy Markdown
Contributor

[operator: bolichen97] Continuing this in #31411; thanks for the start.

bolichen97 added a commit that referenced this pull request Nov 6, 2026
The pinned-order contract said a person who never reordered keeps the
plain sort inside the pinned section. The sidebar's first list-view
load seeds an order with only_if_unset (this browser's old local order
if it kept one, then the natural order), so rows gain a pin_rank
without any reorder and later pins append. The seed is intended, so
the text is corrected wherever it repeated the claim: the contract
docstring, the seed hook and client notes, the route and store
docstrings, the agent-facing pin-move description and session-control
doc, and the owning spec. No code changes.

Builds on #22936.

Co-authored-by: Matthew Briones <50031759+mbriones98@users.noreply.github.com>
bolichen97 added a commit that referenced this pull request Nov 6, 2026
The pinned-order contract said a person who never reordered keeps the
plain sort inside the pinned section. The sidebar's first list-view
load seeds an order with only_if_unset (this browser's old local order
if it kept one, then the natural order), so rows gain a pin_rank
without any reorder and later pins append. The seed is intended, so
the text is corrected wherever it repeated the claim: the contract
docstring, the seed hook and client notes, the route and store
docstrings, the agent-facing pin-move description and session-control
doc, and the owning spec. No code changes.

Builds on #22936.

Co-authored-by: Matthew Briones <50031759+mbriones98@users.noreply.github.com>
bolichen97 added a commit that referenced this pull request Nov 6, 2026
The pinned-order contract said a person who never reordered keeps the
plain sort inside the pinned section. The sidebar's first list-view
load seeds an order with only_if_unset (this browser's old local order
if it kept one, then the natural order), so rows gain a pin_rank
without any reorder and later pins append. The seed is intended, so
the text is corrected wherever it repeated the claim: the contract
docstring, the seed hook and client notes, the route and store
docstrings, the agent-facing pin-move description and session-control
doc, and the owning spec. No code changes.

Builds on #22936.

Co-authored-by: Matthew Briones <50031759+mbriones98@users.noreply.github.com>
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 6, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you for this work! As noted in the thread, it continued in #31411, which has now merged. Closing this one as superseded by #31411.

@iamwhatever iamwhatever closed this Nov 8, 2026
auto-merge was automatically disabled November 8, 2026 09:36

Pull request was closed

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

sidebar: the first-load pinned-order seed ranks rows nobody reordered

3 participants