Handoff Diet

handoff-diet

Handoffs burn turns. Wakeups amplify the burn. This skill documents the pattern that eliminates them.

The anti-pattern: ScheduleWakeup poll loop

1. Push PR with 10-minute CI wait
2. ScheduleWakeup(600)   ← "check back in 10 min"
3. On wakeup: "PR still pending, re-check in 5 min"
4. ScheduleWakeup(300)
5. ...repeat 6–8 times...

Cost: Each wakeup = 1 handoff + 1 compaction cycle. Over 6 wakeups: 12 turns burned on status polling.

The fix: gh pr merge --auto + detached watcher

GitHub has native auto-merge. Use it.

# Instead of ScheduleWakeup:
gh pr merge <N> --repo owner/repo --squash --delete-branch --auto

# Optional: detached background watcher (for visibility)
(
  while gh pr view <N> --json mergeStateStatus | grep -q BLOCKED; do
    sleep 30
  done
  # Once merged, do post-merge actions (log, bump version, etc.)
) &
disown
echo "Auto-merge queued; you can move on"

Cost: 0 wakeups, 0 handoffs, 0 turns burned. Merge happens when CI passes.

When to use auto-merge (no wakeup needed)

• PR has green CI or is 1 rebase away from green
• You trust the test suite (no runtime surprises expected)
• Post-merge cleanup is automated (e.g. auto-bump version, auto-deploy)
• You're moving to the next task and don't need to monitor this one

When to still use ScheduleWakeup (model action required)

• PR merge is blocked by human review (code-review gate)
• PR has merge conflict that needs resolution (not just rebase)
• You're waiting for model-generated changes to be pushed (agent is working on something)
• You're debugging a flaky test and need to see the result immediately

Rule of thumb: Use wakeups only for tasks that require model decision-making. Don't use wakeups for status polling (GitHub polls for you with --auto).

Implementation details

auto-ship skill (canonical implementation)

gh pr merge "$pr_num" \
  --repo "$owner/$repo" \
  --squash \
  --delete-branch \
  --auto

See ~/.claude/skills/auto-ship/SKILL.md for full details.

prod-rebuild skill (detached watcher pattern)

nohup (
  # Build runs in bg
  docker compose build ... &
  BUILD_PID=$!
  
  # Wait for build to finish
  wait $BUILD_PID
  
  # Restart container
  docker rm -f bot && docker compose up -d bot
  
) > /tmp/build.log 2>&1 &

Returns immediately. Build + restart completes in bg without blocking session.

Principles

1. CI is not a model: GitHub's merge queue handles CI status, not you.
2. Detached watchers are free: Use them for visibility, not blocking.
3. Wakeups are expensive: Every wakeup = 1 turn + 1 compaction. Avoid.
4. One wakeup per task max: If you must wakeup, do it once and move on.

Related skills

• auto-ship — the pattern in action
• version-bump — uses --auto merge internally
• prod-rebuild — detached watcher pattern for long-running builds