Skip to content

Project Catch-Up

ContributorsMyles Henaghan

When to use: Summarize what landed on the repo's trunk branch plus quick quality signals after time away, for stand-ups, release notes, or activity audits.

Keep execution deterministic by collecting commit data with the bundled Python script, then produce the report from that dataset. Python 3.8+ and git on PATH are enough. The same script runs from Git Bash, PowerShell, cmd, WSL, macOS, and Linux.

Instructions

1) Gate - Scope Before Git (Mandatory)

Never assume scope. Require one explicit scope before running history commands:

  • Last 3 days
  • Last 10 days
  • Last 30 days
  • Since date YYYY-MM-DD
  • Last N commits

When interactive option tools are available, use them first. Otherwise ask in plain chat and wait for an explicit choice.

2) Collect Facts with Script (Deterministic Path)

Use scripts/collect-history.py so commit extraction, size stats, and version tag activity are captured in one pass. Run from the skill folder or pass an absolute path to the script. The collector prints the commit TSV path and writes a companion <output-stem>-tags.tsv file (or the path supplied by --tag-output); read both files.

scripts/collect-history.sh remains for commit-only collection. Tag activity requires the Python collector.

Examples:

# Last N commits (Git Bash, WSL, macOS, Linux)
python scripts/collect-history.py --repo /path/to/repo --branch <trunk> --count 30

# Windows PowerShell / cmd — same flags; use py -3 if python is not on PATH
py -3 scripts/collect-history.py --repo . --branch <trunk> --count 30

# Date window
python scripts/collect-history.py --repo . --branch <trunk> --since "10 days ago"

# Specific output file
python scripts/collect-history.py --repo . --after "2026-05-01" --output /tmp/project-catchup.tsv
# The companion tag data is /tmp/project-catchup-tags.tsv.

Rules:

  • Do not run this script until scope is confirmed.
  • Pass explicit flags only (--count, --since, or --after).
  • Do not silently substitute defaults.
  • If the script errors, report the error and ask to revise scope.
  • In date scopes, scope_match uses the annotated tagger date (lightweight tags fall back to target commit date). In --count scopes, it uses whether the tag points to one of the selected commits; report this basis accurately.
  • Report in-scope tag activity (scope_match=yes) in the Summary and inspect its drift value. Call out zero padding and numeric regressions for new in-scope tags, even when their target commit predates the requested window; mention an out-of-scope tag only when it is the comparator explaining that regression. Do not repeat warnings for historical padded tags that predate the current tag activity.
  • If no tag rows match the scope, explicitly say no version tag activity was found. Do not infer tag activity from release commits.

3) Report Shape (Required)

Return sections in this order:

  1. ### 👓 Summary
  2. ### 📶 Review signals
  3. ## Per-Commit Detail with the five-column table

Use the detailed scoring/table enums from:

  • references/report-spec.md

Use the sample shape from:

  • examples.md

4) Deep Pass (Optional)

Only include deep-pass artifacts when explicitly requested:

  • file-level blob links
  • author rollup
  • filtered history by author/path/window

5) Output Checklist

  • [ ] Scope explicitly confirmed
  • [ ] Deterministic collector script used for facts
  • [ ] Commit TSV and tag sidecar both inspected
  • [ ] In-scope tag activity and padding/version drift reported
  • [ ] Section order is 👓 then 📶 then table
  • [ ] Summary threads use the borderless row-list layout (Thread · What landed, --- separators, no pipe table)
  • [ ] Review signals use the borderless row-list layout (Signal · Notes, all five rows, no pipe table)
  • [ ] Per-commit table uses exactly five required columns
  • [ ] Enum-only values used for Msg vs files and App vs Tests
  • [ ] Deep pass included only on request

References

  • references/report-spec.md — section order, enums, formatting rules
  • examples.md — sample report output

Troubleshooting

Symptom Likely cause Fix
python: command not found Python not on PATH Install Python 3.8+; on Windows try py -3 instead of python
git is required and must be on PATH Git not installed or shell PATH stale Install git; reopen the terminal; verify with git --version
not a git repository --repo path wrong Point --repo at the repository root (folder containing .git)
provide exactly one scope flag Missing or conflicting scope Pass exactly one of --count, --since, or --after
Empty TSV / no commits Scope too narrow or stale remote Widen scope; omit --skip-fetch so the remote trunk is refreshed first
Script works in Git Bash but not PowerShell PATH differs between shells Use the same Python launcher in both (where python / where py)
Unsure the collector is healthy Need a quick smoke test Run python scripts/collect-history.py --self-test from this skill folder

The collector prints dependency hints to stderr when Python or git is missing.