Repository navigation
fix: tighten guide observe, find_ui and search_docs from review - #18782
Conversation
Observe now needs a turn the person sent, audits every not-observed answer and carries the dashboard language so find_ui needs one round trip. findByName never matches a control inside agent-authored content. search_docs reads each page once until it changes. The ui-index input_digest is the hash of the generated content, so an unrelated locale edit no longer marks the committed index stale.
Sensitive change review
|
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Check what the guide says when someone asks about a button that sits inside agent-written content, which [UX-REVIEWED] c8b05eb Description read[DESCRIPTION-READ] 3232ae71326e28125fd72574cafb2768064b3884a6724f5fff6c19b078b3f7f1 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 |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check one thing before merge: [DESIGN-REVIEWED] c8b05eb Description read[DESCRIPTION-READ] fbf08ef52cd974033b2a3e870aea90c1d9728f90654743c27d401a183bac2726 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 |
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Moving the untrusted-content check into Not justified as shipped
What this change shipsInventory (8 items) — 6 justifiedIntent: close the review follow-ups left open on the guides PR #18443, so a guide observes the person's tab only when they asked, and searches cost fewer round trips. FIX.
[FIRST-PRINCIPLES-REVIEWED] c8b05eb Description read[DESCRIPTION-READ] 9a352505824aeb9c227adba35bc99cafea211bd0f73b03f937e743244adeff69 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Review detailsNo findings. Nothing here blocks the merge; there are two advisory findings. FINDING — src/kiro_crew/mcp_guide.py:343 — [OPUS-REVIEWED] c8b05eb Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsFINDING -- src/kiro_crew/mcp_guide.py:965 -- “ids to observe do not depend on the label language” contradicts execution (recurring-defect-patterns): querying False positive or not applicable? A repository writer can comment: |
Problem / Motivation
Goal: Apply the review follow-ups left open when the guides PR (#18443) merged, so a guide's tab observation,
find_uiandsearch_docsbehave as the review asked.The review on #18443 raised points after its head was already final:
not_observedanswer was never audited;find_uimade two calls (observe, then language);findByNamecould match a control inside agent-authored content;search_docsre-read every page on every call;Why it matters
An observation that times out marks the person's running guide stale, so a turn the person did not send must not trigger one. A control inside agent-written text is not something the guide should point at. The other points cost round trips, file reads and spurious
gen:ui --checkfailures for other PRs.Not a goal
What changed (motivation → approach → change)
Observe is a user-turn action.
guide.observejoins_USER_TURN_OPERATIONS, so a wake, cron, app or sub-agent turn gets 403not_user_turnbefore any tab is asked. Every observe answer,observedornot_observed, carriesui_lang, and everynot_observedoutcome is audited with its reason.One round trip for
find_ui.mcp_guidesearches, observes once, and relabels from the observation'sui_lang; it calls/api/guide/agent/languageonly when no observation was made. InfindByName.ts,interactive()drops anythinginUntrustedContent.search_docsreads pages through anlru_cachekeyed by path, mtime and size, so a page is read once until it changes; there is no module-level mutable state.A stable index digest. In
gen-ui-index.mjs,input_digestis the sha256 of the generated index with its own digest field blanked, so only a change to the index content moves it.docs/architecture/mcp.mdsays so.Backwards compatibility
Compatible: the observe response only gains a
ui_langfield. Thenot_user_turnrefusal applies to callers that were never meant to observe; the guide tools call observe only from a user's turn.Reader: src/kiro_crew/mcp_guide.py:_find_with_live -- chat -- reads
ui_langfrom the observation; test_find_ui_reads_the_dashboard_language_from_the_observation_in_one_callReader: src/kiro_crew/mcp_guide.py:guide observe tool -- chat -- a user turn still observes; test_guide_observe.py
Tests
test_a_turn_the_user_did_not_send_cannot_observe_their_tab: a wake turn gets 403 and no tab is asked.test_guide_observe.pynot-observed cases assertui_langand the audit row.test_find_ui_reads_the_dashboard_language_from_the_observation_in_one_call: one observe, and no separate language call.findByName.test.tsx: a control inside agent-authored content is never matched, whatever predicate the caller passes.test_search_docs_reads_each_page_once_until_it_changes.Local run: 1246 backend guide, find_ui and search_docs tests passed, plus vitest
findByName(72). mypy, flake8, black, tsc, eslint, docs-lint, comment-history andgen:ui --checkare all clean.Manual verification
N/A -- unit coverage is sufficient: there is no visual change, and every behaviour above is pinned by the tests listed.
Screenshots / video
Why no screenshot:
findByNameonly filters which elements the guide may point at; nothing renders differently.Related Issues
Part of #18300
Pattern harvest
Not generalizable: these are review points specific to the guide surface, not a recurring defect class.
Checklist
Contribution License Agreement