Skip to content

Questions: a little more context, and links to attached files open beside the thread - #1829

Merged
backnotprop merged 2 commits into
mainfrom
feat/question-context-and-file-links
Oct 10, 2026
Merged

backnotprop merged 2 commits into
mainfrom
feat/question-context-and-file-links

Conversation

@backnotprop

@backnotprop backnotprop commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

What

1. Questions carry context. The owner, answering an agent's questions: "Put context in these damn questions, please." The rules now say it literally, in every instruction set we give agents, from one source:

  • QUESTION_AUTHORING_GUIDE (packages/core/question-block.ts), pasted byte for byte into the plannotator skill's "Asking the reviewer questions" section, riding send_message's MCP description and printed verbatim by plannotator inbox --help.
  • The rules: never send a bare question, because the reviewer switches in cold, thinks at the level of the product, and does not know what you know. Say what the choice affects, what you know or tried, and why you recommend it, so they can decide without opening anything else. Be terse: one to three short sentences, plain words, no jargon or internal names. Add a screenshot (![alt](path)) for anything visual. Link a file that shows it better ([the mock](mock.html)); in the Inbox, attach it too, and the link opens it beside the thread.
  • The guide's example now follows the rule. It used to open with "Last-write-wins silently drops the loser", which is jargon.
  • The rest of the guide was trimmed so it grows little: 2,213 to 2,292 characters. Claude Code's 2,048-character cut of send_message's description now keeps every context rule and the whole - [x] rule (pinned in inbox.test.ts). The PFM reminder's example and rule say the same.
  • inbox --help's Inbox example now has a context line that links an attached file. The section adds one line about attaching and linking, and says that a link to a file you did not attach shows as "Not attached".
  • The install prompt's step 5 "Yes" branch gets the same rule in one sentence (ASCII).
  • The MCP instructions and the attachments description say that a link opens the file.

2. In the Inbox, a link to an attached file opens it beside the thread.

  • When a markdown or raw-HTML link in an agent message (body or question context) points to one of that message's attachments, the file opens in the side pane, the same as its tile. Focus moves into the pane, Escape closes it as before, and Enter on the link opens it.
  • The match happens on the client (packages/inbox/links.ts), against the attachment records the thread already has: the realpath or named_path, relative to the message's base_path and then the project root, as message images resolve. ?query and #fragment are ignored, and a percent-encoded path also matches. A bare file name matches only when exactly one attachment has that name.
  • No route takes a path, and nothing is fetched to decide.
  • A local link that names no attachment renders as inert text: muted, dotted underline, titled "Not attached to this message". It has no href, so a click goes nowhere and nothing is requested. In raw HTML, the <a> loses its href.
  • An attached link's tooltip names the file's path in the project ("Open design/mock.html beside the thread"), so a match by bare name shows which file. Its href is the window's own deep link, #thread=<thread id>&file=<attachment id>, so "Open in new tab", a Cmd/Ctrl/Shift or middle click, drag and copy open the same file. Viewer's resolveLocalLink lets an open resolution carry that href.
  • External http(s) links are unchanged.
  • The seam is Viewer's new optional resolveLocalLink (packages/ui/components/LocalLinkContext.tsx, documented in packages/ui/HANDOFF.md and README.md). Plan review, annotate and other hosts pass nothing and render exactly as before; a DOM test pins this.

Tests

  • apps/hook/server/plannotator-skill-reference.test.ts: the skill section equals the guide.

  • packages/server/inbox.test.ts: the 2,048-character cut keeps "without opening anything else", "no jargon", the image and link syntax, and the closing "Ask only" rule. 21 pass.

  • apps/hook/server/inbox-help.test.ts: the Inbox example parses with the store's parser, and its context carries the linked file.

  • apps/marketing/inbox-launch.test.ts: the prompt is ASCII and its other checks pass.

  • packages/inbox/links.test.tsx:

    • Matching: sender folder, project root, named_path, a bare name, percent-encoding and Windows paths. These do not match: another file, another folder, ../../../etc/passwd, and a bare name that two attachments share.
    • DOM (DOM_TESTS=1): an attached link (markdown and raw HTML) opens the pane; its href is the deep link and its tooltip the project path; a Ctrl click is left to the browser. An unattached link is an inert span with no href and nothing fetched. An external link keeps target=_blank and rel=noopener noreferrer. A Viewer without the seam is unchanged.
  • tests/e2e/inbox-message-links.spec.ts, Playwright against the compiled binary: click and Enter open the pane, the deep-link href opens the file in a new tab, focus moves into the pane, the unattached link is never requested, and the external link is unchanged. The full test:e2e:inbox run: 87 pass, 1 skipped.

  • bun run typecheck passes.

  • DOM suites for packages/ui, packages/inbox and packages/editor: 2,608 pass. In the full run, 4 DocBadges tests fail; they pass when run alone and this PR does not touch them.

  • bun run --cwd apps/guides-show check:manifest: in sync. scripts/dom-test-allowlist.test.ts and packages/shared/pfm-reminder.test.ts pass. After the review fixes, inbox-message-links, inbox-message-images, inbox-attachments and inbox.spec pass against a rebuilt binary (25 pass).

…side the thread

Guidance (one source: QUESTION_AUTHORING_GUIDE, pasted into the plannotator
skill, riding send_message's MCP description and `plannotator inbox --help`):
never a bare question; the reviewer switches in cold and works at a higher
level, so say what the choice affects, what you know or tried and why you
recommend it, in one to three short sentences, plain words, no jargon or
internal names; a screenshot for anything visual; link a file that shows it
better, attached in the Inbox. The guide's example now models the rule. The
install prompt and the help's Inbox section say the same in one line each.

Inbox window: a markdown or raw-HTML link in an agent message to one of that
message's attachments opens it in the side pane (focus moves into it),
matched client-side against the attachment records (packages/inbox/links.ts).
Any other local link renders as inert text titled "Not attached to this
message", with no href, so nothing is fetched. http(s) links are unchanged.
The seam is Viewer's optional resolveLocalLink (LocalLinkContext); plan
review, annotate and other hosts pass none and render as before.
…ing, link hrefs

- InlineMarkdown drops `cursor-help` (it leaked into the pinned guides.show
  stylesheet); the Inbox sets the help cursor in inbox.css.
- packages/inbox/links.test.tsx joins the CI DOM test list.
- The PFM reminder's question example carries a context line, and the
  reminder says: never a bare question; one to three plain sentences on what
  it affects and why you recommend it; a screenshot if visual.
- Guide: "the reviewer switches in cold, thinks at the level of the product,
  and does not know what you know." The lead and a few rules are shorter, so
  Claude Code's 2,048 cut of send_message's description now keeps the whole
  `- [x]` rule (pinned in inbox.test.ts). Skill pasted again.
- An `open` link resolution may carry an href. In the Inbox it is the
  window's deep link (`#thread=<id>&file=<att id>`), so a new tab, drag or
  copy opens the same file; a Cmd/Ctrl/Shift or middle click goes there.
- The attached link's tooltip names the file's path in the project.
@backnotprop
backnotprop merged commit 4860cc1 into main Oct 10, 2026
32 checks passed
@backnotprop
backnotprop deleted the feat/question-context-and-file-links branch October 10, 2026 23:32
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.

1 participant