Catchup

Calculate days since last modified. Include the age in the subagent prompt so it appears in the briefing. Thresholds:

• < 1 day: no annotation
• 1-3 days: "(handoff is N days old)"
• > 3 days: prominent warning — "(handoff is N days old — context may be stale. Consider verifying assumptions or creating a fresh handoff.)"

Subagent Architecture

The read-and-digest phase runs inside an Explore subagent to keep raw file contents out of the main conversation context.

Launch an Explore agent with a prompt built from this template (fill in the <placeholders> before sending):

Read the handoff file at <resolved-path>. The file is <N> days old.

Extract: frontmatter (created, project, branch) and all body sections. If the file is missing expected sections (Completed, Current State, Next Steps) or appears truncated/corrupted, note what's missing and work with what's there.

Also read PROJECT_STATE.md if it exists. Extract:

• Current Status
• Data Accuracy Status table (which categories are verified, which are failing)
• Active Work Streams (what's in progress, blocked, or done)
• Last 3 entries from the Session Log

If PROJECT_STATE.md doesn't exist, note "No PROJECT_STATE.md found" and continue with handoff data only.

Also check VERIFICATION.md if it exists. Note:

• How many total verification test cases exist
• How many are FILL_IN vs. have actual expected values
• Last known pass/fail status if recorded

Verify git state:

• git branch --show-current 2>/dev/null
• git status --short 2>/dev/null
• git log --oneline -5 2>/dev/null

Compare to the handoff. Flag drift (branch mismatch, new commits, unexpected uncommitted changes). If not in a git repo, note that and skip.

Read each file from the "Relevant Files" section. Don't dump contents — just confirm each file exists, note if anything looks different from the handoff's description.

Return this briefing and nothing else:

**Project:** <name>
**Handoff written:** <timestamp> (<N days ago>)
**Branch:** <recorded> → **Current:** <actual>

**Drift:** <mismatches, or "None">

**Completed:** <bullet list from handoff>

**Current state:** <from handoff + drift observations>

**Data state:** <from handoff Data State section + PROJECT_STATE.md Data Accuracy table>
  - Verified categories: <list>
  - Failing categories: <list with issue summaries>
  - Verification coverage: <X tests defined, Y have real values, Z are FILL_IN>
  (If no database/data component, say "N/A — no database in this project")

**Open decisions:** <from handoff, or "None">

**Traps:** <from handoff, or "None">

**Files verified:** <each file, exists/missing/changed>

**Next steps:**
1. <from handoff>
2. ...

If the handoff is older than 3 days, add a warning line after the timestamp: "This handoff is stale. Git state and file contents may have diverged significantly."

The main conversation receives only this clean briefing.

Present Briefing

Show the subagent's briefing under a ## Catchup Briefing header.

Priority callouts (show prominently if present):

1. Staleness warning — if handoff > 3 days old
2. Drift detected — branch/commit mismatches
3. Data failures — if PROJECT_STATE.md or handoff shows failing verification tests
4. Missing verification — if VERIFICATION.md has mostly FILL_IN values
5. Missing/corrupted sections — if the handoff file was incomplete

Conditional Codex audit: If the handoff is older than 3 days, drift is detected, relevant files are missing, or verification coverage is weak, run a Codex stale-context check before implementation starts:

just codex_audit_handoff .claude/handoff.md

Treat the Codex result as a second opinion. Claude still owns the resume flow, but Codex should be used to challenge stale assumptions before code changes.

Approval Gate

After presenting the briefing, ask the user to confirm before starting work:

Ready to start on [Next Step #1], or want to adjust the plan?

• User approves → begin working on Next Steps #1
• User adjusts → incorporate their changes, then proceed
• Do NOT auto-start work. The briefing is a proposal, not an action.

If data failures were flagged, suggest:

⚠️ There are failing data verification tests. Want to fix those first, or proceed with the planned next steps?

After Beginning Work

Once work begins, check for stale handoff files:

find .claude/ -name "handoff*.md" -mtime +7 2>/dev/null

If any files are older than 7 days, mention:

There are N handoff files older than 7 days. Want me to clean them up?

List the files with their ages and let the user decide. Do NOT auto-delete.

Also mention:

The current handoff file is still on disk. It'll be overwritten on the next /handoff, or you can delete it manually.