oliver-kriska/catchup

Catchup — Async-Team Return Briefing

You've been away. This skill is a thin orchestrator: it resolves the window + sources here, then delegates the I/O fan-out, impact analysis, and brief assembly to the catchup-runner agent (Sonnet) so your (often Opus) session does not pay for summarization. You only print what the agent returns.

Usage

/catchup                                  # since you were last active
/catchup --since "friday"
/catchup --since "2h" --focus reviews-requested
/catchup --since last-commit --depth deep
/catchup --scope all                      # include cross-repo pings/reviews

Default is repo-scoped: every GitHub signal (reviews requested, notifications, mentions) is filtered to the repo you ran it in. Pass --scope all to also include cross-repo activity, which is then listed in its own separate section — never mixed into this repo's lists.

Iron Laws

1. Delegate the heavy work — spawn catchup-runner (sonnet) for fan-out + assembly. Do NOT run the gh/git fan-out in this session; that defeats the cost/speed purpose.
2. Resolve the window here, once — the agent must never re-resolve it. Pass absolute SINCE_* values.
3. MCP runs here, not in the agent — Linear/Calendar MCP tools are unreliable in subagents. If present, fetch in this context and pass the text to the agent; else mark absent.
4. Validate --since before any shell — match the grammar; on no match fall back to 24h and note the assumption.
5. Stop after the brief — print the agent's summary, never auto-transition to another command.
6. Repo-scoped by default — pass SCOPE=repo unless the user passed --scope all. A brief run inside one repo must not leak another repo's reviews/notifications. Cross-repo is opt-in only.

Workflow

1. Parse arguments

From $ARGUMENTS: --since, --scope, --sources, --depth, --focus. Defaults: --since last-active, --scope repo, all detected sources, --depth standard, no focus. --scope accepts repo (default — every GitHub signal filtered to the current repo) or all (cross-repo allowed, listed in its own section).

2. Resolve the time window (here, in this context)

Read ${CLAUDE_SKILL_DIR}/references/time-window.md. Resolve calendar words (friday, yesterday, a date) in the user's local timezone (this machine = the user's TZ), pivot through SINCE_EPOCH, derive SINCE_ISO (UTC) + SINCE_LABEL (with TZ abbrev) + LOCAL_TZ.

Default last-active = MAX of: newest Claude session mtime for this repo, your last own commit (git log --author=<you> -1 --format=%ct), your last own PR in this repo (gh pr list --repo <repo> --author @me --state all, repo-scoped — a global search would anchor to other repos). The latest footprint is "you were last here". Record which signal won. Variants: last-session (sessions only), last-commit/last-mine (your git/PR only). No signal → 24h, noted.

3. Detect sources + pull MCP data (here)

gh:   command -v gh && gh auth status               → github ON
git:  git rev-parse --is-inside-work-tree           → git ON
linear/calendar: a Linear / Google-Calendar MCP tool present?

If Linear/Calendar MCP is present, query it in this context now (assigned/updated tickets since SINCE_ISO; missed + today's meetings in LOCAL_TZ) and keep the short text as LINEAR_DATA / CALENDAR_DATA. If absent, set them to absent (the agent will proxy-harvest XXX-#### refs for Linear; skip calendar with a note).

4. Delegate to catchup-runner (Sonnet)

Spawn one agent, foreground, passing a self-contained prompt:

Agent(subagent_type: "catchup-runner", prompt: """
SINCE_EPOCH={…}  SINCE_ISO={…Z}  SINCE_LABEL="{… local TZ}"
LOCAL_TZ={…}  SOURCES={github,git}  SCOPE={repo|all}  DEPTH={…}  FOCUS={…}
OUT_PATH={cwd}/.claude/catchup/brief-{YYYY-MM-DD}.md   # local date (date +%F), not UTC
LINEAR_DATA={text or "absent"}
CALENDAR_DATA={text or "absent"}
Window anchor signal: {which one won, for the Risks note}
Do the gh+git fan-out, impact analysis, and brief assembly per your
instructions. Write the file. Return ONLY the inline summary.
""")

The agent inlines all recipes (it cannot read this plugin's references). Do not re-implement its work here.

5. Present + stop

Print the agent's returned summary verbatim and the brief path.

If the agent returned no summary (e.g. it hit its turn budget mid-assembly — the brief file is usually already written): do NOT re-summarize the brief yourself; that pulls the expensive step back into this (often Opus) session, defeating the delegation. Instead SendMessage the agent by the agentId from its stop usage: "Return only the inline summary now." — it finishes cheaply in Sonnet. Only if that also fails, read the brief's Intent + Top priorities section (not the whole file) and print that.

Do NOT auto-invoke any other command. The user decides what's first.

Sources at MVP

GitHub (gh), Git (git), Linear MCP (optional), Google Calendar MCP (optional). Slack/Gmail are v2 opt-in — never queried, never piped raw. Scheduling + per-project config are designed in ${CLAUDE_SKILL_DIR}/references/config-schema.md, not built at MVP.

Graceful degradation contract

A missing source degrades the brief, never breaks it. git log alone (always available in a repo) is a valid minimum brief. Every absent or failed source becomes one honest line under the brief's Risks/assumptions block, so the reader knows what it does not cover.