/state-save

Captures the current session state into two files that /state-load can restore in a future session.

Trigger phrases#

/state-save, save progress, save state, save my work, save session, I need to take a break, bookmark where I am, or before using /clear.

Do NOT use for: saving individual source files or committing to version control.

What it writes#

/state-save always writes two files:

• Docs/_working/state/SESSION_SNAPSHOT.json: machine-readable state across 6 taxonomy categories
• Docs/_working/state/SESSION_CONTEXT.md: human-readable narrative summary (max 100 lines)

Both files are read by /state-load on the next session.

The 6 state categories#

1. Tool state#

VCS information (branch, opened/modified files, pending changelists or commits), last build result (SUCCESS/FAILED/UNKNOWN), and whether Live Coding was used.

2. Task state#

Current goal, current checkpoint ID, completed checkpoints with pass/fail results, remaining checkpoints, and any blocked checkpoints awaiting playtest.

3. Artifact state#

Paths to modified source files, modified config files, Blueprint assets needing editor work, the current implementation plan, and updated wiki pages. File contents are not saved. Only paths and one-line descriptions.

4. Decision state#

Key choices made this session with rationale:

• Replication decisions (which properties replicate, OnRep vs RPC choices)
• GAS architecture decisions (ability class hierarchy, GameplayEffect design)
• Gameplay decisions (damage formulas, combo rules, tuning values)
• Workarounds for engine limitations
• Alternatives considered and rejected

5. Blocked state#

What is waiting on you or an external process:

• Playtest gates: checkpoint awaiting manual verification
• VCS submission: changes ready for human review
• Blueprint work: editor changes needed before code can continue
• Team dependencies: assets or levels awaiting another developer

6. Drift risk#

Files that could change externally while the session is paused. Shared headers teammates might modify, pending engine hotfix patches, Blueprint assets that depend on C++ classes you changed.

Archiving#

Before writing new state, /state-save archives the previous snapshot:

• Old SESSION_SNAPSHOT.json moves to Docs/_working/state/archive/SESSION_SNAPSHOT_<YYYY-MM-DD>.json
• Old SESSION_CONTEXT.md moves to a dated archive file
• Only the 3 most recent archives are kept; older ones are deleted
• compaction-*.md files older than 7 days are moved to the archive directory

Confirmation output#

State saved. X source files tracked, Y decisions recorded, Z items blocked.

When to use it#

Run /state-save before:

• Using /clear to compact context
• Ending a work session
• Starting a new unrelated task in the same session
• Any time you want a checkpoint you can return to

The /state-load skill reads these files and runs drift detection to warn you if VCS state has changed since the save.