Bootstrap Prompt Generator

Generate a detailed context prompt that enables seamless continuation of work in a fresh Claude Code session.

Purpose

Sessions accumulate valuable context: task understanding, decisions made, patterns discovered, gotchas encountered, and progress achieved. When starting fresh, this knowledge is lost. A bootstrap prompt preserves the essential context needed to continue effectively.

Core Principle: Intelligent Context Selection

Do NOT mechanically dump everything. Analyze what actually matters for continuation:

• What would confuse a fresh Claude? Include it.

• What decisions took deliberation? Document the reasoning.

• What gotchas caused wasted time? Warn about them.

• What's the critical path forward? Clarify it.

Omit: routine operations, obvious context, resolved dead-ends, standard patterns.

Analysis Process

1. Assess Session Significance

Determine what kind of work occurred:

• Exploration: Learning codebase, investigating options

• Implementation: Building features, fixing bugs

• Debugging: Tracking down issues, testing hypotheses

• Planning: Designing architecture, making decisions

Each type has different handoff needs.

2. Identify Essential Context

Project State

• Working directory and project identity

• Tech stack if non-obvious

• Branch and git state (use scripts/gather-git-state.sh )

Task Context

• Original objective (what the user asked for)

• Current interpretation (what we understood it to mean)

• Scope decisions (what's in/out)

Progress Assessment

• What's completed and working

• What's in progress and current state

• What's remaining (check todo list)

• What's blocked and why

Critical Knowledge

• Architectural decisions and their rationale

• Patterns established in this session

• Gotchas and workarounds discovered

• Files that are central to the work

Next Actions

• Immediate next step

• Remaining work outline

• Known unknowns to investigate

3. Determine Depth

Scale detail to session complexity:

Light session (quick task, simple fix): Brief summary, next step Medium session (feature work, debugging): Key decisions, progress, gotchas Deep session (architecture, complex debug): Full context with reasoning

Output Format

Generate a markdown document structured as a prompt for a fresh session:

Bootstrap: [Brief Task Description]

Generated: [timestamp] Project: [project path] Branch: [branch name]

Context

[2-4 sentences on what this project/task is about]

Session Summary

[What happened in the session - decisions, progress, discoveries]

Current State

[Where things stand right now - what works, what's in progress]

Key Files

[List of files central to the work with brief descriptions]

Decisions Made

[Important choices with brief rationale - only if non-obvious]

Gotchas & Warnings

[Things that caused problems or need careful handling]

Next Steps

[Prioritized list of what to do next]

Resume Instructions

[Specific guidance on how to continue - commands to run, files to open, etc.]

Omit sections that aren't relevant. A simple task might only need Context, Current State, and Next Steps.

Execution Steps

• Analyze the session - Review conversation, understand what happened

• Run git state script - Execute scripts/gather-git-state.sh to capture repository state

• Check todo list - Review current todos for progress context

• Identify key files - Determine which files are central to the work

• Draft bootstrap prompt - Write the document following the format above

• Determine output path - Use .claude/handoffs/{project-name}-{YYYYMMDD-HHMMSS}.md

• Save the file - Write the bootstrap prompt to the handoffs directory

• Copy to clipboard - Execute scripts/copy-to-clipboard.sh {filepath} to copy contents

File Locations

• Output directory: .claude/handoffs/ (create if doesn't exist)

• Filename pattern: {project-name}-{YYYYMMDD-HHMMSS}.md

• Project name: Derive from git remote, directory name, or package.json

Scripts

scripts/gather-git-state.sh

Collects repository state: branch, recent commits, uncommitted changes, modified files. Run this first to include accurate git context in the bootstrap prompt.

scripts/copy-to-clipboard.sh

Copies file contents to system clipboard (macOS pbcopy ). Run after saving the bootstrap prompt file.

Quality Checklist

Before finalizing, verify:

• Fresh Claude could understand the task without prior context

• Decisions include enough rationale to avoid re-litigating

• Gotchas are specific enough to be actionable

• Next steps are concrete and prioritized

• No unnecessary detail that obscures the important parts

Example Bootstrap Prompts

Light Session Example

Bootstrap: Fix API rate limiting bug

Generated: 2025-01-15 14:30 Project: /Users/dev/acme-api Branch: fix/rate-limiter

Context

Fixing a bug where rate limiting wasn't being applied to the /search endpoint.

Current State

Found the issue - the rate limiter middleware was added after the route registration. Fix is ready but untested.

Next Steps

1. Run test suite: npm test
2. If passing, commit with message "Fix rate limiter middleware order for /search"

Deep Session Example

See references/deep-session-example.md for a complex multi-day project handoff.