Report progress

Long work fails the reader in one of two ways, and both of them read as normal. The first is silence: forty minutes pass, something is happening, and the user cannot tell what, where, or whether it is still happening at all. The second is worse because it looks like the opposite — fluent narration that relays a child agent's self-report as established fact, so "all tests pass" arrives in the user's lap having never been run by anyone who could see the result.

Both leave the same hole: the reader cannot answer what is done, what is running, and what do I now know that I did not before? This skill fills that hole with a fixed shape, a line between verified and claimed, and a checklist that can be run over a report that has already been written.

It owns the report. It does not own the work, the child agents, or the truth about their state — it consumes that from agent-lifecycle. It is not a summary of a diff; that is describe-changes. And it is not a substitute for lifecycle telemetry: a well-written report about children you cannot observe is a well-written guess.

What "forced" means here

A skill is instructions. It cannot make a model do anything: nothing in this file executes, intercepts a turn, or holds back a message that skipped the report. A skill that implies otherwise is making exactly the unbacked claim this one exists to stop.

What a contract can do is remove the ambiguity that a vague report hides behind. This skill fixes the shape, names each omission as a specific failure with a consequence, and ends in a checklist that a reviewer — or the author, one minute later — can run against the text. So "forced" here means: there is no ambiguity about what was owed, and no way to claim compliance without producing the evidence. A missing section is visibly missing. An unlabelled number is visibly unlabelled. That is the whole mechanism, and it is enough, because the failure mode it addresses is not inability — it is a report that was never checked against anything.

The mechanical half, which is not this file

A separate, optional gate can hold a turn open when a report is owed and missing. It is a Claude Code Stop hook carried in this pack's adapter directory (adapters/claude-code/report-progress-gate.mjs), with its own installer beside it. It is off until a user installs it, and gone when they run that installer with --remove. How wide it arms is a level the user chooses with --coverage 1|2: a new install gets 1, and re-running the installer to update keeps whatever level is already installed, so updating the pack never changes that level. The paragraphs above are unchanged by it: this file still executes nothing, and nothing in this skill can install the gate or arm it on a user's behalf.

• H6. Nothing in this skill installs or arms the gate. The user runs its installer, or nobody does, and no project that adapts this skill adds a step that does it for them.

What arms it. At coverage 1, one thing: a subagent dispatched through the Agent tool. At coverage 2, three things, and nothing else: a subagent started in this turn (any kind, foreground or backgrounded); a skill the user has listed as an external agent, matched by exact name; and a change in the harness's own list of background work between this turn's end and the last one — something appeared, or something that was running is no longer listed. A task that is merely still running arms nothing, so a dev server left in the background does not make every turn owe a report. On an armed turn it reads the final message and returns {"decision":"block"} when the shape is absent, holding the turn for one more round so the report can be written. It has an observe mode that reports what it would have blocked and never holds anything. It blocks at most once per turn at either level and then stands down, because Claude Code ends a turn after 8 consecutive blocks and that budget is shared with every other Stop hook on the machine. What holds that ceiling is the gate's own record of a block it spent, which nothing inside the turn can erase, and a UserPromptSubmit hook the installer writes beside it, which clears the record when the next turn starts. A turn that hook does not fire for cannot block while an earlier turn's block is still on record. A gate installed before that hook existed keeps its old behaviour until the installer is re-run: there, a re-arm later in the turn is stopped only by the harness's own stop_hook_active.

What it can check. That a "what is done", a "what is running" and a "what is next" section label are present; that a running row carries a literal state and a freshness token, or that the exact no-evidence sentence below stands in its place; and that an empty section says so. Where the harness listed work as still running, it additionally refuses a report that says "Running: none" or that claims there is no lifecycle evidence — that is contradiction detection, not verification: it catches a report denying something the harness stated in the same payload, and it cannot refuse an honest report, because an honest report about n running tasks says neither of those things. A denial is a running section with no row in it; a row carrying a state and a freshness stands, whatever words sit beside it. It is string matching, and that is the only reason it is enforcement rather than more instructions — no model sits in its path, so there is nothing there to talk round.

