feat(page-actions): add UI-mode instructions to agent handoff

[JakeSCahill]

Summary

• Follow-up to feat(page-actions): add agent handoff prompt #408. Add an opt-in mode to the agent handoff action so pages describing console/UI-driven workflows get instructions suited to that, instead of the project-editing instructions.
• :page-agent-handoff: (unset value) keeps today's behavior — project-editing instructions.
• :page-agent-handoff: ui selects a new instruction set: verify the current UI against the docs, don't invent menu/field/button names, confirm before mutating live resources, verify results after acting.
• Unrecognized mode values fall back to the project instructions.

Why

Not all documentation describes something an agent can edit as a "project" (e.g. console click-throughs for creating/deleting resources). The current agent handoff prompt tells the agent to "work in the current project," which doesn't fit those pages. This lets a page opt into UI-appropriate instructions instead, without adding a second attribute for writers to learn.

Implementation

• src/helpers/agent-handoff-mode.js (new): reads the page-agent-handoff attribute value, defaults to project.
• src/js/13-agent-handoff.js: intro/instructions are now keyed by mode (PROMPT_INTROS, INSTRUCTION_SETS); buildAgentHandoffPrompt takes a mode param.
• src/js/14-markdown-dropdown.js: reads data-agent-handoff-mode off the dropdown and threads it through to the prompt builder.
• src/partials/markdown-dropdown.hbs: renders data-agent-handoff-mode.
• preview-src/agent-handoff-ui-test.adoc (new): preview page with :page-agent-handoff: ui for local testing.

Note: the UI instruction wording here is a draft for review, not final copy — #408 assigns ownership of customer-facing prompt wording to the documentation team.

Verification

• npm run test:markdown-dropdown (13 tests, including 2 new ones)
• npx gulp lint
• Manual click-through in a real browser (fetch/clipboard stubbed) confirmed: the ui-mode page copies the new intro/instructions and none of the project-mode language; an unmodified default page still copies byte-for-byte the same prompt as before this change.

Test plan

• On a page with :page-agent-handoff: (no value), confirm "Copy agent handoff" still produces the original project-editing prompt.
• On preview-src/agent-handoff-ui-test.adoc (:page-agent-handoff: ui), confirm "Copy agent handoff" produces the UI-mode prompt.
• Docs team reviews/edits the UI instruction copy before enabling ui mode on any real page.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for docs-ui ready!

Name	Link
🔨 Latest commit	3ce5536
🔍 Latest deploy log	https://app.netlify.com/projects/docs-ui/deploys/6a7217aa02f74c0008673e24
😎 Deploy Preview	https://deploy-preview-411--docs-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 29 (🟢 up 3 from production) Accessibility: 89 (no change from production) Best Practices: 92 (no change from production) SEO: 89 (no change from production) PWA: - View the detailed breakdown and full score reports
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 73fba0f2-3cb3-4b06-9969-1aea60845aac

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The change adds project and UI modes to agent handoff prompts. A new helper normalizes the page mode and defaults to project. The dropdown exposes the mode through a data attribute and passes it to prompt generation. UI prompts include interface checks, ordered execution, confirmation, discrepancy handling, and post-step verification. Tests cover explicit, default, normalized, UI, and unknown modes. A UI-mode test page was added.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Page
  participant markdownDropdown
  participant handleCopyAgent
  participant buildAgentHandoffPrompt
  Page->>markdownDropdown: render normalized agent handoff mode
  markdownDropdown->>handleCopyAgent: pass selected mode
  handleCopyAgent->>buildAgentHandoffPrompt: include mode in prompt arguments
  buildAgentHandoffPrompt-->>handleCopyAgent: return project or UI prompt

Loading

Possibly related PRs

• redpanda-data/docs-ui#408: Introduced the agent handoff functionality and wiring extended by this change.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding UI-mode instructions to agent handoff.
Description check	✅ Passed	The description explains the UI mode, fallback behavior, implementation, testing, and rollout considerations for the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent-handoff-ui-mode

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[micheleRP]

Docs-team-standards review

I ran the suite (11 tests, all pass) and diffed prompt output against the post-#408 baseline at 3764dd8d5: the default path is byte-identical to before this change, both with no mode and with explicit mode: 'project'. That compatibility guarantee is the context for suggestion 3 below.

Suggestions

1. A mistyped mode fails silently, in the worst direction. I confirmed that mode: 'UI' returns a prompt identical to project mode. So a writer who puts :page-agent-handoff: UI (or Ui, or console) on a console click-through page gets a prompt telling the agent to "Work in the current project," "edit and test local files," and run the project's checks. That is precisely the mismatch this PR exists to prevent, delivered with no warning. Normalizing in agent-handoff-mode.js costs one line:

   return String(root.page?.attributes?.['agent-handoff'] || '').trim().toLowerCase() || 'project'

   Keeping the fallback for genuinely unknown values is right. It is the near-miss cases that need catching.

