verbose-updates

Verbose Updates

When the user invokes this skill, they are signaling that they are context-switching, not paying close attention to every turn, or otherwise unable to carry conversation state in their head. Following the communication protocol below is what keeps progress moving in that state. Failure to follow it produces slow progress, wasted tokens, and user frustration -- the user has to re-orient on every reply, push back on under-specified hand-offs, and re-teach the agent what it should already be doing.

The base assumption is that the user only reads end-of-turn messages -- they are the auto-loaded surface for turn-level communication (see ../hand-off/references/communication-framework.md). Mid-turn narration and intermediate tool calls are on-demand at best; nothing important may live exclusively there.

This skill operationalizes the turn-level side of the communication framework. The shared glossary -- work-unit, auto-loaded vs on-demand context, three-part end-of-turn template, State A / State B, orientation moment, self-contained briefs, provenance triad, argument-based invocation modes -- is canonical at ../hand-off/references/communication-framework.md. Definitions live there; this file describes only how the protocol applies them.

The protocol is built around one central rule: every end-of-turn reply uses the framework's three-part template. The other rules support that template by specifying what each of its parts must contain.

The template depends on the agent maintaining awareness of the current work-unit. If you cannot name the current work-unit, you cannot write the template -- ask the user to clarify it before continuing.

The end-of-turn template (required)

Every reply that ends a turn -- whether parking work, handing back for a decision, or just confirming a small change -- uses the framework's three-part template: What changed / Where it sits / Required user action. The framework defines the parts; this section specifies what each part must contain at the operational level.

The template is not optional and not negotiable. Skipping a part means the user has to ask for it, which is exactly the friction this skill exists to prevent.

What changed

Name the artifact and the action. Vague is wrong:

• BAD: "Done."
• BAD: "Renamed the file."
• BAD: "Fixed it."
• GOOD: "Renamed .claude/skills/<old-name>/SKILL.md -> .claude/skills/<new-name>/SKILL.md and added it to the default p4 CL."
• GOOD: "Locked Fluffalo as a sourceless atom in .claude/skills/localization-domain/sourceless_glossary.yaml."

If multiple things changed, list them, but each line still names the artifact.

What changed is measured against the current work-unit, not the previous turn. A turn that advances the unit produces a substantive What changed; a turn that merely confirms or clarifies still names what was confirmed in work-unit terms (e.g. "Confirmed flow is not in the glossary"); a turn whose answer does not relate to the work-unit at all is evidence either that the unit is unclear (ask) or that the work is not done (keep going).

Special case: the first update after the skill is invoked. This is an orientation moment (see framework). The act of invoking the skill is technically the current turn, but the user is re-orienting against work that already happened -- the meaningful question they bring is "where are we?", not "what did the skill invocation just do?" So the first What changed after invocation summarizes the substantive work of the preceding 1-3 turns (whatever it takes to anchor the user in the current state), not the trivial fact that a skill was invoked. Name the artifacts that changed, the decisions that landed, and any handoffs in flight, exactly as those updates would have read if the verbose template had been active all along.

Where it sits

How does this change relate to the rest of the in-flight work? The user has been tracking a broader state -- a CL of staged files, a sequence of atoms locked, a decomposition pass mid-flight, a plan with parked decisions. The reply re-anchors the user in that broader state every time:

• "This is the 14th file in the default p4 CL alongside the loc-ops glossary work."
• "Bucket regenerated; composed_count went from 2,822 to 2,836 (+14 new compositional decompositions)."
• "Skill rename only; no other references to the old name in .claude/ or tmp/."
• "Test suite still at 818 passing."

When the change is genuinely standalone, say so explicitly ("standalone change, no in-flight context"). Don't leave the user guessing.

Required user action

The framework defines State A and State B as the only two end-of-turn states. This section specifies the operational rules:

State A -- user action required. Name one concrete next decision, file to review, or question in one sentence.

• GOOD: "Required action: confirm whether to ship the staged 14 files as one Mix CL or split the skill change off."
• BAD: a numbered list of three open questions (the user picks one; the others rot).
• BAD: silence (the user has to ask).
• BAD: "Required action: none. Continuing on Phase 3.2." -- declaring no action required while implicitly handing off more work to yourself. If you are continuing, the turn is not over.

If two decisions genuinely need to surface, pick the more urgent and park the second in the project plan with a note, not in the chat.

State B -- all requested work complete - ready to end session. Use the exact phrase. The phrase is heavy on purpose -- before claiming State B, pause and enumerate every item the user has requested across the active session. Include every direct request, every parked decision the agent surfaced and the user answered, every plan-defined unit the agent committed to completing this turn, and every artifact the agent said it would produce. Then verify each item against live state, not memory.

A distracted user trusts the classification. A false State B claim leaves requested work undone, and the user has no signal to push back. If the user discussed three things and the agent did two, the agent is in State A -- the third item is the required action, not a forgotten one. The cost of being wrong on State B is silently abandoned work; the gravity of the phrase is what makes the introspection step honest.

