/create

Any AI coding agent can pick up this work seamlessly — capture everything needed to resume without losing momentum.

Determine Target File

Check $ARGUMENTS:

• If non-empty: write to HANDOFF-$ARGUMENTS.md (replace spaces with hyphens automatically)
  • Exception: if $ARGUMENTS is auto, refuse and ask the user to choose a different name — auto is reserved for compaction auto-saves
• If empty: write to HANDOFF.md

Examples:

• /handoff:create payments → writes HANDOFF-payments.md
• /handoff:create auth refactor → writes HANDOFF-auth-refactor.md
• /handoff:create → writes HANDOFF.md

Gather Context First

Run these commands to capture current repo state:

Command	What it tells you
git status	Uncommitted changes
git diff --stat	Which files changed
git log --oneline -5	Recent commits from this session
git rev-parse --short HEAD	Short commit hash to pin exact repo state

Review the conversation history and extract:

• Task/Goal: The original task or goal
• Completed: What was finished
• Failed Approaches: What was tried and didn't work — critical, saves hours
• Decisions: Key choices and their rationale
• Preferences: Opinions and preferences the user expressed during the session
• Errors: Any errors that surfaced and how each was resolved

Guidelines

• Dead Ends table is mandatory — every abandoned approach must have a row; write "None" in the first column only if nothing failed
• Key Decisions table is mandatory — populate with any choice where two or more approaches were considered; if no decisions were made this session, write a single row with — in the Decision column and "No decisions made this session" in the Chosen approach column; never leave placeholders unfilled
• Show code, don't describe - include actual signatures, interfaces, response shapes
• Testing steps need expected outcomes - "verify it works" is useless
• Trim ruthlessly — include only what earns its place
• Paste error messages verbatim when relevant
• Use file paths relative to the repo root
• Highlight blockers so they are impossible to miss
• Drop empty sections (except Dead Ends — write "None" in the first column if truly nothing failed)
• Set Confidence to High if tests passed or the feature was manually confirmed working; Medium if the last action succeeded but wasn't verified; Low if there are unresolved errors

Produce HANDOFF.md

Follow this structure (leave out empty sections, but NEVER omit the Dead Ends table if any approaches failed):

# Handoff: [Brief Task Title]

**Generated**: [date/time]
**Branch**: [git branch]
**Commit**: [output of `git rev-parse --short HEAD`]
**Status**: [In Progress / Blocked / Ready for Review]
**Confidence**: [High / Medium / Low]

## Goal

[1-2 sentences: what the user wants to achieve]

## Completed

- [x] [Specific completed item]
- [x] [Another completed item]

## Not Yet Done

- [ ] [Remaining task - be specific]
- [ ] [Another remaining task]

## Dead Ends (Do Not Retry)

| What was tried | Why it failed | What replaced it |
|---------------|---------------|-----------------|
| [approach] | [specific error or flaw] | [current solution] |

## Key Decisions

| Decision | Chosen approach | Rejected alternative | Reason |
|----------|----------------|---------------------|--------|
| [what was decided] | [what we went with] | [what we didn't do] | [why] |

## Current State

**Working**: [What's functional right now]

**Broken**: [What's not working, error messages if relevant]

**Unsaved Changes**: [Summary of unstaged/staged changes]

## Files to Know

| File | Why It Matters |
|------|----------------|
| `path/to/key/file.ts` | [Brief description] |

## Code Context

[Include actual code the next agent needs. Don't describe it - show it:]

**Key interfaces/signatures** (so the agent knows how to call/modify them):
```typescript
// Hook signature - src/hooks/useCheckout.ts
function useCheckout(): {
  session: Session | null;
  charge: (priceId: string, card: CardDetails) => Promise<void>;
  isLoading: boolean;
}

API request/response shapes (if backend work):

// POST /api/payments/create-intent - example response
{ "clientSecret": "pi_3N..._secret_...", "publishableKey": "pk_test_..." }

Non-obvious logic (anything tricky that isn't self-documenting)

Resume Instructions

[Be extremely specific. Don't just say "test the feature"; give step-by-step instructions with expected outcomes:]

1. [Setup step if needed - migrations, env vars, etc.]
2. [First action with exact command or file to edit]
3. [Verification step with expected outcome]
   • Expected: [what should happen]
   • If it fails: [what to check]

Example:

1. Run alembic upgrade head to apply migrations
2. Start server: ./start.sh
3. Test payment flow: POST to /api/payments/create-intent with price_test_abc123 and card 4242 4242 4242 4242
   • Expected: 200 response with { clientSecret: "pi_..." }
   • If 400: Check that STRIPE_WEBHOOK_SECRET is set in .env

Setup Required

[Only if there are prerequisites the next agent needs:]

Prerequisite	Example
Environment variables	STRIPE_WEBHOOK_SECRET, DATABASE_URL
Test data	price_test_abc123, Stripe test card 4242 4242 4242 4242
Required services	Redis on :6379, Stripe CLI for local webhook forwarding

Edge Cases & Error Handling

[Document known edge cases and how they're handled - or should be:]

• What happens if [X fails]? → [current behavior or "not handled yet"]
• What if user does [Y]? → [expected behavior]

Warnings

[Gotchas, things that look wrong but are intentional, or traps to avoid]

Write to the target file determined in "Determine Target File" above.