context-handoff

This Skill references the upstream documents below at the revisions specified by its author. Author's declaration.

Referenced document 1

Source: glittercowboy/taches-cc-resources/commands/whats-next.md

Revision: 0d915b80b95f9889673e1dc6a9059ed239764cde

Attribution: TÂCHES. License: MIT.

Create a comprehensive, detailed handoff document that captures all context from the current conversation. This allows continuing the work in a fresh context with complete precision.

Instructions

PRIORITY: Comprehensive detail and precision over brevity. The goal is to enable someone (or a fresh Claude instance) to pick up exactly where you left off with zero information loss.

Adapt the level of detail to the task type (coding, research, analysis, writing, configuration, etc.) but maintain comprehensive coverage:

Original Task: Identify what was initially requested (not new scope or side tasks)
Work Completed: Document everything accomplished in detail
- All artifacts created, modified, or analyzed (files, documents, research findings, etc.)
- Specific changes made (code with line numbers, content written, data analyzed, etc.)
- Actions taken (commands run, APIs called, searches performed, tools used, etc.)
- Findings discovered (insights, patterns, answers, data points, etc.)
- Decisions made and the reasoning behind them
Work Remaining: Specify exactly what still needs to be done
- Break down remaining work into specific, actionable steps
- Include precise locations, references, or targets (file paths, URLs, data sources, etc.)
- Note dependencies, prerequisites, or ordering requirements
- Specify validation or verification steps needed
Attempted Approaches: Capture everything tried, including failures
- Approaches that didn't work and why they failed
- Errors encountered, blockers hit, or limitations discovered
- Dead ends to avoid repeating
- Alternative approaches considered but not pursued
Critical Context: Preserve all essential knowledge
- Key decisions and trade-offs considered
- Constraints, requirements, or boundaries
- Important discoveries, gotchas, edge cases, or non-obvious behaviors
- Relevant environment, configuration, or setup details
- Assumptions made that need validation
- References to documentation, sources, or resources consulted
Current State: Document the exact current state
- Status of deliverables (complete, in-progress, not started)
- What's committed, saved, or finalized vs. what's temporary or draft
- Any temporary changes, workarounds, or open questions
- Current position in the workflow or process

Write to whats-next.md in the current working directory using the format below.

Output Format

<original_task>
[The specific task that was initially requested - be precise about scope]
</original_task>

<work_completed>
[Comprehensive detail of everything accomplished:
- Artifacts created/modified/analyzed (with specific references)
- Specific changes, additions, or findings (with details and locations)
- Actions taken (commands, searches, API calls, tool usage, etc.)
- Key discoveries or insights
- Decisions made and reasoning
- Side tasks completed]
</work_completed>

<work_remaining>
[Detailed breakdown of what needs to be done:
- Specific tasks with precise locations or references
- Exact targets to create, modify, or analyze
- Dependencies and ordering
- Validation or verification steps needed]
</work_remaining>

<attempted_approaches>
[Everything tried, including failures:
- Approaches that didn't work and why
- Errors, blockers, or limitations encountered
- Dead ends to avoid
- Alternative approaches considered but not pursued]
</attempted_approaches>

<critical_context>
[All essential knowledge for continuing:
- Key decisions and trade-offs
- Constraints, requirements, or boundaries
- Important discoveries, gotcas, or edge cases
- Environment, configuration, or setup details
- Assumptions requiring validation
- References to documentation, sources, or resources]
</critical_context>

<current_state>
[Exact state of the work:
- Status of deliverables (complete/in-progress/not started)
- What's finalized vs. what's temporary or draft
- Temporary changes or workarounds in place
- Current position in workflow or process
- Any open questions or pending decisions]
</current_state>

Referenced document 2

Source: glittercowboy/taches-cc-resources/docs/context-handoff.md

Revision: 0d915b80b95f9889673e1dc6a9059ed239764cde

Attribution: TÂCHES. License: MIT.

Context Handoff for Claude Code

Create structured handoff documents to continue work in a fresh context without losing progress.

The Problem

You're deep in a conversation, made significant progress, but need to start a fresh chat (context getting full, switching tasks, or just want a clean slate). You lose all the context about what was done, what remains, and why decisions were made.

