goal-checkpoint

Goal Checkpoint

This skill provides structured goal tracking across sessions. When context fills up (~90%), it commits a checkpoint so the next session can resume exactly where this one left off.

When to Use

Invoke at the start of any non-trivial session where:

• The task spans multiple steps or files
• Work may not finish in one context window
• A clean resume in the next session is important

Trigger phrase: "use goal-checkpoint for this" or "/goal-checkpoint"

---

Phase 1: Goal Declaration (Session Start)

When invoked, immediately:

1. Ask for the goal

Ask the user:

"Describe the goal for this session. What should be accomplished, and what does 'done' look like?"

2. Write GOAL_STATE.md

Create (or overwrite) GOAL_STATE.md in the repo root:

# Goal State

## Goal
[User's stated goal, verbatim]

## Done When
[User's definition of done]

## Started
[ISO date-time]

## Status
in-progress

## Steps
- [ ] [Step 1]
- [ ] [Step 2]
...

## Completed Steps
(none yet)

## Context Notes
(key decisions, blockers, environment state)

## Resume From
(filled in at checkpoint — what to do first in the next session)

3. Initial commit

Stage and commit GOAL_STATE.md:

chore(goal): 🎯 start session — [one-line goal summary]

---

Phase 2: Progress Tracking (During Session)

As work progresses:

• After each significant step completes, move it from Steps to Completed Steps in GOAL_STATE.md and add a brief note.
• After any file is substantially changed, note it under Context Notes with a one-line description of its current state.
• Do not commit after every update — batch updates until a natural checkpoint.

---

Phase 3: Checkpoint Protocol (At ~90% Context)

When context approaches 90% (observed via system reminders about context compression, or when the conversation feels dense), trigger a checkpoint before responding to the next user message.

3.1 Assess current state

Before committing, determine:

• Which steps are complete vs. in-progress
• Which files have been modified and how
• What the very next action should be in the next session
• Any environment or tool state the next session needs to know