# Session Discipline

Rules for maintaining continuity and quality across AI coding sessions.

## Session Start

1. **Read CLAUDE.md first.** It has the project state, architecture, and conventions.
2. **Check the latest session handoff** in `.claude/sessions/` for continuity from the previous session.
3. **One focused task per session.** Don't drift across unrelated domains. If scope grows, organize it — don't chase it.

## During Work

4. **Persist decisions to files, not conversation.** If it's only in chat history, it won't survive compaction or a fresh session.
5. **Don't verify context eagerly.** Only verify when about to ACT on data. Documentation drifts — trust it for reading, verify before executing.
6. **When the user cancels your action**, ask what they did. Don't save stale context from a cancelled operation.
7. **Credentials are in CLAUDE.md or .env files.** Don't ask the user for passwords that are already documented.
8. **When creating new scripts, tools, or changing how things work**, update CLAUDE.md immediately so future sessions know about it.

## Commit Discipline

9. **Push to your remote after meaningful changes.** Don't let work accumulate locally.
10. **Commit frequently** — after every completed function, bug fix, or test addition. Not in batches.

## Session End

11. **Before closing a session**, summarize what was learned and ask the user:
    - "Should anything from this session be saved to memory?"
    - "Did you cancel any of my actions and fix it yourself?" (if yes, note what they did)
    - "Is any context from this session wrong or stale?"

12. **Write a session summary** to `.claude/sessions/YYYY-MM-DD-HHMM.md` with:
    - Main task and outcome
    - Key decisions and why
    - What changed (files, commits)
    - What's left to do

## Handoff Documents

When a session ends with unfinished work, create `.claude/sessions/handoff-YYYYMMDD[-topic].md`:

```markdown
# Session Handoff — YYYY-MM-DD

## What Was Done
[Completed work, commits, key outcomes]

## Current State
[Branch, working tree, CI status, what's deployed/tagged]

## Next Steps (ordered)
[Exactly what the next session should do, with file paths and line numbers]
```

The handoff is the *start message* for the next session. Include only what the next session needs to be productive immediately — not a full history.

**When to create a handoff:**
- Context is running low and work remains
- Switching to a completely different task domain
- Before a planned fresh session
- User requests a continuation message

**When NOT to create a handoff:**
- Work is complete (commit messages suffice)
- Remaining work is trivially discoverable from git status