2. The prompt's H1 stays project-flavored in UI mode. The heading is still # Apply this Redpanda documentation while the UI intro says "Complete this documented task in the current console, cluster, or account." "Apply this documentation" reads oddly for a click-through task. Since intro and instructions are already keyed by mode, the title should be too.

3. No test locks in the byte-identical default. The new tests assert substring matches, so a future mode refactor could drift the default prompt without failing anything. Since byte-identity is the compatibility guarantee for every page already using #408, an equality or snapshot assertion would be cheap insurance.

4. The mode data attribute renders on every page with markdown, including pages that never opted into handoff at all, because the attribute sits on the wrapper div outside the has-agent-handoff guard. Harmless, but it puts a meaningless data-agent-handoff-mode="project" on most of the site.

Content review of the UI instruction set

Taking this as the CODEOWNER for the prompt wording, per #408.

The prompt assumes the agent can see a UI. Every instruction ("verify each one against what is on screen," "verify the result in the UI") presumes browser or computer-use access. Most coding agents pasted this prompt have none. Without an escape hatch, the likely outcome is an agent that narrates having clicked through a destructive sequence it never performed, which is the worst failure mode for a prompt whose item 4 is about creating and deleting live resources. Recommend an explicit first instruction: if you cannot see the interface, do not guess. Produce a step-by-step checklist for me to execute, and stop.

The resource enumeration in item 4 is Streaming-shaped. "(clusters, topics, users, ACLs, billing)" will read as wrong on Agentic Data Plane or Connect pages, where the destructive nouns are agents, MCP servers, providers, or pipelines. "Billing" is also an odd member of that list. A generic phrasing ages better than an enumeration that drifts per component.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/js/13-agent-handoff.js`:
- Around line 131-133: Update the mode selection in the prompt-building logic to
use an own-property check on PROMPT_TITLES, PROMPT_INTROS, and INSTRUCTION_SETS,
falling back to the project entries for inherited or unrecognized values such as
constructor and toString. Add a regression test covering one of these values and
verify the generated instructions remain the project-mode set.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6bd800df-d559-49c7-9be5-c7277c4779cf

📥 Commits

Reviewing files that changed from the base of the PR and between 3764dd8 and ab28825.

📒 Files selected for processing (7)

• preview-src/agent-handoff-ui-test.adoc
• src/helpers/agent-handoff-mode.js
• src/js/13-agent-handoff.js
• src/js/14-markdown-dropdown.js
• src/partials/markdown-dropdown.hbs
• tests/markdown-dropdown/agent-handoff.test.js
• tests/markdown-dropdown/visibility.test.js

[micheleRP]

Follow-up review: impact outside this PR

Re-reviewed after ab28825 and 3ce5536. All four findings from my earlier review are fixed, and I verified them against the code rather than the commit messages: mode normalization (trim().toLowerCase()), mode-keyed PROMPT_TITLES, the byte-exact pinned default prompt with assert.equal, and the data attribute now gated behind has-agent-handoff. Both content items are addressed too — the no-UI-access escape hatch is in as instruction 1, and the Streaming-shaped resource enumeration is gone with a doesNotMatch test pinning its removal. npm run test:markdown-dropdown gives 15/15 and npx gulp lint is clean on my end.

One thing that sits outside this PR:

The :page-agent-handoff: attribute is documented nowhere a writer would look. I checked for a positive answer rather than assuming:

• No mention in any non-source file in docs-ui (only .github/CODEOWNERS, preview-src/, src/, and tests/ reference it).
• Not in the page-attribute reference comment block in docs-site — antora-playbook.yml:184 and local-antora-playbook.yml:132 document page-has-markdown, but there's no entry for page-agent-handoff.
• Zero usage across docs, cloud-docs, and rp-connect-docs.

To be fair to this PR: the attribute was already undocumented after #408, so this isn't a regression introduced here. But it does add a second thing a writer has to know — that the attribute exists and that it takes an optional ui value whose misspellings silently fall back to project instructions. Without a written home for that, the ui mode is discoverable only by reading src/js/13-agent-handoff.js.

Suggest a follow-up issue rather than blocking this PR: add page-agent-handoff (and its ui value) to the attribute reference block in the docs-site playbooks alongside page-has-markdown, so writers have somewhere to look before the docs team enables ui mode on real pages.

[micheleRP]

left one little suggestion