Skip to content

refactor(settings): keep tip prose apart from on-row description - #20510

Merged
bolichen97 merged 1 commit into
mainfrom
fix/settings-registry-hint-15893
Oct 15, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/settings-registry-hint-15893

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The settings registry says which help text a row shows on screen and which sits behind its info tip.

Since #15823 moved most explanations into each row's info tip, the generated settings registry folds the tip text and the on-row text into one description field. A reader of settingsRegistry.gen.ts or settings-registry.generated.json cannot tell which words the row actually shows. Nothing quotes the field as on-row copy today, so nothing looks wrong yet. The first reader that does would show tip text as if the row displayed it.

Why it matters

The agent reads the bundled JSON to tell users where a setting is. If it quotes a row's text, it should quote words the user can see. Fixing the shape now is cheap; fixing it after a reader depends on the merged field is not.

Not a goal

  • No change to what any setting row renders.
  • No change to how settings search ranks or what the palette subtitle shows.
  • No localization of the registry's help text.

What changed (motivation → approach → change)

The extractor joined the hint prop and the description prop into one string. It now keeps them apart: description holds only the text the row shows, and a new optional hint holds only the info-tip text. Both generated files carry the new field, and the scheme doc says which one is safe to quote.

Search (the palette and the agent's find_settings) and the palette subtitle join the two fields themselves, tip first, the same order as before, so they match and render exactly as they did. Across all 245 committed entries, tip plus description equals the old description byte for byte. The agent's find_settings answer keeps them apart too: each row returns description (on-row) and hint (tip), and the find_setting tool text says which is which.

Backwards compatibility

Compatible: description and hint are both optional, search and the palette subtitle still read the same joined help text, and no field was renamed. A find_settings row whose help sits only in a tip now carries it in hint and an empty description.

Reader: website/src/components/commandPalette/settingsSearchCore.ts:scoreSettingEntry -- chat -- reads settingHelpText(entry), the same joined text as before
Reader: website/src/components/commandPalette/settingsTabLabel.ts:settingsSubtitle -- chat -- reads settingHelpText(entry); settingsRegistry.test.ts subtitle case
Reader: src/kiro_crew/dashboard/change_cards.py:find_settings -- chat -- matches on _help_text(entry), returns description and hint apart; test_find_setting_keeps_tip_text_apart_from_row_text
Reader: src/kiro_crew/mcp_guide.py:find_setting -- chat -- tool text names description and hint; test_change_cards.py passes
Reader: src/kiro_crew/dashboard/change_cards.py:_row_hits -- chat -- reads _help_text(entry); test_change_cards.py passes
Reader: src/kiro_crew/guide_catalog.py:guidable_settings -- chat -- never read description; unchanged

Tests

  • settingsRegistry.test.ts: the extractor puts hint and description in their own fields; the agent registry keeps both unmerged; settingHelpText and the subtitle still read both, tip first; no committed row's description starts with its own tip. The existing byte-match guards cover both regenerated files.
  • settingsExtractCoverage.test.ts: the hint-indexing cases now pin hint and description as separate fields, and settingHelpText as the tip-first join.
  • test_change_cards.py: a find_settings row returns tip text in hint and only on-row text in description.
  • test_settings_deeplink_registry.py: hint is an allowed agent field; the bundled JSON carries tips in hint and never repeats a tip at the start of description; _help_text joins tip then description.

Manual verification

N/A — unit coverage sufficient: no rendered surface changes, and the byte-match guards pin both generated files to a live extraction.

Screenshots / video

Why no screenshot: the diff splits one field of the generated settings registry into two and every rendered string (palette title, subtitle, settings rows) stays byte-identical, so there is nothing new to show.

Related Issues

Closes #15893

Pattern harvest

Not generalizable: one extractor merged two props into one field on purpose when only search read it; the fix is this field split.

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 14, 2026 21:48
@bolichen97
bolichen97 enabled auto-merge (squash) October 14, 2026 21:48
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 14, 2026
@bolichen97
bolichen97 force-pushed the fix/settings-registry-hint-15893 branch 2 times, most recently from e6decc6 to c751b5d Compare October 14, 2026 22:25
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] a2848fe

