[haowjy]

Changelog

• Changed: the AI's messages to the researcher lead with the point, run a few lines, and use Markdown lists and bold. Its plan arrives in at most five lines instead of plan.md pasted in, and its closing message lists results, then what to check, then what couldn't be done.

Why

The Conversation tab is now main's whole thread (#597), so main's messages are what the researcher reads first. They were walls of prose. Jimmy: "the message to research btw was extremely wordy and not organized well (it needed markdown...)", and "main.md is so bad, it should … consider the audience (researcher), and organize well".

The cause was the prompt. The Conversation already renders GitHub-flavoured Markdown (packages/run-view/src/chat/markdown.tsx). But main.md told main to write plan.md as "a few plain paragraphs… No step lists or counts", and then to send that text to the researcher. The harness's refusal said the same ("message researcher with the text of /work/main/plan.md"). The shared guide for researcher-facing words (words.md) only listed the words to avoid.

Design decisions

1. The guide to the researcher's words lives in words.md, the one file every role's system prompt shares. It now says who the researcher is: an expert in their field, not a programmer, reading in a side panel between looks at the images. It says how to write for them: the point first, a few lines, Markdown lists and bold, numbers with units, where to look, and no ids or paths. Ruled out: rules in main.md only, since workers write titles, notes and To check items that the same researcher reads.
2. plan.md stays main's memory; the researcher gets a five-line version. The message says what the run will measure, what in this input could change it, and what they'll see first. Ruled out: rewriting plan.md as a list, which would lose the reasoning a worker reads it for.
3. Main's closing message has a fixed order: results with numbers, then what to check first and where, then what couldn't be done. It gives no account of the run.
4. Everything stays generic. No anatomy and no micro-CT terms, so the same text reads correctly for another kind of workflow (workflows/core/agents/AGENTS.md).

Walkthrough

What the researcher reads

1. Setup: this branch, pnpm dev, and the runner, with a local run on deepseek-flash per AGENTS.md.
2. Open the sample page's Conversation while main plans. Then ask "What's your plan for this scan, in a couple of sentences?", and later "Is this the patella?" with a mark placed.
3. Expect: on main, the plan arrives as several paragraphs. On this branch, it arrives in a few lines with a list, and each answer opens with its yes or no.

Read in this order: workflows/core/agents/words.md, then main.md (Plan, Close), skills/researcher/SKILL.md, and the refusal text in packages/harness/src/tools/coordination.ts.

What changed

• words.md: a writing guide for the researcher, in place of a list of words to avoid.
• main.md: the plan message (five lines, not plan.md pasted in); when to message during a run; the closing message's order.
• researcher skill: an answer opens with its answer; "Write for them" points to words.md.
• coordination.ts: start_worker's refusal before the plan message no longer says to send plan.md's text.

Risk and where to look

• Breaks or changes: prompt text only, plus one refusal string. Live runs keep their snapshot of the old text. The harness change redeploys the runner, so merge when no demo or rehearsal run is live.
• Where to look: whether words.md's length is right, since it goes into every role's system prompt; and the five-line plan rule against what a worker needs from plan.md.

Knowledge layers, docs and deletions

• Docs: None. workflows/core/agents/AGENTS.md still describes where each file lives.
• Deleted: the rule "No step lists or counts" for what the researcher reads.

Contract changes

None.

Verification

• Ran: pnpm check (passes).
• Saw: no run on this text before merge. Jimmy chose to merge before the 6 PM PT code stop. A local A/B/C test (today's text, no message tool, this text) is running; its findings are in a follow-up. A cold read (p1750) found where an agent would misread the guidance, and fb80547 fixes those cases; the other gaps it found predate this PR (Main's role file and researcher skill: rules that conflict or leave main stuck #604). A fast pre-merge review was still running at merge.

Left out

• Whether main talks to the researcher through message or in its own reply text: A/B test under way; then Main writes a status update every few minutes while a run is live #596.

[haowjy]

Held past the 2026-11-04 code stop; not merging today. Next: the A/B/C test of main's messages (today's text, no message tool, this PR's text). Its findings go in Verification. Merge when no demo or rehearsal run is live, since the harness change redeploys the runner.

[haowjy]

Evidence after merge: a local A/B/C test on deepseek-flash, with the same two researcher questions in each run.

• Plan message: today's text (A) sent 402 words in four paragraphs. This PR's text (C) sent 119 words.
• Answers: A's ran 194 and 200 words. C's ran 80 and 94 words, and each opened with its answer ("Most likely yes: …").
• Markdown: lists and bold rendered properly.
• Without the message tool (B): main restated the plan inside its answer, wrote 40–66-word updates and never answered the second question before the deadline. The cause wasn't isolated, so B is inconclusive.

Findings: work dir ab-message-tool.md (session c1703).