What the bar is. One row per unit the harness itself registers. A workflow of twelve agents owes one row, not twelve: twelve is not a number the gate can see, the parent cannot observe those children's state, and twelve rows carrying invented states would be rule 5's invention wearing a status block — produced by the gate meant to prevent it.

What it cannot check. Whether any number in the report is real. It cannot tell whether npm test was ever run, whether child-7f2 exists, or whether "40s ago" was an observation rather than a guess. A message that satisfies the gate can still be a fabrication, and the five rules and the checklist at the end of this file are what catch that. The gate replaces neither, and a passing turn is not a verified report.

What it cannot see at all, so that nobody mistakes its silence for a clean bill: a foreground external agent — a bare codex exec — unless the user listed the skill that runs it, because the gate does no matching of command text, ever; the individual children of a workflow; background work that starts and finishes inside one turn; and how long anything has been running, because no hook event carries a clock. A disappearance from the harness's list is not a completion and the gate never reports it as one — terminal states belong to agent-lifecycle. Its marker is also keyed by session rather than by turn. So a turn that armed and then died without a Stop costs one block for work the turn did not do, and so does a background result arriving during a trivial turn. A session resumed in a fresh process does not cost a block at coverage 2: a SessionStart hook the installer writes on matcher resume notes the resume, so the old process's work is not read as gone.

The five rules

They are this skill's hard lines: rule 1 is H1, and so on to rule 5, H5. A project that adapts the skill may make one stricter, never looser.

1. H1. Verified and claimed are different words. Every number in a report is one of two things: a result the reporter produced by running a command it can name, or a claim somebody else made. Never let the two share a sentence. A child agent's "all tests pass" is evidence that it said so; re-run at the boundary, or label it unverified and move on.
2. H2. Report state, not activity. Three sections, always: what is done, what is running, what is next — each carrying a count or a concrete artefact. "Working on it" describes the reporter's experience, not the system's state, and a reader cannot act on it.
3. H3. Name the user-facing consequence, not the code change. "Every correctly-installed Yarn 1 repository was reported broken" tells the reader how much to care. "Fixed the receipt path" does not, and the reader has no way to recover the difference.
4. H4. Corrections are first-class and plain. When something already reported turns out to be wrong, say so in one sentence, at the point it matters, and continue. Repairing it silently spends the trust every other line in the report depends on.
5. H5. Nothing-to-report is a valid report; invention never is. "No commits landed yet; the build is still running" is complete and useful. Predicting a pending result, or describing what a still-running agent "should have" produced by now, is the failure this rule exists to stop. An ETA labelled as an estimate with its basis (H8) is not that failure: it says when the work may end, never what it will have produced.

Where "what is running" comes from

agent-lifecycle owns the authoritative state of a child agent — identity, literal state, activity, freshness, terminal cause. Where that evidence exists, every row in the running section is sourced from it and from nothing else. Where it does not exist, guessing is banned, and agent-lifecycle specifies the exact sentence to print instead of a running section:

Background work visibility unavailable; state unknown.

Use it verbatim. A plausible-looking row about a child you cannot observe is the invention rule 5 forbids, wearing a status block's formatting — and it is more convincing than plain silence, which is what makes it worse.

A percentage, an ETA, and updates nobody has to ask for

When the reader has asked how far along the work is or when it will be finished, or updates run on a cadence (B1), the report carries a head line, directly under its first line and above the three sections: the percentage with its basis, then the ETA as a clock time with its basis. It adds to the shape and changes nothing in it. The three sections are still owed, and outside a cadence, a report nobody asked for a percentage or an ETA carries no head line. The percentage counts a register of the work (B3) in one unit, and its "in flight" is that register's count of items started: task metadata, never a running row, which still comes from lifecycle evidence alone (B7). references/percentage-eta-cadence.md has the head line's shape, the arithmetic, the clock commands and the cadence.

Two hard lines come with it, for the two numbers easiest to invent: one nobody measured, and one about the future.

• H7. A figure nobody measured is reported as not measured, with its reason, never as 0. Zero is a measurement. Written for a figure nobody took, it reads as a result.
• H8. An ETA is an estimate, and says so. It is labelled as one and carries its basis: the items, what each was costed at, and the agents it is divided by (S3). Unlabelled, an ETA is a forecast written in the grammar of an observation, the prediction rule 5 forbids.

