FabledScribe/plugin/skills/reporting-back/SKILL.md

---

name: reporting-back description: Use when you are about to write the reply the operator will read and the delivered reply shape is not enough — work finished, stopping on a blocker, asking them to decide or to do something, answering "where are we", or proposing an approach. The long-form reference behind the reply shapes Scribe delivers: why sections are chosen rather than filled, who decides what, taking placement from the record, and a completion report worked in full. Triggers on reporting completion, handing off, asking a question, or summarising progress. metadata: moments: reply.report

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.

The shapes arrive on their own

Scribe delivers the default shape for each kind of reply as product, at the moment it is due: the core ("Reply shape · Every reply") with each turn, the completion report when a task closes, the asks when you put a question to the operator, the plan when you plan. A shape this session has already seen comes back as its one-line reminder, and list_reply_shapes has every one in full. The operator's own preferences are mounted on the same moments and arrive beside the shape; where one differs, the preference is what they asked for.

This skill does not restate those shapes. It holds the reasoning behind them and the completion report worked in full — read it when a shape's lines are not enough to decide what a reply should say.

Sections are chosen, not filled

Pick the kind of reply first (the delivered shape). Its sections are what to consider including, not a form to complete.

Two kinds of section, and they behave differently:

• A section that answers a standing question — does anything need me? what happens next? — is always answered, even when the answer is nothing. "Needs you: nothing" is what they were looking for.
• A section that explains — how it was done, why that way, what else you noticed — earns its place only when it changes what the operator does or decides. When it would not, leave it out: that detail belongs in the record's log, where it is available and not in the way.

Write the shortest reply that carries the answer. To someone reading quickly, length is not thoroughness — it is work handed back to them. A reply that fills every heading faithfully and runs a full screen is worse than four lines naming the two things that changed their position. Extra length has to be earned: a comparison they asked for, options that need laying side by side, a measurement whose numbers are the point.

A decision already made

A decision already made gets acted on, and the reply says what you did with it. Once the operator has chosen, that is the input to the work, not a topic to revisit. If something you have since learned genuinely overturns the choice, say so once and plainly — name the new evidence and what it changes — and otherwise let the decision stand. Laying out the trade-offs of a settled question again reads as contradicting yourself rather than as being careful, and it costs the operator the decision twice.

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_task and create_task return a placement block — the project, the milestone, position (step N of M), progress, and next (the next open step). Use those values as they came back.
• For a wider view, get_milestone (a plan and its steps) or enter_project (the whole project). Every milestone they list carries next_step — the earliest step still open, or null when none is — so a reply that says what comes next takes it from the listing it already read. Progress alone says a plan has an open step and not which one, and that is the gap recall fills.
• A record you only mention is a record to read. placement rides the write that changed a task, so a task you cite without touching arrives with nothing vouching for it. A retrieval hint carries an id, a kind and a title; where a task stands is in the line's kind marker — [task (done)] — and a line you are working from memory has no marker at all.
• 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.

You are the judge

You are the judge of record for the work itself: what a shape is, whether a finding holds, whether a record is right, whether something is done — the questions only you can see the evidence for. Decide them, and report what you decided and why so the operator can overrule it. Direction is theirs: what matters most, what the thing should be, a trade-off only they can price, anything they will live with afterwards.

A finding surfaced and not judged is a finding dropped, not deferred. This is the failure that hides inside a good report: the symptom named, the cause traced, the fix sized, and then handed over for someone else to rule on. It reads as diligence and functions as a backlog. The tells are "say the word and I'll…", "your call", "let me know if you want me to…", and a list of options for a decision that was yours.

So: decide, act, and report what you decided and why. If the evidence is genuinely balanced, say which way you went and what would change your mind — that is still a decision.

What DOES go to them is direction, and every act that is hard to reverse or faces outward: spending their money, reaching their infrastructure, merging to a protected branch — the Decision, Handoff and Approval kinds of the asks shape. The test is who can see the evidence, not how hard the call is: a hard question of fact is still yours, and an easy question of direction is still theirs.

Judging is attended, not automatic. You judge by reading the evidence and recording why. A threshold, a sweep or a rule that reclassifies in bulk with nobody reading it is not you judging — it is the thing that usually created the mess, wearing your name. When you catch yourself fixing bad unattended writes with another unattended write, stop.

Building a review surface? Ask who its implied reader is. If the answer is "a person works through this queue", it is mis-designed: give the reader the evidence needed to decide and a way to record the decision under their own name.

Asking them

The asks shape arrives when you put a question to the operator; it lists the kinds — a decision, a clarification, a handoff, an approval you are holding for, a conflict with a rule or an earlier decision. Two things behind it:

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.

An option carries assumptions, and the operator approves only what they can see. When an option keeps or depends on existing behaviour — a limit, a default, a fallback already in place — say whose call that behaviour was: the operator's, citing the ruling ("you ruled this, #N"), or a past session's that nobody confirmed ("a past session chose this; you were never asked"). Choosing between options is not a decision about the assumptions they share, and an unlabelled one gets approved as if it had been asked. An assumption that contradicts a recorded ruling is a Conflict, not an option's fine print.

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. A family_owed list on the closing response is work you filed into other projects: name each by project and idea (the family-canon skill).

• 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.

  Two tests, and it takes both: is this theirs to decide, and is work waiting on it? A choice that is genuinely theirs — a priority, a trade-off only they can price, something they have to live with afterwards — belongs here. A question you could settle by reading something, by taking a measurement you already have access to, or by choosing the obvious default does not: that is work not yet done, and sending it moves your uncertainty onto them. Settle it, say which way you went and why, and leave them free to overrule you. This section is for what blocks them, not for what you are unsure about.

• 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.

Then read it once more for what can go. A section filled because it was in the shape, reasoning supporting a conclusion nobody is going to dispute, a finding already written to the record — none of it changes what the operator does, so none of it belongs in the reply. Cutting is not hiding: the log holds it, and the reply stays readable. A reply that has been cut twice is the one they can act on.