From 0595904175d398dffe1c76d15fefe830862bcbc0 Mon Sep 17 00:00:00 2001 From: Dotta Date: Sat, 7 Nov 2026 13:26:46 -0600 Subject: [PATCH] fix(skills): teach the board skill how people find things in the web UI Asked how to quickly find tasks without leaving their page, the chat agent had no source describing quick search: it searched for docs, said it did not know the UI, and told the person to ask in chat instead of naming Cmd/Ctrl+K. Document the command palette, its search operators, the Search all handoff to full search, and that the agent cannot drive the person's browser. Add a test that ties the documented shortcuts to the palette's actual key bindings. Co-Authored-By: Claude Opus 5.5 --- .../__tests__/board-skill-ui-guidance.test.ts | 40 +++++++++++++++++++ skills/paperclip-board/SKILL.md | 13 +++++- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 server/src/__tests__/board-skill-ui-guidance.test.ts diff --git a/server/src/__tests__/board-skill-ui-guidance.test.ts b/server/src/__tests__/board-skill-ui-guidance.test.ts new file mode 100644 index 00000000000..2aa7247c80c --- /dev/null +++ b/server/src/__tests__/board-skill-ui-guidance.test.ts @@ -0,0 +1,40 @@ +import { readFileSync } from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../.."); +const read = (relPath: string) => readFileSync(path.join(repoRoot, relPath), "utf8"); + +// Chat agents answer "how do I find X?" from the board skill; without this section they +// had no source for the web UI's quick search and told people to ask in chat instead. +describe("paperclip-board skill web UI guidance", () => { + const skill = read("skills/paperclip-board/SKILL.md"); + const palette = read("ui/src/components/CommandPalette.tsx"); + const section = skill.slice(skill.indexOf("## Finding Things in the Web UI"), skill.indexOf("## Presentation Rules")); + + it("documents the quick-search shortcut the command palette actually binds", () => { + expect(section.length).toBeGreaterThan(0); + expect(palette).toMatch(/e\.key === "k" && \(e\.metaKey \|\| e\.ctrlKey\)/); + expect(section).toContain("**Cmd+K**"); + expect(section).toContain("**Ctrl+K**"); + }); + + it("documents the handoff to full search and the search route it opens", () => { + expect(palette).toMatch(/event\.key === "Enter" && \(event\.metaKey \|\| event\.ctrlKey\)/); + expect(palette).toContain("Search all for"); + expect(section).toContain("**Search all**"); + expect(section).toContain("Cmd/Ctrl+Enter"); + expect(read("ui/src/App.tsx")).toContain(' { + expect(section).toMatch(/cannot press keys, focus fields, or open the palette/); + }); + + it("is discoverable from the skill description", () => { + const frontmatter = skill.slice(0, skill.indexOf("\n---", 4)); + expect(frontmatter).toContain("finding things in the Paperclip web UI"); + }); +}); diff --git a/skills/paperclip-board/SKILL.md b/skills/paperclip-board/SKILL.md index c81966566a6..75e8bd2fdb0 100644 --- a/skills/paperclip-board/SKILL.md +++ b/skills/paperclip-board/SKILL.md @@ -3,7 +3,7 @@ name: paperclip-board description: > Manage a Paperclip company as a board member via chat. Use when the user wants onboarding, company or agent management, approvals, task monitoring, cost - oversight, or work product review in the Paperclip control plane. + oversight, work product review, or help finding things in the Paperclip web UI. --- # Paperclip Board Skill @@ -558,6 +558,17 @@ curl -sS -X PUT "$PAPERCLIP_API_URL/api/issues/{boardIssueId}/documents/decision ``` 2. Also update the local file at `./artifacts/decision-log.md`. +## Finding Things in the Web UI + +When someone asks how to find, search for, or jump to tasks, projects, or agents themselves (for example "how do I quickly find X without leaving what I'm doing?"), tell them about quick search before or alongside listing results here: + +- **Quick search:** press **Cmd+K** (macOS) or **Ctrl+K** (Windows/Linux) on any board page, or click the search icon at the top of the sidebar. It opens over the current page, so they do not lose their place; Esc closes it. +- Type words to match tasks, projects, and agents. Search operators narrow the results, for example `status:backlog`, `status:todo`, `assignee:me`, `project:"Launch"`, `label:bug`, `priority:high`, or `updated:>7d`. +- Choose **Search all** (or press Cmd/Ctrl+Enter) to open the full search page (`/{prefix}/search`). It keeps the typed text and operators as filters and adds comments, documents, and artifacts. +- Results only include what that person is allowed to see. + +You cannot press keys, focus fields, or open the palette in their browser; describe the steps for them to take. You may also offer to list the matching items in chat with links. + ## Presentation Rules - Use markdown tables for lists (agents, tasks, costs)