s-pause

name	s-pause
description	Save current work state for later resumption - creates checkpoint with context for /s:resume

/s:pause - Work State Checkpoint

Save the current working state so that /s:resume can fully reconstruct context in a future session. This skill captures everything that would be lost between sessions: what was being done, what files were being touched, and what comes next.

Instructions

Step 1: Check for project initialization

Check if .planning/STATE.md exists.

If it does NOT exist:

• Display: "No project state found. Run /s:new to initialize a project first."
• Stop here.

Step 2: Read current state

Read .planning/STATE.md to understand:

• Current status
• Active phase and task
• Existing blockers and decisions

Step 3: Assess uncommitted work

Run:

1. git status --short - List all modified, staged, and untracked files
2. git diff --stat - Summary of changes in tracked files
3. git diff --cached --stat - Summary of staged changes

Categorize the results:

• Files with staged changes (ready to commit)
• Files with unstaged changes (modified but not staged)
• Untracked files (new files not yet added)

Step 4: Gather current work context

Ask the user (if not obvious from context):

• "What are you currently working on?" (or infer from recent conversation)
• "Any open questions or blockers?" (or infer from recent conversation)

If the conversation context makes it clear what was being worked on, do NOT ask - just infer it. The goal is minimal friction.

Step 5: Update STATE.md

Update .planning/STATE.md with the following additions:

• Set Last Updated to today's date
• Update Current Focus section with a description of work in progress
• Add any new blockers to the Blockers section
• Add a decision entry: "{DATE} | Work paused | Checkpoint for session resume"

Do NOT overwrite existing content in STATE.md. Append or update specific fields only.

Step 6: Create .continue-here.md

Create .continue-here.md at the project root with the following structure:

# Continue Here

**Paused:** {current date and time}
**Session context:** {brief description of what this session accomplished}

## What Was Being Done

{Clear description of the task/feature/fix in progress}
{Include enough context that a fresh session can understand without history}

## Files Being Modified

{List each file that has uncommitted changes, with a note about what was being done to it}
- `path/to/file.ts` - {what was being changed and why}
- `path/to/test.ts` - {test status: passing/failing/incomplete}

## Current State

{Where in the process: writing tests? implementing? debugging? refactoring?}
{If TDD: which phase - RED (test written, failing), GREEN (minimal impl), REFACTOR?}

## Open Questions

{Any unresolved questions or decisions that need to be made}
{Things the user was thinking about but hadn't decided yet}

## Next Steps

1. {First thing to do when resuming}
2. {Second thing}
3. {Third thing}

## Blockers

{Any blockers, or "None"}

Step 7: Handle uncommitted changes

If there are uncommitted changes (staged or unstaged), display a warning:

WARNING: You have uncommitted changes in {N} files.
Consider committing before ending your session:
  git add -A && git commit -m "wip: {description of work in progress}"

Do NOT automatically commit. Just suggest it. The user decides.

If the working tree is clean, skip this step.

Step 8: Confirm pause

Display the confirmation:

=== WORK PAUSED ===

State saved to:
  - .planning/STATE.md (updated)
  - .continue-here.md (created)

{If uncommitted changes: "Uncommitted changes in {N} files - consider committing."}

Run `/s:resume` in your next session to continue where you left off.

Important Notes

• This skill WRITES to STATE.md and creates .continue-here.md. These are its only side effects.
• Be generous with context in .continue-here.md. Future-you has no memory of this session.
• Include file paths as absolute or project-relative paths, never ambiguous names.
• If the user provides explicit "next steps" in conversation, capture those verbatim.
• The .continue-here.md file is temporary - /s:resume will delete it after reading.
• Do NOT delete or overwrite existing decisions/blockers in STATE.md. Only append.
• Keep the tone factual and direct. This is a checkpoint, not a summary report.