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.

1. Resolve the window here, once — the agent must never re-resolve

it. Pass absolute SINCE_* values.

1. 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.

1. Validate --since before any shell — match the grammar; on no

match fall back to 24h and note the assumption.

1. Stop after the brief — print the agent's summary, never

auto-transition to another command.

1. 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.