---
name: progress-reporting
description: File a dated, immutable progress snapshot that survives the session that produced it — board integrity re-derived, findings classified and routed, gate blind spots named. Use when a human asks where the build stands, when a completeness sweep needs its findings filed durably, before a phase-exit gate, or after a wave or a long break.
allowed-tools: Read, Grep, Glob, Bash, Write, AskUserQuestion
---

> **Specialization:** generic by design — bind every `<…>` and "per `CLAUDE.md`" reference from the project `CLAUDE.md` (the reports directory `<reports-dir>`, the lessons file `<lessons-file>`, the progress log, the board paths, the test command, the built-UI root, and — where bound — the code-discovery graph project id, the metrics directory, and the kit-manifest path used by `completeness-sweep`'s A7–A11). See `SPECIALIZE.md`. If a needed value is missing, STOP-and-ask.

## 1. The problem this exists to solve

A sweep's findings die with its session.

The `completeness-sweep` skill can independently re-derive what the boards claim and classify every incomplete affordance — but its own output contract is "a classified inventory + board-routing table": prose returned to whoever is reading the conversation. Once that conversation ends, the evidence is gone. The next sweep, on the next day or the next project, starts from zero and re-derives the same numbers, and re-discovers the same gaps, because nothing durable was left behind.

This is not hypothetical. Two independent projects on this kit each grew their own answer to the same missing capability — one grew a single mutable status file that got overwritten every time it was touched, the other grew a dated, immutable report file plus an index. Convergent evolution across two unrelated projects is the strongest signal available that a piece of process belongs in the kit rather than being re-invented per project. This skill is that missing capability, generalized.

**Boards are testimony — a claim asserted once and inherited forward without being re-checked. A filed snapshot is dated evidence** — a re-derived set of numbers, tied to a specific commit, that a reader can act on without having been in the room when it was produced. The distinction matters because testimony rots silently (nothing forces a board's roll-up to be recomputed) while evidence carries its own timestamp and method, so staleness is visible on its face.

This skill does not do the finding — that is `completeness-sweep`'s job, alone or fanned out with the read-only auditors. This skill is what turns a finding into something that outlives the session.

## 2. The depth × kind contract

Two independent switches shape a run: how much gets re-derived (**depth**), and which sections and posture the report emphasizes (**kind**). Depth is the cost decision; kind is the audience decision. They compose freely.

**Depth** — how much evidence gets re-derived before filing:

| Depth | Behaviour | Cost |
|---|---|---|
| `boards` (default) | Board-integrity checks only (`completeness-sweep` Part A, `A1`…`A11`); classify findings from the existing board rows, spot-verifying a sample at `file:line`. The report's §2 Coverage section must declare this a **floor, not a census** — it read the boards, not the whole corpus | minutes |
| `full` | Everything `boards` does, plus a fan-out of the read-only auditors (`completeness-sweep` Part B and its peers) over the built surface, batched by module or affinity; every affordance **and every displayed value** gets classified; every design-gap candidate is anchor-tested against the prototype before it is filed as such | hours, many agents |

**Kind** — what the report is for, and which sections beyond the common eleven-section core are mandatory:

| Kind | Purpose | Mandatory beyond the common core |
|---|---|---|
| `status` | An operational plan forward for whoever picks the work up next | §9 task pack + §11 recommended order are the spine of the report |
| `progress` (default) | A retrospective evidence inventory of what is actually true right now | all eleven sections, none optional |
| `gate` | Phase-exit evidence — the artifact a human checkpoint reads to decide go/no-go | an explicit gate verdict per the project's lifecycle contract; the §10 Law-6-style amendment table is required, not optional |
| `session` | The end-of-session story — what a next session (or another live one) needs to pick the work up without having been in the room | purpose/ask (near-verbatim) · plan · done **with evidence** (`file:line`, commits, gate verdicts) · **Pending** · **Decisions to give** (each cross-filed to the approval inbox) · Handoff. Files to the **session journal**, not `<reports-dir>` — see below |

**Default:** no arguments supplied means `--depth boards --kind progress`.

**Escalation is the user's call, never the skill's.** If a `boards`-depth Part A run trips on anything compliance-bearing (a fail-closed authorization gap, a security-relevant divergence, anything the project's `CLAUDE.md` marks as compliance-tagged), the closing `AskUserQuestion` **recommends** re-running at `--depth full` and explains why. It never silently escalates and runs the expensive pass on its own initiative — depth is a cost the user spends deliberately.

**Output path and immutability.** A filed snapshot lands at `<reports-dir>/{yyyy-mm-dd}-{kind}.md` — for example `<reports-dir>/2026-07-30-progress.md`. If a second report of the **same kind** is filed on the **same day**, it takes a `-2` suffix (`{yyyy-mm-dd}-{kind}-2.md`) rather than overwriting the first: a filed report is never overwritten, only superseded by a newer dated file (see the immutability invariant in §4). Every filed report also prepends one newest-first line to the reports index at `<reports-dir>/README.md`. **Exception — `--kind session`:** the session story files into the **session journal** (default `docs/journal/{yyyy-mm-dd}-session-{sid}.md` — exactly the file the session ledger's Stop gate names), adds **no** reports-index line, and shares that file with the ledger's mechanical envelope: narrative sections above, envelope appended at close below. Same immutability discipline — append, never rewrite; use the headings `## Purpose`, `## Plan`, `## Done`, `## Pending`, `## Decisions to give`, `## Handoff` so the ledger's orientation can excerpt Pending/Handoff for the next session. A `session` report at `boards` depth skips Part A entirely unless boards were touched this session.

## 3. The eleven sections

Every report opens with a short header block before the numbered sections: the date, the branch plus the commit it was filed at plus how many commits separate it from the previous snapshot on this branch, the **method** (which instruments actually ran, each named with the skill or command file that ran it — never left implicit), and the **relationship to prior snapshots** (what each prior snapshot was for, what this one adds, and an explicit statement that filing a new one supersedes none of the earlier ones — see §4). `REPORT_TEMPLATE.md` in this folder is the ready-to-fill skeleton for all of the below; use it rather than reconstructing the shape from this prose.

1. **Executive summary.** The one sentence that is actually true of this build right now — not a hedge, a claim. The recurring *classes* of finding, not an itemized bug list (that belongs in §6/§9). The count of hard defects. **Why the gates passed anyway** — the structural, mechanical reason (a gate that samples a default render cannot see an unwritten branch), never "sloppiness" or a personal-failing explanation. The revised posture the reader should hold after reading this section.

2. **Coverage — what this sweep did and did not read.** Files audited, how many were fully read versus signature-extracted only, and the corpus total, so a reader can judge whether the count below is a census or a sample. Plus the honesty notes: any partition of work that left files outside every batch, any unit read mechanically rather than closely, any check that could not run at all. This section is not optional at any depth — see the invariant in §4.

3. **Part A — board integrity.** The full `A1`…`A11` table from `completeness-sweep`: check, verdict (`✅ consistent` or `⚠ <divergence>`), and evidence carrying both the board's number and the re-derived number. Close with one paragraph on the single most *instructive* divergence — not the largest number, the one that teaches something about why the boards drifted.

4. **Classification.** Counts per class — reconstruction-gap, wiring-gap, data-seam, design-gap, and unresolved-anchor (a candidate that could not be anchor-tested to a verdict) — each row naming the board that owns that class. A per-batch breakdown when a `full`-depth Part B ran. How many design-gap candidates were anchor-tested and cleared: a zero design-gap count that was never tested is a materially different claim from a zero that survived the anchor test, and the report must say which one it is.

5. **The systemic classes.** Findings grouped by shared root cause, especially across units that were built weeks apart by independent sweeps and could not have seen each other. Each class gets its site list (at `file:line`) and its worst instance narrated in two or three sentences. This grouping goes before the individual-defect table because one root cause explaining a dozen symptoms is a different, more actionable claim than a dozen unrelated defects.

6. **Hard defects.** Things that are actively wrong — producing an incorrect result, not merely an absent one. A table: number, defect, site (`file:line`), and the task id it is filed under (existing or newly proposed).

7. **Verdicts that correct the boards.** Every place a board's claim turns out to be half-stale, run in **both** directions — including the direction where the board undersold what is actually done. A one-directional corrections section reads as an indictment rather than evidence.

8. **Blocking graph.** Findings ranked by fan-out — the root cause that unblocks the most downstream rows first, not the largest single defect. Include the shared-primitive audit (a component or utility used by many screens/units), split into consumers that are clean versus consumers carrying their own findings, with counts for both.

9. **Task pack.** Id, task, class, severity, effort, owner. Reuse existing board ids wherever a finding already has one; mark anything new **"proposed — not yet filed"** — this report proposes, it does not file (§4, §5).

10. **Closing the loop — why the gates were blind.** For every defect that surfaced *inside* a gate's stated scope, name the gate, the mechanical reason it could not observe this class of miss, and the amendment that would close the blind spot. Then a lesson entry for `<lessons-file>`, in Mistake / Trigger / Rule form: what was declared true, the structural condition that made it invisible, and the prevention. This section exists because a defect inside a passed gate's scope is the gate's defect too, not only the artifact's.

11. **Recommended order.** A numbered list of what to do next, with the ordering rationale stated (not just asserted) and a closing posture verdict — what a reader should believe about the state of the build after acting on this list.

Close every report with one evidence line: how the findings were produced, how many rows each table carries, and whether re-running the same instruments would reproduce them.

## 4. Discipline invariants

Ten rules, each earned by a specific miss that happened without it. State the rationale inline with every rule you apply — a rule read without its reason gets rationalized away the first time it is inconvenient, and this skill is loaded cold by whoever needs it, not by whoever wrote it.

1. **§2 Coverage is mandatory at every depth and every kind.** Without it, a total reads as a census when it might be a floor over a fraction of the corpus. A reader cannot tell "we checked everything and found 12" from "we checked a sample and found 12" unless the coverage section says which.

2. **Every finding carries a `file:line` citation.** A claim about the build without a citation is an impression, not a finding — it cannot be independently checked, and it will not survive the first person who tries to verify it.

3. **The orchestrator verifies every agent-reported finding at `file:line` before it is filed.** This is not a formality: a real run once had an auditor's classification corrected twice and narrowed once at this step, including a finding that named a modal as unbuilt when the actual prototype anchor was an inline pill — filing it unverified would have sent a later build agent hunting for a source that never existed. Delegating this verification step reintroduces exactly the error it exists to catch.

4. **Anchor-test every design-gap candidate against the prototype (or design source of record) before filing it as one.** A candidate that turns out to have a design anchor is a *reconstruction* gap, not a design gap — filing it wrong commissions a redesign over what may already be the binding contract. The `anchor-test` is: grep the design source for the state key or affordance behind the candidate; a hit with a real consumer reclassifies it, a genuine zero-hit confirms it.

5. **Never present a number that was not re-derived this run, without marking it as unverified.** A board's number quoted without re-derivation is testimony wearing evidence's clothing — see §1.

6. **Systemic classes are reported before individual defects.** Grouping by shared root cause first is what makes the report actionable rather than a flat list to re-litigate defect by defect.

7. **The blocking graph is ranked by fan-out, not by defect size.** One root cause that retires a dozen downstream rows outranks a dozen unrelated single-row defects, and the recommended order (§11 of the template) should follow from this ranking, not contradict it.

8. **The Law-6-style amendment table (§10 of the template) is mandatory on a `gate`-kind report, never optional.** A `gate` report is phase-exit evidence; a defect found inside a passed gate's stated scope is a defect in the gate, and the phase-exit decision needs to see that the blind spot was named and closed, not just that the defect was found.

9. **Immutable once filed.** A filed report is never edited in place. A correction to an earlier report's content is filed as a new, later-dated snapshot that says what it corrects and why — the old file stays exactly as it was written, because its value as evidence depends on it representing what was true (or believed true) at the moment it was filed. **"Filed" means merged or shared, not first written** — a snapshot still sitting on an unmerged branch may be corrected in place, because no reader has yet relied on it; from the moment it reaches anyone else, the rule above binds absolutely.

10. **Boundary-anchor every regex used to produce a count, before quoting the count.** A naive, ticket-shaped pattern once matched the trailing characters of unrelated event names and fragments inside reference numbers, inflating a real census from 120 to 179. Every count derived from a pattern match needs the pattern shown, and a spot-check that the matches are the thing being counted, not a lookalike.

## 5. Boundaries — what this skill does not do

- **Writes exactly one artifact per run** — the dated report — plus one index line in the reports directory's `README.md`. Nothing else changes.
- **Proposes board rows and tickets; it never files them.** Every row in the §9 task pack is a proposal until a separate, approved action lands it on its owning board. This is what keeps the single-writer rule intact: a report that silently mutated other boards would be indistinguishable from a sweep that skipped its own review checkpoint.
- **Never re-indexes anything** (a code-discovery graph, a search index, or any other cache). If a freshness check (`completeness-sweep`'s `A9`, where bound) finds staleness, the report names it and recommends the re-index; it does not perform it.
- **Never fixes a finding.** Inventory and remediation are separate passes, run separately, by design — a pass that starts fixing stops sweeping, and the resulting snapshot is silently partial.
- **Adds no new agent.** The heavy reading is done by the existing read-only auditors this skill's `full` depth fans out to; this skill is the discipline for filing what they find, not a new reader of its own.