Git Checkpoint Commit Format

Use this structured format for all checkpoint commits during phased development.

Template

checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused/Blocked]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)
- path/to/another.tsx (what changed)

Next: [Concrete next action with file path + line number]

Examples

Phase Complete

checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)
- src/middleware/validate.ts (validation middleware)

Next: Phase 4 - Start building Task List UI component

Context Full Mid-Phase

checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints, need PATCH/DELETE

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)
- src/lib/schemas.ts (task schema)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47

Blocked or Paused

checkpoint: Phase 3 Paused - Need design decision

Phase: 3 - Tasks API
Status: Paused
Session: Built endpoints but need to decide on tag filtering approach

Files Changed:
- src/routes/tasks.ts (basic endpoints)

Next: Decide: client-side tag filtering or add SQL query parameter? Then resume at src/routes/tasks.ts:89

Bug Fix During Verification

checkpoint: Phase 3 In Progress - Fixed validation bug

Phase: 3 - Tasks API
Status: In Progress (Verification stage)
Session: Fixed invalid data returning 500 instead of 400

Files Changed:
- src/middleware/validate.ts (added try-catch for Zod errors)

Next: Continue verification - test PATCH and DELETE endpoints

Guidelines

Status Values:

Complete - Phase fully done, all verification passed
In Progress - Active work, may include stage (Implementation/Verification/Debugging)
Paused - Temporarily stopped, waiting for decision or external input
Blocked - Cannot proceed due to blocker (note blocker in Session field)

Session Field:

Focus on WHAT was accomplished, not HOW
Be specific enough for future resume
Include stage if not obvious (Verification, Debugging)

Files Changed:

List significant files only (not config changes)
Briefly note what changed in each file
Use relative paths from project root

Next Field:

MUST be concrete (file + line + action)
NOT vague ("Continue working on...")
Include decision points if relevant
File paths should be specific

Creating Checkpoints

When to checkpoint:

✅ End of phase (status: Complete)
✅ Context getting full mid-phase (status: In Progress)
✅ Pausing for user decision (status: Paused)
✅ Hitting a blocker (status: Blocked)

How to create:

# Stage changes
git add path/to/changed/files

# Commit with checkpoint format
git commit -m "$(cat <<'EOF'
checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints, need PATCH/DELETE

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)
- src/lib/schemas.ts (task schema)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47
EOF
)"

After checkpoint:

Update SESSION.md with checkpoint commit hash
Push to remote if desired
Clear context if needed
Resume from "Next" field when continuing

3.5 KiB Raw Blame History