# Skill: Session State Management

*Reference knowledge for persisting, restoring, and reasoning about session state. Loaded by the orchestrator, session hooks, and the morning briefing workflow.*

---

## Purpose

Session state enables **seamless continuity without ceremony**. There are no pause/resume commands. The system auto-persists when the user leaves and auto-restores when they return. The experience should feel like returning to a conversation with someone who has good memory.

## What Gets Persisted

Every session exit (automatic or explicit) writes to `.planning/STATE.md`:

### Current Focus
The user's last active work area. This is the strongest signal for predicting what they'll do next.

- **What**: The feature, bug, or task they were working on
- **Where**: Which files were being modified
- **How far**: Rough progress (e.g., "backend done, frontend half-built")
- **What's next**: The immediate next step if they continue this work

### In-Progress Work
All active work items, each with:
- Reference to work directory (`.planning/work/NNN-slug/`)
- Completion status
- Last activity timestamp
- Next action needed

### Blocked Items
Anything that can't proceed, with:
- What's blocking it (missing decision, external dependency, prerequisite feature)
- When it was blocked
- What would unblock it

### Recently Completed
Last 3 sessions of completed work. Provides momentum context. Older items exist in LANDSCAPE.md and work archives.

### Pending Decisions
Decisions that were raised but not yet resolved:
- What the decision is about
- Where it came up (which work or conversation)
- What options exist
- What's waiting on the decision
- Urgency (what it blocks)

### Session Log
Brief log of last 5 sessions: date, duration, focus, outcome. Not a full transcript — just enough to see the pattern of recent work.

### Predicted Next Action
The system's best guess at what the user will want when they return, with:
- Primary prediction (most likely action)
- Confidence level
- Alternative prediction (second most likely)

## How to Initialize State (During /forge:init)

After init completes, write STATE.md with:
- **Focus area**: "None (just initialized)"
- **In Progress**: empty
- **Blocked**: empty
- **Recently Completed**: "Project initialization — domain model, architecture, decisions recorded"
- **Pending Decisions**: any that came up during init but weren't resolved
- **Session Log**: one entry for the init session
- **Predicted Next Action**: "User will likely want to start building. Suggest `/forge:build` or `/forge:idea`."

## How to Restore State (Session Start)

When the user returns:

1. **Read STATE.md** — load the full session state
2. **Check for external changes** — did any files change outside Forge? (git pull, manual edits)
3. **Compose a briefing** based on:
   - Current focus → "Last time you were working on X"
   - Blocked items → "Y is still blocked by Z"
   - Pending decisions → "You still need to decide about W"
   - Predicted action → frame the opening around this
4. **Don't dump everything** — present 2-3 most relevant items, offer details if they want

### Good Session Opening
> "Morning. Last session you were building the Tour planning drag-and-drop — the basic interaction works but Gewichtslimit validation on drop isn't in yet. You also had a pending decision about whether Teilladungen should be modeled as a separate entity. Want to continue with Tour planning or tackle that decision first?"

### Bad Session Opening
> "Here is the complete status: STATE.md shows focus area is Tour planning, there are 2 items in progress, 0 blocked, 1 recently completed, 1 pending decision, the session log has 3 entries..."

## How to Predict User Intent

Signals for prediction, roughly ordered by strength:

1. **Explicit statement**: User said "tomorrow I want to work on X" → highest confidence
2. **Interrupted work**: Something was in progress and not finished → very likely to continue
3. **Pending decisions**: Urgent decisions that block work → user may want to resolve these
4. **Recent momentum**: What's been the focus this week? → likely to continue in that direction
5. **Captured ideas**: Recent ideas that are fresh → might want to explore or build
6. **External events**: Demo coming up, customer meeting → priorities shift toward those

Confidence levels:
- **High**: Clear in-progress work that was interrupted mid-task
- **Medium**: Logical next step based on completed work and open items
- **Low**: No strong signals, multiple possible directions

## Auto-Persist Triggers

State should be persisted:
- When a build/fix/extend workflow completes
- When a decision is made
- When the user explicitly changes focus
- When a session ends (however detected)
- After any significant state change (new blocked item, work completed, etc.)

## Anti-Patterns

- **Don't over-persist**: STATE.md should be concise. If it grows beyond ~200 lines, prune old session log entries and completed items.
- **Don't persist conversation**: State captures *status*, not *dialogue*. "User was working on Tour planning" not "User said they wanted to add drag-and-drop to the tour screen."
- **Don't lose the thread**: If the user context-switches frequently, track the main focus AND note the interruptions. "Main focus: Tour planning. Also did: quick vehicle filter fix."
- **Don't predict too strongly**: Present predictions as suggestions, not assumptions. "I think you'll want to continue X — or would you rather do Y?" not "Continuing X now."
