Build Session Context

Quickly resume work by extracting key information from project logs and presenting a concise context summary for efficient session startup.

Goal

Extract essential information from multiple project documentation files and present a concise, token-efficient summary that enables quick context recovery without reading entire files.

Workflow

Step 1: Extract Key Information from Each File

Read each file and extract only the most critical information:

1. CLAUDE.md (Project Entry Point)

• Phase: Current project phase (e.g., "Phase 2 - Refactoring")

• Last Updated: Date of last update

• Project Status: High-level overview (e.g., "9/9 files migrated, 90% complete")

• Note: CLAUDE.md is now a clean entry point; detailed tasks are in TASK_BOARD.md

2. TASK_BOARD.md (Detailed Task Tracking)

• Completed Tasks: Count and 2-3 most recent

• In Progress Tasks: List (limit to 3 most important)

• Next Steps: Top 2-3 priorities

• Blockers: Any active blockers (critical)

• Progress Metrics: Overall percentages if available

3. MIGRATION_LOG.md (Migration History)

• Progress: X/9 files completed (percentage)

• Recent Migrations: Last 2-3 entries (date, title, status)

• Index: Check index for quick overview if available

4. DEBUG_LOG.md (Problem Tracking)

• Active Issues: Count and brief descriptions

• Recent Resolutions: Last 2-3 resolved issues

• Urgent Blockers: Any issues marked as critical

5. GIT_LOG.md (Change History)

• Recent Commits: Last 3-5 commits (hash, message)

• Activity Pattern: Type of recent work (features, fixes, docs)

• Last Commit Date: When was last work done

6. SKILLS_LOG.md (Skills Changes) [Optional]

• Recent Changes: Last 1-2 skill updates (if within last 7 days)

• New Skills: Any skills added recently

• Only include if skills changed recently to keep context minimal

7. Git Status (Current Workspace)

• Current Branch: Which branch is active

• Uncommitted Changes: Any staged/unstaged changes

• Untracked Files: New files not yet in git

Step 2: Generate Concise Context Summary

Format the extracted information into a compact summary:

🚀 Session Start - VRP Toolkit

Phase: [Phase] | Last Updated: [Date] | Branch: [branch]

📊 Status Snapshot

• Migration: X/9 files (XX%) | Active Issues: [count]
• Completed: [count] tasks | In Progress: [count] tasks
• Blockers: [None/list]

🔍 Recent Activity

Git: [Last 3 commits, one line each] Migrations: [Last 2 migration titles] Issues: [Active issue count, recent resolution]

🎯 Current Focus

1. [Primary in-progress task]
2. [Secondary in-progress task]

📋 Immediate Next Steps

1. [Highest priority next action]
2. [Secondary next action]

⚠️ Active Blockers (if any)

• [Blocker 1]
• [Blocker 2]

Token Optimization Guidelines:

• Keep total summary under 1000 tokens if possible

• Use abbreviations: e.g., "ALNS" not "Adaptive Large Neighborhood Search"

• Limit lists to 3-5 items maximum

• Use bullet points over paragraphs

• Prioritize recent information over historical

Step 3: Suggest Context-Aware Next Action

Based on the summary, recommend the most appropriate next step:

Decision Matrix:

• Blockers present → Address most critical blocker first

• Uncommitted changes → Review and commit before new work

• Active issues in DEBUG_LOG.md → Continue debugging if in progress

• Migration in progress → Continue with current migration

• No active tasks → Start highest priority from "Next Steps"

• Long break (>3 days) → Review recent commits first

Be specific and actionable:

• Instead of: "Work on migration"

• Use: "Continue migrating operators.py to vrp_toolkit/algorithms/alns/operators.py "

Step 4: Offer Skill Integration

After presenting summary, suggest relevant skills:

Common integrations:

• update-task-board

• Update task status if work completed

• git-log

• Commit uncommitted changes

• log-debug-issue

• Document issues encountered

• update-migration-log

• Log completed work

• migrate-module

• Continue file migration

Special Cases & Optimization

Long Log Files

When logs are very long (e.g., MIGRATION_LOG.md > 500 lines):

• Rely on index section if available

• Read only first/last few entries

• Use grep or search for recent dates

• Extract statistics rather than details

Missing Log Files

If a log file doesn't exist:

• Note its absence in summary

• Suggest creating it if needed

• Proceed with available information

First Session After Break

If last update > 3 days ago:

• Emphasize git history to rebuild context

• Highlight any stale in-progress tasks

• Suggest verifying environment/dependencies

High Token Count Situation

If summary is too long:

• Further trim lists (2 items instead of 3)

• Remove less critical sections

• Use more abbreviations

• Focus only on current/next actions

Integration with Project Documentation

TASK_BOARD.md: Detailed task status managed by update-task-board skill. This is the primary source for task tracking.

MIGRATION_LOG.md: Migration history maintained by update-migration-log skill. Provides evidence for task completion.

DEBUG_LOG.md: Issue tracking maintained by log-debug-issue skill. Source for active blockers.

GIT_LOG.md: Commit history maintained by git-log skill. Shows recent development activity.

SKILLS_LOG.md: Skills changes maintained by manage-skills skill. Optional context for recent workflow updates.

CLAUDE.md: High-level project overview (now simplified, points to other files for details).

Documentation Structure (post-refactoring):

• CLAUDE.md → Entry point (~308 lines reduced)

• TASK_BOARD.md → Task tracking (extracted from CLAUDE.md)

• SKILLS.md → Skills reference (extracted from CLAUDE.md)

• MIGRATION_GUIDE.md → Migration details (in migrate-module skill)

Example Output

🚀 Session Start - VRP Toolkit

Phase: Phase 2 - Refactoring (90% complete) | Last Updated: 2026-01-03 | Branch: main

📊 Status Snapshot

• Migration: 9/9 files (100%) | Active Issues: 0
• Tasks: 20+ completed | 1 in progress
• Blockers: None
• Skills: 10 total (recently refined documentation structure)

🔍 Recent Activity

Git: 4569fa1 feat(architecture): unified Solver interface 9590014 feat(setup): make package installable 0287f90 docs: comprehensive README Tasks: Test suite creation (in progress) Docs: CLAUDE.md simplified (~308 lines → dedicated files) Created TASK_BOARD.md, SKILLS.md, MIGRATION_GUIDE.md Skills: manage-skills created, manage-python-env fixed compliance

🎯 Current Focus

1. Creating comprehensive test suite for new architecture

📋 Immediate Next Steps

1. Complete test suite with edge cases and integration tests
2. Test ALNSSolver with other VRPProblem implementations

⚠️ Active Blockers

None - ready to proceed

💡 Suggested Action: Continue test suite development or start with update-task-board to sync latest progress

Reference

For detailed file structures:

• CLAUDE.md structure: claude_md_structure.md

• Log file formats: See respective skill documentation