Create Handoff

Generate a structured handoff document summarizing implementation work for the review pipeline.

Step 1: Determine the session name

Derive a session name from context:

If the user provided $ARGUMENTS, sanitize it to a safe kebab-case string (lowercase, strip any characters that aren't alphanumeric or hyphens, collapse multiple hyphens) and use that as the item name
Otherwise, infer from the current branch name (e.g. feature/issue-24-authentication → issue-24-authentication)
If on main/master, ask the user what to name the session

Step 2: Create the review session

Create the session directory and handoff file:

SESSION_DIR=".chalk/reviews/${session_name}"
HANDOFF_PATH="$SESSION_DIR/handoff.md"
mkdir -p "$SESSION_DIR"

If the handoff file already exists with content beyond the template, ask the user whether to overwrite or create a new timestamped session.

Step 3: Determine the base branch

Figure out what the current branch was based on:

Check for a merge base with main: git merge-base main HEAD
If that fails, try origin/main
If that fails, try master / origin/master

Store this as {base} for later steps.

Step 4: Gather context

Run these to understand the scope of changes:

git log --oneline {base}..HEAD
git diff --stat {base}..HEAD
git diff {base}..HEAD

Step 5: Detect and run project checks

Auto-detect the project's build/check tooling and run what's available. Check for these in order:

Node.js — if package.json exists:

Detect package manager: yarn.lock → yarn, pnpm-lock.yaml → pnpm, else npm
Run build: {pm} run build 2>&1 | tail -5
Run typecheck: {pm} run typecheck 2>&1 | tail -5 OR npx tsc --noEmit 2>&1 | tail -5
Run lint: {pm} run lint 2>&1 | tail -5
Run test: {pm} run test 2>&1 | tail -5

Rust — if Cargo.toml exists:

cargo check 2>&1 | tail -5
cargo test --no-run 2>&1 | tail -5
cargo clippy 2>&1 | tail -5

Go — if go.mod exists:

go build ./... 2>&1 | tail -5
go vet ./... 2>&1 | tail -5
go test ./... -short 2>&1 | tail -5

Python — if pyproject.toml or requirements.txt exists:

python -m py_compile on changed .py files
python -m pytest --co -q 2>&1 | tail -5 (collect only, don't run)

Make — if Makefile exists with build/check/test targets:

make build 2>&1 | tail -5
make check 2>&1 | tail -5
make test 2>&1 | tail -5

If no build system is detected, note "No build system detected — skipped automated checks".

Important: If any check fails, note the failure — do NOT try to fix it. The handoff should report the current state honestly.

Step 6: Write the handoff

Write to HANDOFF_PATH. Use this format:

# Handoff

## Scope
- Item: {item reference — e.g. "#24 — Add authentication" or "Refactor IPC layer"}
- Goal: {1-sentence summary of what was accomplished}

## What Changed
{bullet list of logical changes — describe WHAT each change does, not just file names}

## Files Changed
{bullet list of every file modified/created, from git diff --stat}

## Risk Areas
{bullet list of things that could break, have edge cases, or need careful review}

## Commands Run
{bullet list of every command run and its pass/fail status}

## Known Gaps
{bullet list of things NOT done — e.g. "no tests written", "error handling incomplete", "hardcoded values"}

## Suggested Focus For Reviewers
{bullet list of what reviewers should look at most carefully — prioritize by risk}

Step 7: Report to the user

Show:

The handoff file path
A brief summary of what was captured
Suggest next step: run /create-review to generate a review prompt for any AI reviewer

Rules

Do NOT modify any source code — this skill is read-only except for the handoff file
Be honest about failures — if build/typecheck fail, report that clearly
Keep descriptions concrete and actionable — avoid vague statements like "various improvements"
List ALL files from git diff --stat, don't summarize or skip any
If there are no commits ahead of base, warn the user that there's nothing to hand off

create-handoff