Updates on a cadence (B1) come without being asked: a reader who has to ask "eta?" was owed one already. S1 keeps the ticks coming, and S8 gives the next one's time or says they stop.

What this skill does not own

Install the companions with npx skills add crissmoldovan/agent-skills.

When to Use

A report is owed at these points, and the point is the trigger — not whether there is anything impressive to say:

• At every phase or milestone boundary, including one that ended badly or produced nothing.
• Before ending a turn in which background work was started, or in which a background result arrived. The user is about to stop reading; this is the last moment they can learn that four agents are still running.
• Whenever the user asks any form of "status" — "where are we", "how's it going", "what's left", "did that finish", "eta?", "how far along is it".
• At every tick of a cadence (B1), whether the reader set it or the project binds it, without being asked, and once more at the end to say the ticks stop.
• Immediately on discovering that something already reported was wrong. Not at the next boundary. The reader may already be acting on it.
• At a handover — to another session, another agent, or a human — where the receiver has none of the context and everything they get, they get from this text.

Do not use it for a single-step answer, a conversational exchange, or work with no phases: a three-section status block over "yes, that file is in src/ " is ceremony, not clarity, and it trains the reader to skim the ones that matter. Do not use it as a substitute for lifecycle telemetry — a post-run summary is not visibility, and agent-lifecycle says so first. Do not use it to describe a landed change in detail; describe-changes (B8) reads the diff and anchors every claim in it.

Bindings

A project can adapt this skill without copying it: it binds these slots and adds to the steps by their ids, as the pack's project-adaptation guide describes. A slot nobody binds keeps its default.

Prerequisites

1. A phase list, or the admission that there is not one. The denominator in "3 of 5" has to come from somewhere the reader can trust: the phase list, or the register a percentage is counted from (B3). Complete when: the phases are written down with their order, or the report is prepared to say "no fixed phase list" rather than inventing a denominator.
2. The command behind every number you intend to give (B4). Test counts, commit counts, file counts, durations. Complete when: each number owed is paired with the command that produces it here, or is marked in advance as a claim to be attributed.
3. A lifecycle evidence source, located or declared absent. Check before you write, not while writing. Complete when: the projection is readable in this run, or the run is marked as having no lifecycle evidence and the exact no-evidence sentence is the one that will be used.
4. The earlier reports in this run, re-read. Corrections are impossible if you cannot remember what you claimed. Complete when: you can name every number and every outcome you have already asserted to this reader.
5. The reader's position. Someone who has watched every message needs different framing from someone arriving cold at a handover. Complete when: the audience is chosen, and the report is written for that one.

Procedure

