---

name: handoff description: Prepare session handoff with git commit summary

Handoff

Prepare session handoff with git commit summary. Use at end of sessions to ensure clean git state and proper documentation.

Usage

/handoff # Prepare commit only (default) /handoff pr # Prepare commit + create pull request /handoff pr draft # Prepare commit + create draft PR

Argument provided: "$ARGUMENTS"

---

Step 0: Parse Arguments

Parse $ARGUMENTS to determine mode:

• Empty → Commit mode (prepare commit only)
• pr → PR mode (commit + create PR)
• pr draft → Draft PR mode (commit + create draft PR)

---

Step 1: Check Memory Bank Staleness

Read Current State

1. Parse timestamp from .claude/memorybank/session.md
2. Run git status to identify changes
3. Calculate time since last memory bank update

Determine Staleness Level

Handle Staleness

If Fresh or Minimal:

• For Minimal: Auto-append brief summary to session.md
• Continue to Step 2

If Significant:

Copy## Memory Bank Needs Update

Significant work detected since last documentation:
- Last updated: [timestamp] ([X] hours ago)
- Files changed: [N]
- New files: [list if any]

Run `/document` first to record progress, then `/handoff`.

Alternatively: `/handoff --force` to skip (not recommended)

Exit unless --force flag provided.

---

Step 2: Check Branch Status

Gather Branch Info

Copygit branch --show-current           # Current branch name
git rev-parse --abbrev-ref HEAD     # Confirm current branch
git log origin/main..HEAD --oneline # Commits ahead of main
git remote -v                       # Remote info

Branch Awareness

Main Branch Warning

If on main/master:

Copy⚠ Warning: You're on the main branch

Committing directly to main is not recommended. Options:
1. Create a feature branch: `git checkout -b feature/[name]`
2. Continue anyway (press Enter)
3. Cancel

Proceed with commit to main?

---

Step 3: Review Git Status

Gather Changes

Copygit status --porcelain              # Machine-readable status
git diff --stat                     # Change statistics
git diff --cached --stat            # Staged changes

Categorize Changes

Group by Type

Copy### Files Changed

**Modified** (3):
- src/auth/handler.py
- src/api/routes.py
- tests/test_auth.py

**Added** (1):
- src/auth/refresh.py

**Deleted** (0): None

---

Step 4: Determine Commit Scope

Scope Detection

Analyze changed files to determine scope:

Multi-Scope Handling

If changes span multiple scopes:

1. Use the primary scope (most significant change)
2. Or use parent scope if related (e.g., feat if adding feature + tests)

---

Step 5: Generate Commit Message

Format

Copy<scope>: <brief description>

- Detail 1 (if needed)
- Detail 2 (if needed)

Rules

Validation

Check commit message against rules:

• Scope is valid (feat/fix/refactor/docs/test/chore/style)
• First line ≤72 characters
• Uses imperative mood
• No trailing period
• Description is meaningful (not "update files")

---

Step 6: Present Handoff Summary (Commit Mode)

Output Format

Copy## Session Handoff

### Memory Bank Status
[✓ Current | ✓ Auto-updated | ⚠ Updated with brief summary]

### Branch
- **Current**: [branch-name]
- **Status**: [ahead/behind/up-to-date] with origin
- **Commits**: [N] commits ahead of main

### Changes Summary

| Type | Count | Files |
|------|-------|-------|
| Modified | [N] | [list] |
| Added | [N] | [list] |
| Deleted | [N] | [list] |

**Total**: [N] files changed, [+X/-Y] lines

### Suggested Commit

```bash
git add -A
git commit -m "$(cat <<'EOF'
<scope>: <description>

- Detail 1
- Detail 2
EOF
)"

Session Summary

Focus: [from session.md] Completed: [key items] Next: [from session.md next steps]

---

Ready to commit. Run the commands above or modify as needed.

Copy
---

## Step 7: PR Mode (`/handoff pr` or `/handoff pr draft`)

### Additional Steps for PR

After commit preparation:

1. **Check if branch is pushed**:
   ```bash
   git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null

1. Generate PR description from:

   • Session work (from session.md)
   • Commit messages on branch
   • Changes summary

2. Determine base branch:

   • Usually main or master
   • Check for develop if exists

PR Output Format

Copy## Pull Request Preparation

### Commits on Branch

git log origin/main..HEAD --oneline

Copy[List of commits]

### Suggested PR

**Title**: [scope]: [description from primary commit]