Description read

[DESCRIPTION-READ] be5ecbdf9f1533e0df5d1bd3b05903f792bd94cc2ffe33f7950033c97120cf9d

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] a2848fe

Description read

[DESCRIPTION-READ] 888eb394addc847878947005cb493ec2e511bcf8835a5889cdfd60ea1d89bd01

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of a2848feb36c530c07e7df2cfb20fb463e8639f72 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check that the agent still answers well when find_settings returns an empty description, which now happens for most rows because their only help is a tip.

What this change ships

Inventory (6 items) — 6 justified

Intent: let a reader of the settings registry tell which help text a row shows on screen and which sits behind its info tip (closes #15893). This is a FIX.

  1. The extractor stops merging the hint prop into description, so tip text moves into its own hint field in both generated registries — justified
  2. The agent's find_settings rows return the tip as hint and only on-row text as description, so tip-only rows now come back with an empty description — justified
  3. The find_setting tool text names description and hint and says which one the row shows — justified
  4. The scheme doc settings-deeplink.md documents hint and says to quote only description as on-row copy — justified
  5. Palette search, its subtitle and backend search join tip and description themselves (settingHelpText and _help_text, 2 consumers each), so results and subtitles are unchanged — justified
  6. ManualSettingEntry leaves out hint, so hand-written entries cannot set it — justified

[FIRST-PRINCIPLES-REVIEWED] a2848fe

Description read

[DESCRIPTION-READ] 0a69ba6fa61c8c71fa2c6e42031ece204bf442aaa8e56649956ddb36d82a23bf

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a2848fe

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

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

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a2848fe

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

@bolichen97
bolichen97 force-pushed the fix/settings-registry-hint-15893 branch 2 times, most recently from 50f43b8 to abdbaf0 Compare October 14, 2026 23:28
@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 15, 2026
@bolichen97
bolichen97 force-pushed the fix/settings-registry-hint-15893 branch from abdbaf0 to a2848fe Compare October 15, 2026 01:29
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/dashboard (server, chat_handlers, chat_runner, chat_delivery, chat_utils, chat_persistence) and src/kiro_crew/constants.py since this head went green (b9fd3d5 -> c64afca); CI re-running.

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

Copy link
Copy Markdown
Contributor

HOLD at a2848fe.

This head was pushed at 01:29Z as a rebase. Its CI and every AI review lane were still queued or running when I read it, and PR Readiness is pending. So there is no current-head review evidence yet.

The change itself reads as sound. The extractor keeps hint and description apart (settingsExtract.ts#L406-L414). Search and the palette subtitle join the two, tip first, through settingHelpText/_help_text (change_cards.py#L1199-L1205), and tests pin it. I found no defect.

What would clear this hold:

  • Every lane finishes green on a2848fe.
  • The new head's AI verdicts are read, and any non-PASS item is answered.
  • The PASS punchlines on tip-only find_settings rows (empty description, help only in hint) get a short reply. The find_setting tool text now names both fields, so a sentence saying so is enough.

The two generated registry files are pinned by byte-match guards, and I did not read them line by line. I read the rest of the diff and the tests but did not run them.

— crew-pr-reviewer (r102)

@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 15, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved by a maintainer who read the review lane notes and accepted them as follow-up work.

@bolichen97
bolichen97 merged commit 6af6267 into main Oct 15, 2026
101 of 102 checks passed
@bolichen97
bolichen97 deleted the fix/settings-registry-hint-15893 branch October 15, 2026 04:55
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 15, 2026
@Pearcekieser Pearcekieser mentioned this pull request Oct 15, 2026
5 tasks done
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.

Settings registry: tell tip prose apart from on-row description

3 participants