bvandeusenandClaude Opus 5
6eb5ef5c73
A session's go-ahead request sat inside a completion list as "Blocked by the permission check", and the operator read it as a fault rather than a question waiting on them. The reporting-back skill now puts any action held for a yes under a section headed "Approval requested", near the top of whatever reply it is: each change numbered so part can be approved, why it needs them, how it is undone, and what happens after. The Asks table gains an Approval row, and the completion report's "Needs you" points at the section. test_reporting_back_skill pins the heading and the row. Plugin version minted: 2026.09.15.1921. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy
7.6 KiB
name, description
| name | description |
|---|---|
| reporting-back | Use when you are about to write the reply the operator will read — work finished, a task marked done, stopping on a blocker, asking them to decide or to do something, answering "where are we" / "what's next", or proposing an approach. Shapes the reply around where the work stands (which task, what changed, what needs them, what comes next) instead of the order you did things in. Triggers on reporting completion, handing off, asking a question, or summarising progress. |
Reporting back
Your reply is where the operator finds out what happened. They were not there while you worked: they don't hold the files you read, the names you used or the order you did things in. A reply that follows your path is accurate and still unreadable to them. Shape it around where the work stands.
Pick the kind of reply first (the tables below), then fill its sections. The sections are what lets the operator find things at a glance, so keep them even when one is short — "Needs you: nothing" is an answer they were looking for.
Every reply
- Conclusion first. The verdict, the result, or the question — before the reasoning that supports it.
- One topic per section. Two things the operator raised get two sections.
- Make priority visible. Bold the few things that matter; let the rest be plain.
- End with the ask, in bold — the one thing they need to decide or do. If there is nothing, say so.
- A request for approval gets its own section, headed "Approval requested". Whenever you are holding an action until the operator says yes — a permission prompt their client raised, something hard to undo, a change you have prepared and not made — put it there, near the top, whatever kind of reply this is. Inside a progress or completion list it reads as a status line, and the operator does not see that you are waiting on them.
- Plain words. Use the operator's vocabulary, not the names you coined while working. If a term has to appear, explain it once.
- Place the work in Scribe. Name the task, issue or milestone it belongs to, by id and title (using-scribe: "Name the record, never just its number").
Take the placement from the record
A remembered milestone title or "next step" reads exactly like a real one when it is wrong. So take placement from Scribe:
update_taskandcreate_taskreturn aplacementblock — the project, the milestone,position(step N of M),progress, andnext(the next open step). Use those values as they came back.- For a wider view,
get_milestone(a plan and its steps) orenter_project(the whole project). - Work with no task behind it: say so plainly — "this wasn't tracked as a task" — and offer to record it. An honest "untracked" is a placement too.
The operator's own shapes come first
The shapes below are defaults. An operator may have changed some of them — a
section they always want, an order they read faster, a kind of reply they want
shorter — and those changes are preference records. Where a preference and a
default differ, the preference is what they asked for.
- A completion report brings its preferences with it. Closing a task with
update_taskreturns them asreply_preferenceswhen the operator has any; thereport_backline says so. Nothing to search for. - Every other reply, ask before writing it. A finding, a decision, a
handoff, a "where are we" — no tool call comes before these, so nothing
hands their preferences over. Once you know which kind of reply you are
writing,
search(content_type="rule")for it in the words of that moment — "writing a decision for the operator", "handing off to the operator" — and follow any preference that comes back. Nothing coming back means the default shape stands.
Reports — work happened
| Kind | Sections |
|---|---|
| Completion | Where this sits · What now works · How / why · Needs you · Next |
| Finding (a problem you found and did not fix) | Symptom · Cause · Size of the fix · Offer to fix it |
| Blocked / failed | What stopped · What you tried · What you need from them |
| Progress (mid-work) | One or two lines: where things are, what's next, any blocker |
| Where are we | The milestone and its progress · Done · Open · Needs you · Next |
Asks — the operator needs to act or decide
| Kind | Sections |
|---|---|
| Decision | The question first · 2–4 options, each with what it changes · recommendation first |
| Clarification | "My reading is X · the gap is Y · unless you say otherwise I'll do Z" |
| Handoff (only they can do it) | The action · why it needs them · what it unblocks · what you'll do after · any way to skip it |
| Approval (you are ready to act and holding for a yes) | Approval requested: exactly what happens once they approve, one numbered item per change so they can approve part · why it needs their yes · how it can be undone · what you'll do after |
| Conflict (what you're about to do clashes with a rule, a plan or an earlier decision) | What it says · what you were about to do · where they clash · A or B? |
Before asking, check whether you can find the answer yourself — something that can be read or looked up is a fact to check, not a question to send.
Answers — the operator asked something
| Kind | Sections |
|---|---|
| Explanation | The answer first · then the evidence, pointing at what they could open to check it |
| Evaluation ("can we / should we") | Verdict · What exists · The gaps · Recommendation |
Proposals — shaping future work
| Kind | Sections |
|---|---|
| Options | 2–3 approaches · the trade-off of each · one recommendation |
| Plan | Goal · Steps · Open questions — for review before starting (writing-plans) |
| Review | Findings ranked by how much they matter, one per item |
The completion report, in full
The most common reply, and the one most often written in the order the work happened. The shape:
Where this sits: milestone 12 "Move the backups offsite", step 3 of 5. Task #340 "Schedule the nightly sync" is done.
What now works
- The nightly sync runs at 02:00 and copies the photo library to the remote store.
How / why
- Used the scheduler the other jobs already use, so there is one place to look when a job doesn't run.
- Verified by running it once by hand and checking the remote copy's size matches the source.
Needs you: nothing.
Next: #341 "Alert when a sync fails". Starting it unless you redirect.
Notes on each section:
- Where this sits — from
placement. If the work isn't under a milestone, the task alone is enough. - What now works — outcomes the operator would notice: "You can now…", "X no longer…". The files and steps behind them belong in the task's log.
- How / why — only the decisions worth knowing, plus how it was verified. If something could not be verified, say what and why here rather than letting it read as passed.
- Needs you — an action, an approval, a decision, or "nothing". If it's an action, give the reason with it. An approval you are holding for also gets its own Approval requested section, and this line points at it.
- Next — from
placement.next, or say the milestone is finished. If you found something you didn't fix, the offer to fix it goes here.
Before sending
Read the reply as the operator will: someone who wasn't there, reading quickly. Can they tell what was done, whether anything needs them, and what happens next without asking a follow-up? If not, the sections are what's missing — not more detail.