1. S1. On a cadence, re-arm the next tick before anything else. When updates run on a cadence (B1), arm the next tick first, strictly inside the harness's cap on background time (B5), so a long turn cannot lose it. When the interval is as long as the cap or longer, chain wake-ups, each armed for the time left until the update or strictly inside the cap, whichever is shorter. A wake-up before the update is due re-arms the next one and writes nothing; the one that reaches the update's time writes it. The first time, write the standing order where the work is tracked (B6). Complete when: the next tick, or the next wake-up towards it, is armed and the standing order is written, or no cadence is running.
2. S2. Name the boundary you are reporting at. "Phase 3 of 5 complete", "background result arrived", "scheduled update", "handing over". A report with no stated position in the work reads as a mood. Complete when: the first line says where in the work this report sits.
3. S3. Write the head line when one is owed. It is owed when the reader asked for a percentage or an ETA, and carries what they asked for; on a cadence it carries both. Count the register (B3) by state just before you write, in one unit, with work blocked on a person in the denominator and never in the numerator, and give the ceiling without them; when the denominator moved, say what moved it and give both percentages. With no register, it reads "Progress not measured: no register of the work" (H7). Give the ETA in agent-hours, then wall-clock at the agents actually running, as the running section counts them (B7), then a clock time in each reader's zone (B2), every time and zone label pasted from a command. With no lifecycle evidence, divide by the agents dispatched, when there are any, and say they were not observed. With evidence that shows no agent running, or no evidence and no agent dispatched, give agent-hours alone and say the wall-clock and the clock time are not measured, and why (H7). Label it an estimate with its basis (H8), and make it cover all the work to the goal, with a fix round for each review still to come; a clock time that leaves part of it out says what it covers. references/percentage-eta-cadence.md has the shape and the commands. Complete when: the head line sits under the first line and each number in it states its basis, or the report has none because nobody asked for either and no cadence runs.
4. S4. Collect "done" from artefacts, never from memory. A commit sha, a merged PR number, a file that exists, a command that exited zero in this checkout. Run the commands now; a result from twenty minutes and three edits ago is a claim about the past. Complete when: every done item names an artefact or a command with its result, and no done item rests on recollection.
5. S5. Source "what is running" from lifecycle evidence (B7). Child ID, literal state, current activity, freshness. If there is no evidence source, print the exact no-evidence sentence in place of the section and stop — do not soften it, do not supplement it with an estimate. Complete when: every running row traces to a lifecycle observation, or the exact sentence stands alone in place of the section.
6. S6. Split verified from claimed, visibly, in the text. Two labelled groups beat one hedged sentence. "Verified here: npm test at 9f0a1b2, 812 passing." versus "Claimed by the child agent, not verified here: the Windows path is fixed." Complete when: every number in the report is either adjacent to the command that produced it, or attributed to whoever claimed it and marked unverified, or part of an ETA labelled as an estimate with its basis (H8).
7. S7. Translate each done item into its user-facing consequence. What could the user not do, or was wrongly told, that is now different? One clause is usually enough. Complete when: at least one line in the report states a consequence for a person rather than a change to a file.
8. S8. State "what is next" as an act with its precondition. "Re-run the installer on a clean checkout; blocked until child-7f2 reaches a terminal state." Not "continue with the migration", which is a topic, not a next step. On a cadence, the section also gives the next update's clock time beside the acts, or, in the last update, says the updates stop and why. Complete when: each next item names an act and what it waits on, if anything, and on a cadence the next update's time or the stop is stated.
9. S9. Issue every correction you owe, in this report, in one sentence each. Including corrections to a number you gave five minutes ago and corrections to something a child agent told you that you passed along. Complete when: no statement made earlier in this run and now known to be wrong stands uncorrected, and no corrected claim is quietly restated in its fixed form as though it had always read that way.
10. S10. Say when a section is empty. "Nothing running" and "no commits yet" are results. An omitted section reads as an oversight and invites the reader to assume the good case. Complete when: all three sections are present, each either populated or explicitly empty.
11. S11. Run the Verification checklist over the text before sending it. This is the step the whole contract rests on, because it is the only one that inspects the artefact rather than producing it. Complete when: every box is ticked, or the report has been edited until they are.

Usage Examples

Give me a status report on the migration. Fixed shape: what is done, what is running, what
is next, each with a count or an artefact. Keep numbers you verified by running something
separate from numbers a subagent claimed, and name the command for each verified one. If you
cannot see the background agents' state, say that rather than guessing it.

Before you end this turn: you started three background agents. Report which of them are
still running, from lifecycle evidence, with freshness — or state plainly that you have no
visibility into them. Do not tell me what they are probably doing.

The commit count you gave me earlier looks wrong. Correct it in one sentence, say what the
right number is and how you got it, and carry on — no apology paragraph, and do not restate
the old number as if it had been right.

Until the migration is merged, send me an update every 20 minutes without my asking. Open
each one with the overall percentage and what it counts, and an ETA as a clock time in UTC,
printed by date rather than typed, labelled as an estimate with what it rests on. Tell me in
the last one that the updates stop.

What it looks like

Specimens, not prompts. The asks are above; these are what the output should and should not look like.

A report that works

Phase 3 of 5 complete (receipt-path fix landed; Windows half unproven).

Done — verified here: 4 commits on feat/receipt-path (b1c2d3e..9f0a1b2); `npm test` run in
this checkout at 9f0a1b2 — 812 passing, 0 failing.
Done — claimed, not verified: the child agent reports the Windows path fixed. No Windows
runner exists in this environment, so that is its word, not a result.
Running: 1 child, child-7f2, state running, activity "rewriting the fixture loader", last
observed 40s ago (lifecycle projection).
Next: re-run the installer end-to-end on a clean checkout — blocked until child-7f2 reaches
a terminal state.
Consequence: every correctly-installed Yarn 1 repository was being reported broken by the
doctor command; from 9f0a1b2 it is not. The same bug on Windows is still unproven either way.
Correction: I said 5 commits an hour ago. One of those was already on main before this
branch existed. It is 4.

