/progress-report review and report

Install

Install just this, from a clone of the repo. Anything it needs comes with it.

./scripts/install-skills.sh --skill progress-report   # bash, Git Bash, macOS, Linux
.\scripts\install-skills.ps1 -Skill progress-report   # Windows PowerShell

Needs: handoff-auto (installed with it).

What it does

Turns a run's ledger into a short progress report (1–2 pages) covering only what happened since the last report — never overlapping.

• Markdown by default, .docx on request.
• Every issue/PR/commit reference is a link.

When to use

• "Make a report", "an update doc", "what's been done", "write up progress".
• Typically during or after a meta-orchestrator run, but works on any long session (reconstructs a ledger if none exists).

How to invoke

/progress-report [reports folder] [docx] [full]

• docx — Word file instead of Markdown (uses the docx skill if available, else python-docx).
• full — ignore the watermark, cover everything, titled "Full report".

Claude also runs it when you ask for "an update doc".

How it works

1. Find the source. Reports folder (default the repo's skilleddocs/reports/); ledger at skilleddocs/orchestrator/ledger.md.
   • No ledger → reconstructs one from git log, merged PRs, issues and the conversation, and says so.
2. Watermark. .last-reported records where the last report stopped: <NNN> <report filename> <entry NNN's timestamp>, where NNN is the last reported ledger entry.
   • The new report covers entries NNN + 1 through the latest.
   • If a new run restarted the ledger at 001, the stored timestamp no longer matches, so the report covers the ledger from 001.
   • It also covers commits or merged PRs since the watermark that have no ledger entry, marked "not in ledger". The reporting commits themselves are skipped.
   • Earlier items only reappear under "Revisions to earlier reports" if they changed (revert, reversed decision, broken "done").
3. Fixed sections. Empty → "none".
   • Header (report number, date, time range in your local zone, ledger range).
   • Summary.
   • Done (table).
   • What worked.
   • What didn't.
   • Concerns (ranked, blocking flagged).
   • Decided for you.
   • Assumed decisions open (A-n still unconfirmed).
   • Manual steps for you.
   • Revisions to earlier reports.
   • Next up.
4. Link everything. Resolves the repo URL once.
   • #n, PR #n/PR#n, commit hashes and decision ids (if the repo has a decisions doc/ADRs) become links in every section.
   • Existing links, bare URLs, code spans, headings and decimal CI run ids are left as they are.
   • Checks the link count afterwards.
5. Write NNN-YYYY-MM-DD-<slug>.md (or .docx) in the reports folder.
   • Never overwrites an earlier report.
   • Reads it back to check.
6. Advance the watermark. Updates .last-reported, appends a report entry to the ledger.
   • In commit mode it commits them with the report, on the default branch. If the default branch is protected, it commits on a docs branch instead (TRACKING.md).
   • Prints the path and entry range.

Reads: skilleddocs/orchestrator/ledger.md, .last-reported, git/gh.

Writes: the report, .last-reported, a ledger entry.

Design principles

• Never overlapping. A watermark (.last-reported) means each report covers only new ledger entries; anything earlier reappears only under "Revisions to earlier reports" when it changed.
• Readable in two minutes. Fixed sections, bullets with one idea each, numbers in a table, 1 to 2 pages.
• Every reference is a link, every time is real. Issues, PRs, commits and decision ids are linked; times come from the ledger, git log or API timestamps in your local zone, never estimated.

Shared context for these principles: Matt Pocock's video.

Use cases

• Catching up after a meta-orchestrator run you left unattended.
• A periodic update during a long run, each one picking up where the last stopped.
• Writing up a long manual session with no ledger (it reconstructs one from git, PRs, issues and the conversation, and says so).
• A Word document to send to someone else (docx).

Tips

• Use full when you want everything in one document regardless of earlier reports; the watermark is ignored for that run.
• Reports are numbered and never overwritten, so the folder is a running history.
• The "Decided for you" and "Manual steps for you" sections are the ones to read first after an unattended run.
• Pass a folder to keep reports outside skilleddocs/reports/; its .last-reported file lives in that folder.

Example

Related

• meta-orchestrator writes the ledger it reads.
• docx skill (optional) for Word output.

Prereqs

• gh to resolve the repo URL for links.
• For docx: the docx skill or python-docx.

Sample workflows

• Run the backlog unattended
  you → lanes → you → meta-orchestrator → planner → manager → implementer → verifier → you → switch → remind → progress-report → you
  Install just this one: ./scripts/install-skills.sh --workflow unattended-backlog or .\scripts\install-skills.ps1 -Workflow unattended-backlog
• Hand the project to a teammate
  progress-report → teammate-brief → you → you
  Install just this one: ./scripts/install-skills.sh --workflow brief-a-teammate or .\scripts\install-skills.ps1 -Workflow brief-a-teammate

Source

• progress-report/SKILL.md
• progress-report/README.md