handoff

Files (3)

• SKILL.md
• handoff-format.md · references/
• README.md · scripts/

SKILL.md (first lines)

# Handoff

The context-window evacuation skill.

Every long AI coding session eventually hits one of three walls: the conversation gets too long for the model's remaining window, the task scope expanded mid-session, or the chat got polluted with dead-ends and irrelevant tangents. The fix isn't "keep going and hope" — it's a clean handoff to a fresh chat that starts already loaded.

This skill turns that handoff into a one-block ritual instead of an improvised paste-job.

## When to Use This Skill

### User-triggered

Trigger when the user says any of:

- "handoff this", "prepare a handoff", "hand this off"
- "we're running out of context", "this is getting heavy", "fresh chat for this"
- "context window is getting full", "running long, let's migrate"
- "save state and move to a new session"

### AI-triggered (heuristic detection)

The AI should *proactively suggest* a handoff when it detects context pressure. Honest caveat: Claude does not have direct access to its own remaining token budget — these are heuristic signals:

- The conversation has crossed roughly 40–60 turns and the task isn't complete
- Many files (>10) have been read into context
- The task scope has expanded substantially since the original primer
- The user is reporting that the AI is "forgetting" earlier instructions
- The current response is approaching the model's typical max output length
- Tool/file references in the conversation are starting to be re-fetched repeatedly

When the AI suggests a handoff, it should phrase the offer briefly and explicitly:

> *"This conversation is getting long enough that I might start dropping earlier context. Want me to prepare a handoff block so we can continue cleanly in a fresh chat?"*

Wait for explicit user approval before proceeding. **Never produce a handoff block without confirmation.**

## How It Works (5-Step Protocol)

### Step 1 — Confirm the handoff with the user

If user-triggered: ask "scope to confirm — single feature, broader project, or just the immediate stuck point?"

If AI-triggered: state the reason, get user approval. Stop here if user says no.

### Step 2 — Ensure Prime is complete

A handoff without a loaded primer is just a TODO list — the new chat will start cold. Before producing the handoff block, verify:

- ✅ `~/ai-doctrine.md` exists and has a Default Primer filled in
- ✅ The current conversation has either run the `prime` skill OR the user has confirmed they want the new chat to read the doctrine directly

If Prime hasn't run in this session, invoke the `prime` skill first. The handoff block will then reference *which doctrine sections are load-bearing for this task* rather than re-pasting them inline.

### Step 3 — Extract handoff state

Examine the conversation and produce these sections (format defined in `references/handoff-format.md`):

1. **Mission** — one-sentence goal of the original task
2. **Locked decisions** — choices that are final, don't re-litigate
3. **Open questions** — items still pending the user's input
4. **What's done** — concrete artifacts produced so far (file paths, code, designs)
5. **What's next** — the immediate next 1–3 actions when the new chat resumes
6. **Doctrine pointers** — which `~/ai-doctrine.md` sections/rules are load-bearing
7. **Files in scope** — paths the new chat will need to read
8. **Estimated remaining effort** — rough size of the task that remains

### Step 4 — Render the handoff block

Wrap everything in a single fenced code block (so the user can copy-paste in one motion). The block must be:

- **Plain Markdown** — works in any AI chat (Claude, Cursor, ChatGPT, Codex, Gemini, Aider)
- **Self-contained** — does not require the new chat to read the old conversation
- **Doctrine-anchored** — points at `~/ai-doctrine.md` rather than embedding stale doctrine inline (the new chat reads the current doctrine fresh)
- **Action-oriented** — opens with "You are taking over from a long chat session..." style framing

### Step 5 — Deliver + offer doctrine save

Output the block to the user with one line of context:

> *"Paste this into a fresh chat (or a Claude session with a larger context window) and tell me what you want to ship next."*

Then offer:

> *💡 Doctrine candidate: should I save the handoff trigger you used here as a rule? (e.g., 'After 50+ turns on a refactor, always suggest handoff before continuing.')*

Save flow routes through `doctrine-keeper`. After the next `sync_to_agents.sh`, the same handoff discipline applies in Cursor / Copilot / Codex / Gemini / Windsurf.

## Files in This Skill

| File | Purpose |
| --- | --- |
| `SKILL.md` | This file |
| `references/handoff-format.md` | Canonical handoff block template with annotated example |
| `scripts/README.md` | Scripts placeholder |

## Operational Rules

1. **Never produce a handoff without explicit user approval.** The block is potentially long — surprise outputs waste the very context you're trying to save.
2. **Always run Prime first.** A handoff without a primer reference produces a cold new chat. If primer isn't loaded, invoke `prime` before continuing.
3. **One block, one paste.** Everything the new chat needs goes in a single fenced Markdown block.
4. **Reference doctrine, don't paste it.** Point at `~/ai-doctrine.md` sections by category and rule number. The new chat reads fresh rules.
5. **Lock decisions explicitly.** A handoff that doesn't mark locked decisions invites re-litigation in the new chat — which burns the context you just saved.
6. **Be honest about token estimation.** If the AI can't accurately estimate remaining context, say so. "I think context is getting heavy" beats "you have 12% left."
7. **Cross-tool by default.** The handoff format must work pasted into Cursor / Copilot / ChatGPT — not just Claude. Plain Markdown, no Claude-specific syntax.

## Doctrine Integration

Three save patterns produced by this skill:

1. **Trigger rules** — "When working on multi-file refactors >40 turns, always suggest handoff before continuing." (category: `Execute`)
2. **Format rules** — "In handoff blocks for security work, always include the threat-model section verbatim." (category: `Prime`)
3. **Anti-patterns** — "Don't try to summarize the whole conversation into the handoff — list locked decisions only. Burned 5k tokens on summary that the new chat didn't need." (category: `Trap`)

Save routes through `doctrine-keeper`. After `sync_to_agents.sh`, the same handoff playbook is loaded in every other AI tool.

## Position in the PURE Loop

When the `pure-orchestrator` is running a loop and detects context pressure, it invokes handoff **after Phase 1 (Prime) completes and before Phase 2 (Understand)**. The reasoning:

From AQaddora/pure-skill-suite, MIT.

More from AQaddora/pure-skill-suite