Balkonsen/build-session-context

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