The Solution

/whats-next analyzes the current conversation and creates a structured handoff document (whats-next.md) in your working directory. In your next chat, reference it with @whats-next.md to continue seamlessly.

Command

`/whats-next`

Analyzes the conversation and creates a comprehensive handoff document with:

Original task - What was initially requested
Work completed - Everything accomplished in detail
Work remaining - Specific tasks still needed
Attempted approaches - What was tried (including failures)
Critical context - Decisions, constraints, discoveries
Current state - Exact status of deliverables

Output format:

<original_task>
Implement user authentication with JWT tokens
</original_task>

<work_completed>
- Created auth middleware in middleware/auth.ts:1-45
- Added JWT signing/verification in utils/jwt.ts:1-67
- Updated User model with password hashing in models/User.ts:23-34
- Created login endpoint in routes/auth.ts:12-56
</work_completed>

<work_remaining>
- Add token refresh endpoint in routes/auth.ts
- Implement logout (token blacklist) using Redis
- Add password reset flow (email + token verification)
- Write tests for auth middleware in tests/middleware/auth.test.ts
</work_remaining>

<attempted_approaches>
- Tried using session-based auth first but switched to JWT for statelessness
- Attempted to use Passport.js but found it overkill for this use case
</attempted_approaches>

<critical_context>
- Using jsonwebtoken library (already in dependencies)
- Tokens expire in 24h (configurable via JWT_EXPIRY env var)
- Password hashing uses bcrypt with 10 rounds
- Discovered: User.findByEmail returns null for missing users (handle this in routes)
- Redis connection required for token blacklist (not yet configured)
</critical_context>

<current_state>
- Auth middleware: Complete and tested
- JWT utils: Complete
- Login endpoint: Complete
- Token refresh: Not started
- Logout: Not started
- Password reset: Not started
- Tests: Not started
</current_state>

Why This Works

Preserves progress:

Exact file paths and line numbers for all work
Comprehensive work completed with reasoning
Clear remaining tasks with precise locations
Current state tracking for all deliverables

Prevents wasted effort:

Documents attempted approaches and failures
Captures dead ends to avoid repeating
Records what didn't work and why

Prevents scope creep:

Focuses only on completing the original request
Doesn't add new features or "nice to haves"
Maintains task boundaries across context switches

Transfers critical knowledge:

Key decisions and trade-offs made
Technical constraints and gotchas discovered
Environment details and assumptions
References to documentation consulted

Installation

Install globally - works in any directory:

cp whats-next.md ~/.claude/commands/

The command works everywhere. Each project gets its own whats-next.md in the working directory.

Usage

End of current conversation:

You: /whats-next
Claude: [Analyzes conversation, writes whats-next.md]
✓ Created whats-next.md - reference with @whats-next.md in a new chat to continue

Start of new conversation:

You: @whats-next.md continue this work
Claude: [Reads handoff document, understands context, resumes work]

Example Workflow

Conversation 1 (getting full):

You: "Build a user dashboard with real-time analytics"
Claude: [Works on task, creates components, sets up data fetching...]
You: /whats-next

✓ Created whats-next.md

Conversation 2 (fresh context):

You: @whats-next.md finish this
Claude: [Reads whats-next.md]
"I see we've completed the dashboard layout and real-time data
connection. Still need to add the chart components and error handling.
Continuing from src/components/Dashboard.tsx:67..."

File Structure

Global (install once):

~/.claude/commands/
  whats-next.md         # Command

Per-project (created when needed):

/your/project/
  whats-next.md         # Handoff document for this project

/another/project/
  whats-next.md         # Different project's handoff

Tips

Use /whats-next when context feels full or cluttered
Reference with @whats-next.md in new chats for seamless continuation
The file is overwritten each time - it's a snapshot, not a log
Delete whats-next.md when work is complete
Works great with /add-to-todos for long-term task tracking

Integration

Combine with todo management:

/whats-next for immediate continuation (same session/day)
/add-to-todos for longer-term backlog (weeks/months)

Use whats-next.md for "I'll finish this after lunch" and TO-DOS.md for "I'll get to this eventually."

Questions or improvements? Open an issue or submit a PR.

—TÂCHES