The classification is binary. If the agent is not confidently and verifiably in State B after the enumeration, it is in State A and owes the user a concrete action. If you have more work, do not end the turn; do the work.

Transitioning between work-units

In a multi-work-unit context -- a plan with phases, a sequence of tasks, a staged migration -- turns frequently span work-unit boundaries. When a single turn both completes one unit and begins the next, the reply contains TWO end-of-turn updates back-to-back, each following the full template:

1. The first update describes the completion of the just-finished work-unit. What changed is the closing-out summary of that unit's progress. Where it sits notes that the unit is complete. Required user action names the next unit in the plan, explicitly.
2. The second update describes whatever work was already accomplished moving into the next work-unit (often partial -- the agent picked up the next unit, did some work, and now ends the turn). What changed is what advanced in the new unit. Where it sits anchors to the new unit. Required user action is the next decision within that unit.

Splitting the reply this way keeps each update scoped to a single work-unit, so a user reading only end-of-turn messages can track unit boundaries cleanly.

Asking the user for permission to move on to the next work-unit is an anti-pattern. The plan or phase sequence already authorizes the transition -- moving forward is the default. "Should I proceed to the next phase?" forces the user to confirm work that does not need confirmation, and the cost is one round-trip the user did not need to pay. If the next unit raises a genuine decision (a scope ambiguity, an unforeseen risk, a missing input), surface that decision in the second update's Required user action slot directly; do not use it as a permission gate on the transition itself.

Supporting rules

These specify what the template parts must contain. They are not numbered as the user-facing surface -- the template is the surface; these are implementation notes.

Always name specific file paths

Every artifact mentioned gets its absolute or project-relative path. "I updated the plan" -> name the plan path. "I wrote a draft" -> name the draft path. "I edited the config" -> name the config path. "Review the bucket" -> name the bucket file.

The agent already knows the path; making the user remember which artifact is the current surface is exactly the burden this skill removes.

Self-contained briefs (always, not just at boundaries)

Whenever the skill is invoked, treat every turn as if the user is reading cold -- the framework's self-contained briefs principle, applied per-turn. Do not say "as I mentioned earlier"; do not reference prior turns by index; do not assume the user remembers a decision from three turns ago. The plan, handoff, and ticket are the durable substrates; the live conversation is not.

If a system-reminder describes resumed state ("queued next concrete action is X"), verify against live state before acting on it. Stale carry-forward is common -- restate the actual next decision and explicitly flag the stale note rather than re-doing already-completed work.

Auto mode means execute, not chase

Auto mode authorizes work without asking. It does NOT authorize spinning on already-done work, fabricating next steps when the real next step is a user decision, or doing extra work the user did not request. When the next decision is genuinely the user's (architectural choice, policy decision, audit verdict), surface it concisely in the Required user action slot and stop.

When the user asks for X, deliver X. Do not also re-issue Y "while I'm at it" -- that produces stacked-deliverable replies that violate the template's single-required-action rule.

Capture provenance, not just outcomes

When recording a decision in a durable artifact (project plan, decision log, audit log), use the framework's provenance triad: surface / finding / follow-up. Outcomes alone are not enough; the next agent who picks up cold cannot reconstruct what surface revealed the smell. The project's plan / handoff / decision-log is the right home for these -- chat memory is not durable.

Argument-based invocation modes

/verbose-updates <arg> switches from the default end-of-turn template to a focused report shape selected by the argument. Default invocation (no argument) continues to use the standard three-part template above. The framework's argument-based invocation modes rule applies: each mode names the question it answers, defines reply shape and length, and states whether it replaces or supplements the default.

Recognized arguments:

strategy -- goal + trajectory check

Answers exactly three questions, in this order, as a single short reply:

1. What is our current goal? State the work-unit in one sentence -- the falsifiable thing we are trying to make true.
2. Are we on track to hit that goal? Yes / no / partially, with the evidence in one sentence (what's done vs what remains; any blockers).
3. Are we doing what will most quickly help us achieve our goal? Yes / no, with one sentence on the next-action choice -- if no, name the action that would be faster and why we are not doing it.

Keep the whole reply tight (3-6 sentences total). This is a sanity check the user is asking the agent to run on itself; verbose elaboration defeats the purpose. If any of the three answers is genuinely unclear, say so explicitly rather than padding.

Replaces the standard three-part end-of-turn template for this turn.

Adding new argument modes

Per the framework's rule, each new mode must: (a) name the specific question the argument answers, (b) define the shape and length of the reply, (c) state whether it replaces or supplements the default template. Keep modes orthogonal to each other -- the user should never have to decide which of two overlapping modes to invoke.

When NOT to apply

These rules are about reply shape, not about ignoring the user. Do not over-apply:

• If the user explicitly asks for a structured report, deliver one.
• Project-specific protocols (audit logs, surface/finding/follow-up shape, domain terminology) live in the project plan; this skill is the generic substrate they extend.