Everything in it is checkable: counts carry denominators, each number sits next to the command that produced it or the agent that claimed it, the running row came from lifecycle evidence with its freshness, and the correction is one sentence with no ceremony around it.

The same moment, reported badly

Great progress! I've been working through the migration and things are moving along nicely.
The tests are all passing and the background agent should be wrapping up the Windows fixes
shortly. I'll keep going and ping you if anything comes up.

Four failures in four sentences, and the text reads better than the good one. "Working through" is activity, not state (rule 2). "The tests are all passing" has no command, no count, and came from a child agent (rule 1). "Should be wrapping up" predicts a result from an agent whose state was never observed (rule 5). Nothing anywhere says what a user would notice (rule 3) — and the commit miscount is repaired by never being mentioned again (rule 4).

Pitfalls

• Narrating the child's self-report. The sentence arrives already fluent and the boundary between "an agent said this" and "this happened" disappears into it. The user then makes a decision on a result nobody produced.
• The progress bar with no denominator. "Phase 3" is unreadable without "of 5"; the reader cannot tell whether you are nearly done or barely started, which is the one thing they wanted.
• Activity verbs standing in for state. "Looking into", "continuing with", "working through" — all of them survive a report in which nothing at all happened, which is exactly when they get used.
• The silent repair. Quietly re-stating a corrected number in its fixed form, with no correction, is the cheapest possible short-term fix and it costs the reader the ability to trust any number in any later report.
• Predicting a pending result. "Should be done shortly" is not a state; it is a forecast presented in the grammar of an observation, and it is wrong roughly as often as work is hard.
• Freshness dropped from a running row. A child last observed 40 seconds ago and one last observed 40 minutes ago render identically without it, and only one of them is alive.
• Reporting only at the end. A single report after two hours cannot be acted on: every decision it would have informed has already been taken by someone waiting in the dark.
• A status block over a one-step answer. Ceremony where there is no state to report trains the reader to skim, and the skimming carries over to the report that mattered.
• Counting effort instead of outcomes. "17 files changed, 6 agents dispatched" measures what the agent spent, not what the user got; volume is not progress.
• Re-using the previous report's numbers. A count carried forward without re-running its command has silently become a claim about the past, and rule 1 now applies to your own earlier self.

Verification

Run this over the text you have written, before it is sent.

• The first line states where in the work this report sits.
• All three sections are present: what is done, what is running, what is next.
• Every item carries a count or a named artefact; none is an activity verb.
• Every count that has a denominator shows it.
• A head line, where there is one, carries what the reader asked for, and both on a cadence. A percentage names its register and counts in one unit, with work blocked on a person out of the numerator; an ETA is labelled as an estimate with its basis, covers all the work, and has its clock times pasted from a command.
• A figure nobody measured says "not measured", never 0.
• On a cadence, the next section gives the next update's time, or the last update says the updates stop.
• Every number is adjacent to the command that produced it here, or is attributed to whoever claimed it and marked unverified, or is part of an ETA labelled as an estimate with its basis (H8).
• No child-agent claim is restated as a result of this run.
• "What is running" came from lifecycle evidence, or the exact no-evidence sentence stands alone in its place.
• Each running row carries a literal state and a freshness.
• At least one line names a user-facing consequence rather than a code change.
• Every earlier statement now known to be wrong carries a one-sentence correction here, and no corrected claim is silently restated.
• Nothing in the report describes a result that has not happened yet; an ETA labelled as an estimate says when the work may end, never what it will have produced.
• An empty section says it is empty rather than being omitted or padded.
• A reader who has seen nothing else can answer: what is done, what is running, what is next.

The report is finished when every line in it is either an artefact, a command with its result, an attributed claim, or an estimate labelled with its basis — and a reviewer holding only this checklist could tell which is which without asking you.

Deeper reading

• Percentage, ETA and cadence: the head line's shape, the arithmetic, the clock commands, and what keeps updates on a cadence coming.