start-session

name	start-session
description	Loads project context at the start of a work session. Use this skill whenever the user says "start session", "new session", "begin session", or similar. Always invoke proactively at the start of any session when the user indicates they are starting work on a project. Reads CLAUDE.md, SESSION.md, and TODO.md from the current working directory and produces a compact, actionable brief.

Start Session

The goal is to orient quickly — give enough context to work effectively without overwhelming with detail. Think of it as a smart handoff from the last session.

Step 1 — Check files exist

Look for these files in the current working directory:

• CLAUDE.md
• SESSION.md
• TODO.md
• .reference/INDEX.md (optional but recommended)

If any are missing, warn immediately:

⚠️ Missing: SESSION.md — no session history available
⚠️ Missing: TODO.md — no task list found

If CLAUDE.md is missing, note that the project may not be set up yet and suggest running the project-setup skill.

Step 2 — Read the files strategically

• CLAUDE.md — read in full (it's the master reference, usually concise)
• .reference/INDEX.md — if present, read in full; this is the evergreen lookup map
• TODO.md — read strategically:
  • ## Open Tasks — read in full (this is the canonical active work list)
  • ## Done — skip by default unless needed for clarification
• SESSION.md — read selectively:
  • KEY LEARNINGS section — read in full (critical gotchas, always relevant)
  • CHRONOLOGICAL LOG — read only the last 2-3 entries (recent = relevant)
  • Skip everything older — it's history, not context

SESSION.md can be hundreds of lines. Don't read it all — the gotchas and recent entries are what matter for orienting quickly.

Use .reference/ for stable operational/docs lookup context. Use .ai-notes/ only when a specific investigation timeline is needed.

Step 3 — Produce the session brief

Use this structure. Keep each section tight — no padding, no repetition.

## Session Ready — [Project Name]

**Project:** [What this project is + current status in 2-3 lines]

**Last session:** [What was done + any key decisions made — 2-3 lines]

**Key gotchas:**
- [Top 2-3 warnings from KEY LEARNINGS most relevant right now]
- [Only include ones that could actually affect today's work]

**Open tasks:**
1. [!] [Important task title]
  scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
2. [!] [Next urgent task title]
  scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
3. [ ] [Remaining open task title]
  scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD

**Suggested focus today:**
- [2-3 specific items Claude thinks deserve attention, based on context,
   recency, and what was left unfinished last session]

**Reference docs to use:**
- [0-3 relevant files from `.reference/INDEX.md` for likely lookup during this session]

Notes on judgment

• Gotchas: Don't list all of them — pick the ones most relevant to the current project state and recent work. If there are none that apply, skip the section.
• TODO structure: Assume one canonical ## Open Tasks section (urgent [!] first, then regular [ ]) and one ## Done section at the bottom.
• Task parsing: Prioritize next + updated when deciding suggested focus; these fields carry execution priority and recency.
• Suggested focus: Be specific. Not "continue work" but "check the AT workflow logs for the process fix that was left in progress last session."
• Missing context: If SESSION.md exists but has no recent entries, say so. If TODO.md is empty, say so. Don't pretend context exists when it doesn't.
• Tone: Direct and ready-to-work. No filler phrases like "Great, let's get started!" — just the brief.