---
name: bilal140202/Context Hygiene & Session Management
source: https://app.decimal.ai/s/bilal140202-context-hygiene-session-management@1/SKILL.md
source_sha256: b7a528870a0c
---

# Context Hygiene & Session Management

## Purpose

AI context windows degrade as conversations grow. After ~30+ exchanges, the AI loses track of earlier constraints, starts hallucinating details, and wastes tokens re-reading irrelevant history. 

This skill teaches Anti-Gravity to actively manage session boundaries **automatically** — securing all progress to disk before the user moves to a clean chat window.

## When to Advise a Session Split

Recommend the user open a new chat window when:

1. **The task changes significantly.** If we finished debugging and are now building a new feature, that is a new session.
2. **The conversation exceeds ~30 exchanges.** Context quality degrades. Proactively say: "We've covered a lot. I recommend starting a fresh chat for the next piece so I stay sharp."
3. **Multiple unrelated tasks are being discussed.** Each task deserves its own clean context.
4. **A micro-task sequence is complete.** After finishing a planned set of tasks, suggest: "Good stopping point. For the next batch, a fresh session will give you better results."

## How to Execute a Handoff (The Zero-Friction Method)

Never ask Beloved to manually copy-paste a "Handoff Brief." Instead, perform these two steps automatically:

### Step 1: Secure Long-Term Knowledge (Memory)
Before suggesting a split, ensure all permanent knowledge from this session is written to disk:
- Did we make an architectural choice? Write it to `.agents/memory/decisions-log.md`.
- Did we learn what *not* to do? Write it to `.agents/memory/mistakes-to-avoid.md`.
- Did we establish a new convention? Write it to `.agents/memory/common-patterns.md`.

### Step 2: Secure Immediate State (Workflow)
Update `.agents/workflow-state.json` so the next session knows exactly where to resume. 
Ensure the `notes`, `key_decisions`, and `phases` fields are perfectly up to date.

*Reference format from `GLOBAL_MEMORY.md`:*
```json
{
  "workflow": "build-feature",
  "current_phase": "IMPLEMENT",
  "completion_pct": 64,
  "notes": "Finished the UI layout. Next session must focus on wiring the submit button to the API.",
  "key_decisions": ["Used Flexbox instead of Grid for the main container"],
  "blockers": []
}
```

### Step 3: Inform the User
Once the files are updated, tell Beloved:
> *"I've secured our progress in `workflow-state.json` and logged our decisions to Memory. This chat is getting long — I recommend opening a new chat window to continue. The new session will automatically read the state file and pick up exactly where we left off."*

## When NOT to Split

- In the middle of a single atomic task (don't interrupt flow)
- When the user is in a sprint and splitting would break momentum
- When the conversation is short and focused