# Handoff Size Check

> Handoff-size warning tied to the 500k cap. Per v3.6 backlog 3.2 — elephant-hint and token-cap as the same mechanism from two ends.

- Skill: `jokerman89/handoff-size-check` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jokerman89/handoff-size-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/handoff-size-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: jokerman89 (https://skillmd.com/u/jokerman89)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jokerman89/handoff-size-check

---


You are the `handoff-size-check` skill — pre-handoff payload validation against the 500k cap.

## What this skill does

When the operator picks "run anyway" on a broad idea (elephant-hint default), the plan declares its own handoff size. If the plan's payload approaches the 500k cap → natural warning point ("this plan yields ~480k handoff, near cap — split it?").

Per v3.6 backlog 3.2 — complements 3.1 elephant-hint + 2.1 500k cap as **the same mechanism from two ends:**
- Elephant-hint (3.1): catches a broad idea BEFORE plan-writing
- Handoff-size-check (3.2): catches a large plan AFTER plan-writing
- Cleaner than two separate systems.

## When to use

- **Post-PLAN-phase auto** — `/li:cycle` invokes this after plan.md is done
- **Standalone audit** — `/li:handoff-size-check <plan.md>` → check a specific plan
- **Pre-cold-executor-handoff** — verifies trio + warming total < cap

## When NOT to use

- Mid-plan-writing (a warning against a partial plan is a false positive)
- Single-skill estimate — use `/li:context-budget` directly
- Real-time monitoring — this is a batch check at handoff points

## Workflow

### Step 1 — Locate plan + warming-manifest

```bash
PLAN_FILE="${1:-.claude/runtime/state/plan.md}"
WARMING_FILE=".claude/runtime/state/warming-manifest.md"  # from context-warm-* invocations
[ -f "$PLAN_FILE" ] || { echo "No plan found at $PLAN_FILE"; exit 2; }
```

### Step 2 — Compute payload size

```bash
# Cold-executor trio sizes
spec_size=$(wc -c < .claude/runtime/state/spec.md 2>/dev/null || echo 0)
plan_size=$(wc -c < "$PLAN_FILE")
prompt_size=$(wc -c < .claude/runtime/state/prompt.md 2>/dev/null || echo 0)

# Warming projected loads
warming_total=0
if [ -f "$WARMING_FILE" ]; then
  # Parse warming-manifest for per-load file-sizes
  while IFS= read -r line; do
    if [[ "$line" =~ ^load:[[:space:]]*([0-9]+) ]]; then
      warming_total=$((warming_total + ${BASH_REMATCH[1]}))
    fi
  done < "$WARMING_FILE"
fi

# Convert bytes to tokens (rough: 1 token ≈ 4 bytes)
trio_tokens=$(( (spec_size + plan_size + prompt_size) / 4 ))
warming_tokens=$(( warming_total / 4 ))
total_tokens=$(( trio_tokens + warming_tokens ))
```

### Step 3 — Apply mode-aware cap (per 2.1)

Read current mode from `~/.lintel/profile.yaml`. Look up the cap from context-budget mode_envelopes:

```yaml
hotfix:              { soft: 200k, hard: 300k }
customer-engagement: { soft: 500k, hard: 750k }
research-dive:       { soft: 750k, hard: 900k }
demo-prep:           { soft: 300k, hard: 450k }
internal-tool:       { soft: 400k, hard: 600k }
```

### Step 4 — Surface verdict

```
HANDOFF SIZE CHECK — <mode> mode (cap: <soft>k soft / <hard>k hard)
══════════════════════════════════════════════════════════════════

Plan + trio:      <X>k tokens (~<%> of soft cap)
Warming projected: <Y>k tokens
TOTAL HANDOFF:    <Z>k tokens

Status:
  Z < soft  → ✅ GREEN — proceed
  soft ≤ Z < hard → ⚠ YELLOW — near cap, consider:
    - Split the plan (into 2 smaller phases)
    - Skip --skip-warming-<X> on lowest-priority warming target
    - Switch to research-dive mode (higher cap) if research-justified
  Z >= hard → ⛔ RED — exceeds cap, MUST reduce:
    - Plan is too broad → split now
    - Warming includes too many files → cut to essentials
    - Mode mismatch → consider research-dive

Suggested next step: <auto-recommendation>
```

Return code: 0 (green), 1 (yellow), 2 (red).

### Step 5 — Audit-log

One line via the unified writer (ts/operator/cycle_id come from the envelope):

```bash
source "${LINTEL_SOURCE_ROOT:-$(git rev-parse --show-toplevel)}/bin/_audit.sh"
audit_log handoff-size-checks size_check "plan=$PLAN_FILE" "mode=$mode" \
  "total_tokens=$total_tokens" "verdict=$verdict"
# → .claude/runtime/audit/handoff-size-checks.jsonl
```

## Status protocol

- **DONE** — check done, verdict green
- **DONE_WITH_CONCERNS** — yellow verdict (near cap warnings)
- **BLOCKED** — red verdict (exceeds cap) — operator must address before handoff
- **NEEDS_CONTEXT** — no plan file at default path and `--plan` arg missing

## Pause-points

- Red verdict: hard-block for operator decision (split / cut warming / abort handoff)
- Yellow verdict: surface options + ask whether to proceed (override OK with justification)
- Missing warming-manifest: assume warming = 0 + warn that the estimate may be low

## Integration

**Reads:**
- `.claude/runtime/state/plan.md` (or `--plan <path>` override)
- `.claude/runtime/state/spec.md`, `prompt.md` (cold-executor trio)
- `.claude/runtime/state/warming-manifest.md`
- `~/.lintel/profile.yaml` (current mode → cap)
- skills/context-budget/SKILL.md mode_envelopes

**Writes:**
- `.claude/runtime/audit/handoff-size-checks.jsonl`
- stdout (verdict report)
- Return code (CI/script consumption)

**Consumed by:**
- `/li:cycle` (auto-invocation post-PLAN)
- Operator (pre-handoff manual check)
- `/li:ship` (could integrate as a ship-gate)

## Anti-patterns

- **Auto-cut warming without operator-approval** — cap-violation surfaces options;
  operator decides which warming targets stay.
- **Override red verdict without justification-log** — `--override "<reason>"` logs
  intent. Silent bypass = future-debugging-pain.
- **Token-budget in bytes** — Lintel cap is in tokens. Convert at compute time.

## Failure recovery

- Plan-file unreadable: exit BLOCKED with diagnostic
- Mode unknown: fall back to customer-engagement defaults + warn
- Warming-manifest absent: assume 0 warming, surface "estimate may be low"

## Recommended next steps after invocation

- Green: proceed with cold-executor handoff
- Yellow: review the warming list for cut-candidates, consider splitting
- Red: address blocker (split / cut / mode-change), re-run check
- Pair with `/li:context-budget --report` for deeper headroom-analysis