**Body**:
```markdown
## Summary
- [Key change 1]
- [Key change 2]
- [Key change 3]

## Changes
[Auto-generated from git diff --stat]

## Testing
- [ ] Tests pass locally
- [ ] Manual verification done

## Session Context
[Summary from session.md]

Commands

Copy# Stage and commit (if needed)
git add -A
git commit -m "<message>"

# Push branch
git push -u origin [branch-name]

# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
<body content>
EOF
)" [--draft]

---

Run the commands above to create the PR.

Copy
### Draft PR Flag

If `pr draft` mode:
- Add `--draft` flag to `gh pr create`
- Note in output: "Creating as draft PR"

---

## Do NOT

| Action | Reason |
|--------|--------|
| Execute git commands | User should review and run |
| Push to remote | User controls when to push |
| Create PR automatically | User should verify first |
| Include emoji in commit | Keep professional |
| Add Claude attribution | Not needed |
| Commit if significantly stale | Suggest `/document` instead |
| Force push | Never suggest `--force` |

---

## Error Handling

### No Changes to Commit

No Changes Detected

Working directory is clean - nothing to commit.

Options:

• Continue working and run /handoff when ready
• Check git status to verify

Copy
### Not a Git Repository

Git Error

Current directory is not a git repository.

Initialize with git init or navigate to a git repository.

Copy
### No Remote Configured (PR Mode)

Remote Required for PR

No remote repository configured.

Add a remote:

Copygit remote add origin <repository-url>
git push -u origin [branch-name]

Then run /handoff pr again.

Copy
### Uncommitted Changes with PR Mode

Uncommitted Changes

You have uncommitted changes. Commit first:

Copygit add -A
git commit -m "<message>"

Then run /handoff pr to create the pull request.

Copy
---

## Workflow Integration

### Standard Session End

/document → Record progress /logwork end → Close time tracking /handoff → Prepare commit [Execute commit commands]

Copy
### With PR Creation

/document → Record progress /logwork end → Close time tracking /handoff pr → Prepare commit + PR [Execute commands]

Copy
### Quick Handoff (Minimal Changes)

/handoff → Auto-updates if minimal staleness [Execute commit commands]

Copy
---

## Examples

### Example 1: Standard Commit

User: /handoff

Claude:

1. Checks session.md - updated 30 min ago ✓
2. Checks git status - 3 files modified
3. Detects scope: feat (new functionality)
4. Generates commit message
5. Presents handoff summary with commands

Copy
### Example 2: Stale Memory Bank

User: /handoff

Claude:

1. Checks session.md - updated 6 hours ago
2. Checks git status - 8 files changed, 2 new
3. Determines: Significant staleness
4. Shows warning, suggests /document first
5. Exits without commit preparation

Copy
### Example 3: PR Creation

User: /handoff pr

Claude:

1. Checks memory bank - current ✓
2. Checks branch - feature/auth-refresh
3. Finds 3 commits ahead of main
4. Generates PR title and body
5. Presents commit + push + PR commands

Copy
### Example 4: Main Branch Warning

User: /handoff

Claude:

1. Detects on main branch
2. Shows warning about direct commit to main
3. Suggests creating feature branch
4. Waits for user decision
5. Proceeds or exits based on response

Copy
---

## Commit Message Templates

### Feature

feat: add user authentication flow

• Implement JWT token generation
• Add login/logout endpoints
• Include refresh token support

Copy
### Bug Fix

fix: resolve login timeout issue

• Increase session timeout to 30 minutes
• Add keep-alive ping mechanism

Copy
### Refactor

refactor: restructure auth module

• Split handlers into separate files
• Extract common utilities
• No behavior changes

Copy
### Documentation

docs: update API documentation

• Add authentication section
• Include request/response examples

Copy
### Multiple Changes

feat: implement password reset flow

• Add reset request endpoint
• Create email notification service
• Add reset confirmation page
• Include rate limiting

Copy
---

## Checklist

- [ ] Checked memory bank staleness
- [ ] Handled staleness appropriately (proceed/auto-update/prompt)
- [ ] Checked current branch
- [ ] Warned if on main/master branch
- [ ] Gathered all git changes
- [ ] Categorized changes by type
- [ ] Determined appropriate scope
- [ ] Generated valid commit message
- [ ] Validated commit message format
- [ ] Presented clear handoff summary
- [ ] Included executable commands
- [ ] (PR mode) Generated PR title and body
- [ ] (PR mode) Included push and PR creation commands
- [ ] Did NOT execute any git commands