report skill and communication rule: write every message for a reader who did not watch the work #26

Before you file

• I searched the existing issues.
• I looked in Discussions under Ideas.

Kind

New skill, plus a rule that routes to it and a change to implement-spec

Component

Something else (a new report skill, a new rules/communication.md, and the hand-back of implement-spec)

Proposed behaviour

Every message the agent writes to the author, in any skill or none, is written for a reader who did not watch the work. The plugin gets three things to make that so.

1. A rule, rules/communication.md, loaded by the two hooks into every session and sub-agent. Short, about 1,500 characters, within the 10,000-character hook budget (5,966 used today). It says what every message to the author must do, and names the skill below for the heavy moments, as the rules memory of 2026-10-14 says a rule should: route, and cover only what no skill can. The bullets, each with its why:

• Write for a reader who did not watch the work. The author sees only the final message, never the tool calls.
• Lead with what failed, what was not run and what was assumed, each as its own sentence saying what it is and why it matters. rules/collaboration.md already says "bad news first"; this says what bad news is.
• Name a thing by what it is, never by a label coined during the work. Quote the line when it is text. A label only works for someone who was there.
• When asking for a decision, state what is being decided, the options in plain words, then the recommendation and the reason. "Your call" after a dense paragraph is not a question the author can answer.
• Say what a result means before the number. A score or a cost is not a finding.
• Do not narrate tool calls, or list what is still pending, unless the author asked.
• Hand back, ask for a decision, or report a run with /freethinking:report.

2. A skill, report (name open), that writes the message when there is something to deliver. A skill, not only a rule, because a skill body can hold worked examples and a fixed shape per situation, which the rules budget cannot, and because the agent can reach for it on purpose: "I have something to deliver, write it the report way." It takes a mode as its first argument, and picks the mode from the situation when none is given:

• handback: after a piece of work. Problems first, one bullet each for a failure, an unfixed finding, a stopped task or an assumption made on the author's behalf, saying what it is, why it matters and what the options are; then what was done; then the files; then the next step. This replaces the report shape in step 6 of implement-spec, which today puts Done first and packs unfixed findings into one "carried:" clause.
• decision: when the author has to choose. What is being decided, the options with what each costs, the recommendation and why, then the question.
• status: when asked what is going on. What is running, what it is doing, what finished and with what result, nothing about what is "pending".
• answer: when the author asked what something is or why something happened. What it is, in plain words, before what to do about it.

Each mode carries one before-and-after example taken from the transcripts below. The skill is invoked by the agent when it is about to deliver something, and by the author as /freethinking:report [mode] to have the last message rewritten.

3. implement-spec, pr, bugfix and start-task hand off to the skill at their hand-back points instead of carrying their own report wording, as the no-cross-skill-internals memory of 2026-10-14 says. The executor's Summary and the reviewer's Findings keep their shapes, since they are agent-to-agent; the orchestrator translates them for the author rather than pasting them.

Proof. Eval cases, run with the no-plugin baseline (--ablation with-without) since this is a rule change: a case where a check fails and one where a check cannot run, grading that the final message opens with that fact and says what was not run, plus a not-contains regex for narration openers; a case where the author must choose, grading that the options are listed before the recommendation; a tool_used grader that the agent invokes the skill on a non-slash prompt. The implement-spec works-one-wave case gets a grader on the new hand-back shape. The rule goes in the README rules table and the component dropdown of the four issue forms.

Deferred, to a spike once the rule has run for a few sessions: a force-for-plugin output style (main session only, overrides every teammate's own style, drops Claude Code's coding instructions unless told to keep them) and a SubagentStop hook that rejects an executor Summary missing its sections (the only mechanism that can block a message, but only on a shape a script can check).

Motivating case

Eight sessions on this repository between 2026-10-06 and 2026-10-15 were read end to end. Of about 400 human turns, 27 were the author asking the agent to decode or expand its own previous message, one turn in fifteen. On 2026-10-13 the author wrote: "i need less of this AI ultra summarized stuff. half the time i barely understand what you're saying." The turns cluster into five habits:

• Labels in place of explanations. A wave report on 2026-10-13 listed its follow-ups as "the README unit-test list, the executor's launcher wording, and the eval cases' write-grader gap"; the author asked what that meant. The same day: "the fit question" and "the three code-changes cases". On 2026-10-09 a design decision was settled in one clause, "2.1 read Requirement 2.4 through the design's flowchart, so a standalone change is proved by the test it wrote", and the author replied "use more words and explain the 2.1 issue as if i'm an exec and you need me to make a decision". Long messages had this as often as short ones.
• Decisions requested without the material to decide. "Your call on priority." "I'll accept it unless you say otherwise." "What would you like to clarify about proposal D?", answered with "What's the options so i can make a better decision?". The "ultra summarized" complaint followed a triage paragraph that bundled type, priority, area and a new milestone into one block.
• Bad news buried under good news. The implement-spec report shape puts Done first. The wave 0 report of 2026-10-13 16:01 had "make check: 9 tests, 3 fail" as the third bullet under Tests and four unfixed findings in one 120-word sentence, while "all fixed in one attempt each" and "two executors and read back" got full lines. The author asked to be taken "through each follow up but explain it a little more detail, what the fix is and what the solution might be so I can input my reasons". rules/collaboration.md already says "bad news first"; the template contradicts it.
• Narration instead of substance. "The executor is running. While it works, nothing else is pending." "Waiting on 1.1." After a message that said what had finished but not what was still going, the author asked "what is still running?".
• Metrics instead of meaning. Eval timeouts were reported as run counts, a score of 0.83 and costs in cents; the author asked "what are the cases doing, what are the prompts?".

The only fix so far is a personal memory file written on 2026-10-13. It reaches no teammate, no sub-agent and no eval run, and three of the examples above happened after it was written.

What a plugin can ship, from the Claude Code docs (read 2026-10-15):

Sources: code.claude.com/docs/en/output-styles, /memory, /hooks, /sub-agents, /skills, /plugins/manifest-reference, /plugin-evals. Transcripts are in ~/.claude/projects/ under the four project folders for this repository; the turns quoted are dated to the minute.